js-locations/ReadME.md

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

# 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

```javascript
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:

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

- Get a specific country by name:

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

- Find cities within a state:

```JavaScript
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.