Repository files navigation

🌍 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

1. Get a list of Countries

   GET:https://countries-states-cities.vercel.app/api/v1/countries

   • Request Parameters

     No parameters

   • Example Success Response

     {"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"}

2. Get country details from ISO2 code

   GET:https://countries-states-cities.vercel.app/api/v1/countries/[ciso]

   • Request Parameters

     Name	Located in	Description	Required	Type
     [ciso]	URL	ISO2 Code of Country	required	string

     • Example Success Response

       {"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 a list of States

     GET:https://countries-states-cities.vercel.app/api/v1/states

     • Request Parameters

       No parameters

     • Example Success Response

       {"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 a list of States within country

     GET:https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states

     • Request Parameters

       Name	Located in	Description	Required	Type
       [ciso]	URL	ISO2 Code of Country	required	string

       • Example Success Response

         {"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 the state details from ISO2 Code

       GET:https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states/[siso]

       • Request Parameters

         Name	Located in	Description	Required	Type
         [ciso]	URL	ISO2 Code of Country	required	string
         [siso]	URL	ISO2 Code of State	required	string

         • Example Success Response

           {"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 the list of cities in a state

         GET:https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/states/[siso]/cities

         • Request Parameters

           Name	Located in	Description	Required	Type
           [ciso]	URL	ISO2 Code of Country	required	string
           [siso]	URL	ISO2 Code of State	required	string

           • Example Success Response

             {"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 a list of Cities within country

           GET:https://countries-states-cities.vercel.app/api/v1/countries/[ciso]/cities

           • Request Parameters

             Name	Located in	Description	Required	Type
             [ciso]	URL	ISO2 Code of Country	required	string

             • Example Success Response

               {"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"}

1. Node.js (v20.x or higher)
2. Yarn (v1.22.x or higher)

Ensure you haveNode.js andYarn installed by runningnode -v andyarn -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 theNode.js website and theYarn website.

1. Clone the repository and navigate to the directory:

   git clone https://github.com/montasim/countries-states-cities.gitcd countries-states-cities

2. Install the dependencies:

   yarn install

3. Configuring the Environment:

   Create a.env.development or.env.staging or.env.production file in the root directory of the project and populate it with the necessary environment variables. See the.env.example file for an example.

1. 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.

2. 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.

3. Testing:

   To run the tests configured with Jest, use:

   yarntest

   This will build the project and then run all the Jest tests.

4. 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

5. Generating Documentation:

   To generate code documentation with JSDoc, run:

   yarn generate-docs

   This will create documentation based on your JSDoc comments.

6. 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:minoryarn release:major

7. Cleanup:

   To clean up dependencies and rebuild the project:

   yarn clean

   This command initializes the auto cleanup process and then forces a rebuild.
   

1. WebStorm
2. Postman
3. Swagify.io

https://countrystatecity.in/

github.com/dr5hn/countries-states-cities-database - For the countries, states, cities data.

Contributions are always welcome!Please read thecontribution guidelines first.