js-locations

A Node.js library for accessing country, state, and city data

This library provides functions to retrieve information about countries, states, and cities from a provided JSON data file. It allows you to search for specific data points, including phone codes and currency symbols.

npm install js-locations

Usage

1. Import the Library

import countries from "js-locations";

2. Access Data:

The library provides a single function getCountryData to retrieve information based on different parameters.

• getCountryData(option): This function takes an options object as a parameter and returns an array of matching entries.

Available options for searching:

• country: Search by country name (string).
• state: Search by state name (string).
• city: Search by city name (string).
• phone_code: Search by phone code (string).
• currency_symbol: Search by currency symbol (string).

Examples

• Get all countries:

const allCountries = countries.getCountryData();
console.log(allCountries);

• Get a specific country by name:

const usaData = countries.getCountryData({ country: 'United States' });
console.log(usaData);

• Find cities within a state:

const californiaCities = countries.getCountryData({ state: 'California' });
console.log(californiaCities.map(city => city.city)); // Extract city names

Data File

This library expects a JSON data file containing an array of country objects. Each country object should have the following properties:

• id: The id of the country (number).
• name: The full name of the country (string).
• iso2: The ISO 2-letter code for the country (string). (Optional)
• iso3: The ISO 3-letter code for the country (string). (Optional)
• phone_code: The country's phone code (string). (Optional)
• currency: The country's currency code (string). (Optional)
• currency_symbol: The currency symbol used in the country (string). (Optional)
• states: An array of state objects (optional). Each state object should have the following properties:
  • id: The id of the city (number).
  • name: The full name of the state (string).
  • cities: An array of city objects (Optional). Each city object should have the following properties:
    • id: The id of the city (number).
    • name: The full name of the city (string).

Note: You need to provide your own JSON data file following the described format. The library doesn't include any pre-populated data.

Contribution

We welcome contributions to improve this library. Feel free to submit pull requests with bug fixes, enhancements, or additional features.

License

This library is licensed under the ISC License. See the LICENSE file for details.