Table of contents

1. Mission
2. Getting started
   • Installation
   • Import
3. Usage
   • Countries
   • States
   • Cities
4. Contributors
5. Need help
6. Licence
7. Sponsor

Mission

• I've never found any complete library to get all world countries, states, and cities. I want to develop the best one. Of course, contributors are welcome!!
• I took this data as a starting point.

Getting started

To get started with this library, you need to install it and add it to your project.

Installation

Countries States Cities Service is available as an npm package.

1# npm
2npm install countries-states-cities-service
3
4# yarn
5yarn add countries-states-cities-service

Import

Import single named import as follow:

1import { Countries, States, Cities } from 'countries-states-cities-service'

Usage

The code snippet below shows how to put into action countries-states-cities-service in some common use cases.

• Countries
• States
• Cities

Countries

• Get all countries.

1const countries = Countries.getCountries()

• Get all countries by asc sort.

1const countries = Countries.getCountries({
2  sort: {
3    mode: 'asc',
4  },
5})

• Get all countries by desc sort.

1const countries = Countries.getCountries({
2  sort: {
3    mode: 'desc',
4  },
5})

• Get all countries by alphabetical sort.

1const countries = Countries.getCountries({
2  sort: {
3    mode: 'alphabetical',
4    key: 'iso2',
5  },
6})

• Get all countries with localization.

1const countries = Countries.getCountries({ locale: 'it' })

• Get a country by iso2 code.

1const countries = Countries.getCountries({ filters: { iso2: 'US' } })

• Get a country by iso2 code and localization.

1const countries = Countries.getCountries({
2  filters: { iso2: 'IT' },
3  locale: 'it',
4})

• Get a country by iso3 code.

1const countries = Countries.getCountries({ filters: { iso3: 'ITA' } })

States

• Get all states.

1const states = States.getStates()

• Get all states by asc sort.

1const states = States.getStates({
2  sort: {
3    mode: 'asc',
4  },
5})

• Get all states by desc sort.

1const states = States.getStates({
2  sort: {
3    mode: 'desc',
4  },
5})

• Get all states by alphabetical sort.

1const states = States.getStates({
2  sort: {
3    mode: 'alphabetical',
4    key: 'name',
5  },
6})

• Get all states with localization.

1const states = States.getStates({ locale: 'it' })

• Get states by country code.

1const states = States.getStates({ filters: { country_code: 'IT' } })

• Get states by country code and localization (available only for Italian states for now).

1const states = States.getStates({
2  filters: { country_code: 'IT' },
3  locale: 'it',
4})

• Get regions by country code (available only for Italian states for now).

1const states = States.getStates({
2  filters: {
3    country_code: 'IT',
4    is_region: true,
5  },
6})

• Get a state by country code and state code.

1const states = States.getStates({
2  filters: {
3    country_code: 'IT',
4    state_code: 'GE',
5  },
6})

Cities

• Get all cities.

1const cities = Cities.getCities()

• Get all cities by asc sort.

1const cities = Cities.getCities({
2  sort: {
3    mode: 'asc',
4  },
5})

• Get all cities by desc sort.

1const cities = Cities.getCities({
2  sort: {
3    mode: 'desc',
4  },
5})

• Get all cities by alphabetical sort.

1const cities = Cities.getCities({
2  sort: {
3    mode: 'alphabetical',
4    key: 'name',
5  },
6})

• Get Italian cities.

1const cities = Cities.getCities({
2  filters: {
3    country_code: 'IT',
4  },
5})

• Get Italian Ligurian cities.

1const cities = Cities.getCities({
2  filters: {
3    country_code: 'IT',
4    state_code: '42', // Region iso2
5  },
6})

Contributors

Any contribution is appreciated. You can get started with the steps below:

1. Fork this repository (learn how to do this here).

2. Clone the forked repository.

3. Make your changes and create a pull request (learn how to do this).

4. I will attend to your pull request and provide some feedback.

Need help?

Ping me on Twitter

License

This repository is licensed under the MIT License.

Sponsor

Don't be shy! 😜

:heart: Sponsor