🌍 Location Hub

A lightweight and efficient utility library to fetch Countries, States, Districts, Country Codes, and Currency Codes.

This library is perfect for:

• Dynamic location-based dropdowns
• Country/state/district pickers
• Phone number country code selection
• Payment flow currency selection
• Data‑driven applications

📦 Installation

npm install location-hub
# or
yarn add location-hub

🔧 Usage

Import the functions you need:

import {
  getAllCountry,
  getStatesByCountry,
  getDistrictByState,
  getAllCountryCode,
  getAllCurrencyCode,
  getCountryStdCode,
} from "location-hub";

🚀 Available Functions

1️⃣ getAllCountry()

Returns all countries.

Example:

const countries = getAllCountry();
console.log(countries);

Country Object:

{
  "countrycode": 101,
  "countryname": "India",
  "stdcode": 91,
  "shortnm": "IN"
}

2️⃣ getStatesByCountry(countryCode: number)

Fetch all states belonging to a specific country.

Example:

const states = getStatesByCountry(101); // 101 = India
console.log(states);

State Object:

{
  "countryID": 101,
  "stateID": 33,
  "stateName": "Kerala"
}

If no states found:

{
  "message": "No states found",
  "countryCode": 999
}

3️⃣ getDistrictByState(countryID: number, stateID: number)

Returns districts for a given country & state.

Example:

const districts = getDistrictByState(101, 33); // India → Kerala
console.log(districts);

District Object:

{
  "countryID": 101,
  "stateID": 33,
  "cityID": 551,
  "cityName": "Kochi"
}

If no districts found:

{
  "message": "No states found",
  "countryID": 101,
  "stateID": 33
}

4️⃣ getAllCountryCode()

Returns all country calling codes.

Example:

const codes = getAllCountryCode();
console.log(codes);

Country Code Object:

{
  "country": "India",
  "code": "+91"
}

5️⃣ getAllCurrencyCode()

Returns all currency codes.

Example:

const currencies = getAllCurrencyCode();
console.log(currencies);

Currency Object:

{
  "country": "India",
  "currency": "INR"
}

6️⃣ getCountryStdCode(code: number)

Returns STD calling code details for a country.

Example:

const std = getCountryStdCode(101);
console.log(std);

STD Object:

{
  "countrycode": 101,
  "countryname": "India",
  "stdcode": 91,
  "shortnm": "IN",
  "countryLogo": "🇮🇳"
}

⚠️ Error Handling

All functions return a readable fallback object when no data is found:

{
  "message": "No states found",
  "countryCode": 999
}

🎯 Ideal For

• Country / State / District dropdowns
• Forms & user onboarding flows
• E‑commerce checkout
• Payment gateways
• Multi‑country apps
• Mobile number input with country codes

📄 License

MIT © Joyal Shaji 2025

Made with ❤️ for developers who need clean location data.