🌍 full-countries-states-cities package

Welcome to the Location Data Package! This package provides well-formatted, all-English data on countries, states, and cities, including projection and pagination support for efficient data retrieval. It can be easily integrated into any project and includes a wide range of features for working with geographical data.

📦 What's Included

This package includes the following features:

1. Country Data: Retrieve information on all countries, with optional projection for specific fields.
2. State Data: Get details on states within a specific country, with support for pagination and field projection.
3. City Data: Fetch cities based on country ISO codes, with the ability to filter by state and use pagination.
4. Field Projection: Specify which fields you want returned (e.g., only name and iso).
5. Pagination: Easily control how many items are returned and navigate through large datasets.
6. All the names that should be in english are cleared from unknown symbols!

📚 How to Use

Installation

First, install the package using npm:

npm install full-countries-states-cities

Importing Functions

You can import the available functions like so:

import {
    getCountries,
    getCountry,
    getStates,
    getCities
} from 'full-countries-states-cities'

Easy as that

getCountries() function will give u back:

{
    "id": 1,
    "name": "Afghanistan",
    "iso3": "AFG",
    "iso2": "AF",
    "numeric_code": "004",
    "phone_code": "93",
    "capital": "Kabul",
    "currency": "AFN",
    "currency_name": "Afghan afghani",
    "currency_symbol": "؋",
    "tld": ".af",
    "native": "افغانستان",
    "region": "Asia",
    "region_id": "3",
    "subregion": "Southern Asia",
    "subregion_id": "14",
    "nationality": "Afghan",
    "timezones": [
        {
            "zoneName": "Asia/Kabul",
            "gmtOffset": 16200,
            "gmtOffsetName": "UTC+04:30",
            "abbreviation": "AFT",
            "tzName": "Afghanistan Time"
        }
    ],
    "translations": {
        "kr": "아프가니스탄",
        "pt-BR": "Afeganistão",
        "pt": "Afeganistão",
        "nl": "Afghanistan",
        "hr": "Afganistan",
        "fa": "افغانستان",
        "de": "Afghanistan",
        "es": "Afganistán",
        "fr": "Afghanistan",
        "ja": "アフガニスタン",
        "it": "Afghanistan",
        "cn": "阿富汗",
        "tr": "Afganistan"
    },
    "latitude": "33.00000000",
    "longitude": "65.00000000",
    "emoji": "🇦🇫",
    "emojiU": "U+1F1E6 U+1F1EB",
    "iso": "AF"
}

Available Functions

1. getCountries

Retrieve a list of all countries with support for pagination and field projection.

const result = getCountries({ page: 1, limit: 10, project: ['name', 'iso'] });
console.log(result.countries); // Array of countries with 'name' and 'iso' fields

Parameters:

• page: Page number (default: 1)
• limit: Number of countries per page (set to 0 to retrieve all)
• project: Array of fields to return (optional)

2. getCountry

Retrieve full details of a specific country by its ISO code.

const country = getCountry('US');
console.log(country); // Returns the details for the country with ISO code 'US'

Parameters:

• isoCode: ISO 3166-1 alpha-2 code of the country.

3. getStates

Retrieve a list of states within a country, with support for pagination and field projection.

const result = await getStates({
    isoCode: 'US',
    limit: 5,
    page: 1,
    project: ['name', 'abbreviation']
});
console.log(result.states); // Array of states with 'name' and 'abbreviation' fields

Parameters:

• isoCode: ISO 3166-1 alpha-2 code of the country.
• page: Page number (default: 1)
• limit: Number of states per page (set to 0 to retrieve all)
• project: Array of fields to return (optional)

4. getCities

Retrieve a list of cities within a country, with optional filtering by state, pagination, and field projection.

const result = await getCities({
    isoCode: 'US',
    state: 'California',
    limit: 10,
    project: ['name', 'population']
});
console.log(result.cities); // Array of cities in California with 'name' and 'population' fields

Parameters:

• isoCode: ISO 3166-1 alpha-2 code of the country.
• state: Optional state name to filter cities by.
• page: Page number (default: 1)
• limit: Number of cities per page (set to 0 to retrieve all)
• project: Array of fields to return (optional)

🔄 Pagination Support

For endpoints that support pagination, you can control the number of results and navigate through pages.

• page: The current page number (starting from 1).
• limit: Number of results per page.

Example: Fetch the second page of states for the United States, with a limit of 5 states per page:

const result = await getStates({ isoCode: 'US', page: 2, limit: 5 });
console.log(result.pagination); // Pagination info including current page, total pages, etc.

Example Pagination Response:

{
    "states": [],
    "pagination": {
        "totalStates": 50,
        "totalPages": 10,
        "currentPage": 2,
        "hasMore": true
    }
}

🛠️ Example Usage

Fetching Countries with Field Projection

const countries = getCountries({ limit: 5, project: ['name', 'iso'] });
console.log(countries);

Fetching Cities by Country and State

const cities = await getCities({
    isoCode: 'US',
    state: 'California',
    limit: 10
});
console.log(cities);

Fetching States with Pagination

const states = await getStates({ isoCode: 'US', page: 2, limit: 5 });
console.log(states);

📝 Notes

• The project parameter can be used to limit the fields returned, reducing payload size and improving performance.
• Pagination parameters allow you to control the number of results returned and navigate through large datasets.