π World countries, states, regions, provinces, cities, and towns api. All Countries, States, Cities with ISO2, ISO3, Country Code, Phone Code, Capital, Native Language, Time zones, Latitude, Longitude, Region, Subregion, Flag Emoji, and Currency.
- FEATURES
- PREREQUISITES
- SETUP
- RUNNING THE SCRIPT
- ERROR HANDLING
- HOSTING
- TOOLS
- ARTICLES
- DO NOT FORGET TO DO
- TUTORIALS
- INSPIRATIONS
- SPETIAL THANKS
- CONTRIBUTE
- CONTRIBUTORS
- SPECIAL THANKS
- LICENSE
- CONTACT
-
GET: https://countries-states-cities.vercel.app/api/v1/countries
-
No parameters
-
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": [ { "_id": "66962e25e7dec94bff9a9ba9", "id": 19, "name": "Bangladesh", "iso3": "BGD", "iso2": "BD", "numeric_code": "050", "phone_code": "880", "capital": "Dhaka", "currency": "BDT", "currency_name": "Bangladeshi taka", "currency_symbol": "৳", "tld": ".bd", "native": "Bangladesh", "region": "Asia", "region_id": "3", "subregion": "Southern Asia", "subregion_id": "14", "nationality": "Bangladeshi", "timezones": [ { "zoneName": "Asia/Dhaka", "gmtOffset": 21600, "gmtOffsetName": "UTC+06:00", "abbreviation": "BDT", "tzName": "Bangladesh Standard Time" } ], "translations": { "kr": "λ°©κΈλΌλ°μ", "pt-BR": "Bangladesh", "pt": "Bangladeche", "nl": "Bangladesh", "hr": "BangladeΕ‘", "fa": "Ψ¨ΩΪ―ΩΨ§Ψ―Ψ΄", "de": "Bangladesch", "es": "Bangladesh", "fr": "Bangladesh", "ja": "γγ³γ°γ©γγ·γ₯", "it": "Bangladesh", "cn": "εε ζ", "tr": "BangladeΕ" }, "latitude": "24.00000000", "longitude": "90.00000000", "emoji": "π§π©", "emojiU": "U+1F1E7 U+1F1E9" }, ... ], "message": "Successfully retrieved countries matching criteria.", "status": 200, "route": "/api/v1/countries" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/countries/[ciso]
-
Name Located in Description Required Type [ciso] URL ISO2 Code of Country required string -
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": { "_id": "66962e25e7dec94bff9a9ba9", "id": 19, "name": "Bangladesh", "iso3": "BGD", "iso2": "BD", "numeric_code": "050", "phone_code": "880", "capital": "Dhaka", "currency": "BDT", "currency_name": "Bangladeshi taka", "currency_symbol": "৳", "tld": ".bd", "native": "Bangladesh", "region": "Asia", "region_id": "3", "subregion": "Southern Asia", "subregion_id": "14", "nationality": "Bangladeshi", "timezones": [ { "zoneName": "Asia/Dhaka", "gmtOffset": 21600, "gmtOffsetName": "UTC+06:00", "abbreviation": "BDT", "tzName": "Bangladesh Standard Time" } ], "translations": { "kr": "λ°©κΈλΌλ°μ", "pt-BR": "Bangladesh", "pt": "Bangladeche", "nl": "Bangladesh", "hr": "BangladeΕ‘", "fa": "Ψ¨ΩΪ―ΩΨ§Ψ―Ψ΄", "de": "Bangladesch", "es": "Bangladesh", "fr": "Bangladesh", "ja": "γγ³γ°γ©γγ·γ₯", "it": "Bangladesh", "cn": "εε ζ", "tr": "BangladeΕ" }, "latitude": "24.00000000", "longitude": "90.00000000", "emoji": "π§π©", "emojiU": "U+1F1E7 U+1F1E9" }, "message": "Successfully retrieved the country.", "status": 200, "route": "/api/v1/countries/BD" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/states
-
No parameters
-
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": [ { "_id": "66962e1ae7dec94bff9a891d", "id": 759, "name": "Rangpur District", "country_id": 19, "country_code": "BD", "country_name": "Bangladesh", "state_code": "55", "type": "district", "latitude": "25.74679250", "longitude": "89.25083350" }, ... ], "message": "Successfully retrieved states matching criteria.", "status": 200, "route": "/api/v1/states" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states
-
Name Located in Description Required Type [ciso] URL ISO2 Code of Country required string -
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": [ { "_id": "66962e1ae7dec94bff9a891d", "id": 759, "name": "Rangpur District", "country_id": 19, "country_code": "BD", "country_name": "Bangladesh", "state_code": "55", "type": "district", "latitude": "25.74679250", "longitude": "89.25083350" }, ... ], "message": "Successfully retrieved the state.", "status": 200, "route": "/api/v1/countries/BD/states" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states/[siso]
-
Name Located in Description Required Type [ciso] URL ISO2 Code of Country required string [siso] URL ISO2 Code of State required string -
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": { "_id": "66962e1ae7dec94bff9a891d", "id": 759, "name": "Rangpur District", "country_id": 19, "country_code": "BD", "country_name": "Bangladesh", "state_code": "55", "type": "district", "latitude": "25.74679250", "longitude": "89.25083350" }, "message": "Successfully retrieved the state.", "status": 200, "route": "/api/v1/countries/BD/states/55" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states/[siso]/cities
-
Name Located in Description Required Type [ciso] URL ISO2 Code of Country required string [siso] URL ISO2 Code of State required string -
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": [ { "_id": "66962e33e7dec94bff9abe90", "id": 8577, "name": "Rangpur", "state_id": 759, "state_code": "55", "state_name": "Rangpur District", "country_id": 19, "country_code": "BD", "country_name": "Bangladesh", "latitude": "25.73333000", "longitude": "89.25000000", "wikiDataId": "Q2344570" }, ... ], "message": "Successfully retrieved the cities.", "status": 200, "route": "/api/v1/countries/BD/states/55/cities" }
-
-
GET: https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/cities
-
Name Located in Description Required Type [ciso] URL ISO2 Code of Country required string -
{ "timeStamp": "2024-07-24T14:58:55.767Z", "success": true, "data": [ { "_id": "66962e33e7dec94bff9abe90", "id": 8577, "name": "Rangpur", "state_id": 759, "state_code": "55", "state_name": "Rangpur District", "country_id": 19, "country_code": "BD", "country_name": "Bangladesh", "latitude": "25.73333000", "longitude": "89.25000000", "wikiDataId": "Q2344570" }, ... ], "message": "Successfully retrieved the cities.", "status": 200, "route": "/api/v1/countries/BD/cities" }
-
-
-
-
-
-
- Node.js (v20.x or higher)
- Yarn (v1.22.x or higher)
Ensure you have Node.js and Yarn installed by running node -v and yarn -v in your terminal. These commands will display the current version of each installed on your system. If these are not installed, follow the installation instructions on the Node.js website and the Yarn website.
-
Clone the repository and navigate to the directory:
git clone https://github.com/montasim/countries-states-cities.git cd countries-states-cities -
Install the dependencies:
yarn install
-
Configuring the Environment:
Create a
.env.developmentor.env.stagingor.env.productionfile in the root directory of the project and populate it with the necessary environment variables. See the .env.example file for an example.
-
Running the Application:
To start the application in development mode, use:
yarn dev
This will run the server with nodemon, automatically restarting when any changes are made.
-
To build and run the application in production mode, use:
yarn start
This will build the application and start the server using the built files.
This script first builds the project by linting the code, fixing lint issues, running prettier, and then starts the application with pm2.
-
Testing:
To run the tests configured with Jest, use:
yarn testThis will build the project and then run all the Jest tests.
-
Linting and Code Formatting:
-
To check for linting errors:
yarn lint:check
-
To fix linting errors:
yarn lint:fix
-
To check if files are formatted correctly:
yarn prettier:check
-
To format files:
yarn prettier:fix
-
-
Generating Documentation:
To generate code documentation with JSDoc, run:
yarn generate-docs
This will create documentation based on your JSDoc comments.
-
Release Management:
To create a new release, you can use:
yarn release
This will automatically bump the version, update the CHANGELOG, and create a commit and a tag.
For minor or major releases:
yarn release:minor yarn release:major
-
Cleanup:
To clean up dependencies and rebuild the project:
yarn clean
This command initializes the auto cleanup process and then forces a rebuild.
Step-by-step guide on setting up your own Vercel instance:
Vercel is the recommended option for hosting the files since it is free and easy to set up.
- Go to vercel.com.
- Click on
Log in. - Sign in with GitHub by pressing
Continue with GitHub. - Sign in to GitHub and allow access to all repositories if prompted.
- Fork this repo.
- Go back to your Vercel dashboard.
- To import a project, click the
Add New...button and select theProjectoption. - Click the
Continue with GitHubbutton, search for the required Git Repository and import it by clicking theImportbutton. Alternatively, you can import a Third-Party Git Repository using theImport Third-Party Git Repository ->link at the bottom of the page. - Create a personal access token (PAT) here and enable the
repoanduserpermissions (this allows access to see private repo and user stats). - Copy all the .env.development file as environment variables in the Vercel dashboard.
- Click deploy, and you're good to go. See your domains to use the API!
github.com/dr5hn/countries-states-cities-database - For the countries, states, cities data.
Contributions are always welcome! Please read the contribution guidelines first.
|
|
|
|
|
|
|
|---|