countries-states-cities-database

🌍 Discover our global repository of countries, states, and cities! 🏙️ Get comprehensive data in JSON, SQL, PSQL, SQLSERVER, MONGODB, SQLITE, XML, YAML, and CSV formats. Access ISO2, ISO3 codes, country code, capital, native language, timezones (for countries), and more. #countries #states #cities

8,466

2,801

8,466

View on GitHub

Top Related Projects

countries

1,712

Rinvex Country is a simple and lightweight package for retrieving country details with flexibility. A whole bunch of data including name, demonym, capital, iso codes, dialling codes, geo data, currencies, flags, emoji, and other attributes for all 250 countries worldwide at your fingertips.

world_countries

1,469

Constantly updated lists of world countries and their associated alpha-2, alpha-3 and numeric country codes as defined by the ISO 3166 standard, available in CSV, JSON , PHP, SQL and XML formats, in multiple languages and with national flags included; also available are the ISO 3166-2 codes of provinces/ states associated with the countries

Countries

1,254

Countries, Languages & Continents data (capital and currency, native name, calling codes).

country-list

5,233

:globe_with_meridians: List of all countries with names and ISO 3166-1 codes in all languages and data formats.

Quick Overview

The dr5hn/countries-states-cities-database is a comprehensive collection of world countries, states, and cities data in JSON, SQL, PLIST, YAML, and XML formats. It provides up-to-date information on geographical entities, making it a valuable resource for developers working on applications that require location data.

Pros

Offers data in multiple formats (JSON, SQL, PLIST, YAML, XML) for easy integration
Regularly updated to ensure accuracy and relevance
Includes additional information such as country flags, timezones, and currencies
Open-source and free to use

Cons

Large file sizes may impact performance in some applications
Occasional inconsistencies or missing data for less common locations
Requires manual updates to stay current with geopolitical changes
Limited support for historical or deprecated location data

Code Examples

Since this is a database repository and not a code library, there are no specific code examples to provide. However, here are some examples of how you might use the data in different formats:

JSON:

{
  "countries": [
    {
      "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",
      "subregion": "Southern Asia",
      "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"
    }
  ]
}

SQL:

INSERT INTO `countries` (`id`, `name`, `iso3`, `iso2`, `numeric_code`, `phone_code`, `capital`, `currency`, `currency_name`, `currency_symbol`, `tld`, `native`, `region`, `subregion`, `timezones`, `translations`, `latitude`, `longitude`, `emoji`, `emojiU`) VALUES
(1, 'Afghanistan', 'AFG', 'AF', '004', '93', 'Kabul', 'AFN', 'Afghan afghani', '؋', '.af', 'افغانستان', 'Asia', 'Southern Asia', '[{\"zoneName\":\"Asia\\/Kabul\",\"gmtOffset\":16200,\"gmtOffsetName\":\"UTC+04:30\",\"abbreviation\":\"AFT\",\"tzName\":\"Afghanistan Time\"}]', '{\"kr\":\"아프가니스탄\",\"pt-BR\":\"Afeganistão\",\"pt\":\"Afeganistão\",\"nl\":\"Afghanistan\",\"hr\":\"Afganistan\",\"fa\":\"افغانستان\",\"de\":\"Afghanistan\",\"es\":\"Afganistán\",\"fr\":\"Afghanistan\",\"

Competitor Comparisons

countries

1,712

Pros of Countries

More comprehensive data structure, including additional information like currencies, languages, and calling codes
Better integration with Laravel framework, offering service providers and facades
Regularly updated and maintained, with frequent commits and releases

Cons of Countries

Larger file size due to more detailed data, potentially impacting performance
More complex structure, which may be overkill for simpler use cases
Primarily focused on Laravel, which could limit its use in other frameworks or vanilla PHP projects

Code Comparison

Countries-States-Cities-Database:

{
  "id": 101,
  "name": "India",
  "iso3": "IND",
  "iso2": "IN",
  "numeric_code": "356",
  "phone_code": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "currency_name": "Indian rupee",
  "currency_symbol": "₹",
  "tld": ".in",
  "native": "भारत",
  "region": "Asia",
  "subregion": "Southern Asia",
  "timezones": [...]
}

Countries:

$country = country('IN');
$country->getCapital();
$country->getCurrencies();
$country->getLanguages();
$country->getCallingCode();
$country->getTimezones();

The Countries repository offers a more object-oriented approach with methods to access specific data, while Countries-States-Cities-Database provides a straightforward JSON structure. The choice between them depends on the project requirements and preferred coding style.

world_countries

1,469

Pros of world_countries

Offers data in multiple formats (JSON, XML, CSV, SQL)
Includes additional information like country calling codes and top-level domains
Regular updates and maintenance

Cons of world_countries

Limited to country-level data, lacking states and cities information
Smaller dataset compared to countries-states-cities-database
Less detailed geographical information

Code Comparison

world_countries (JSON format):

{
  "id": 1,
  "name": "Afghanistan",
  "alpha2": "AF",
  "alpha3": "AFG"
}

countries-states-cities-database (JSON format):

{
  "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",
  "subregion": "Southern Asia",
  "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": "阿富汗"
  },
  "latitude": "33.00000000",
  "longitude": "65.00000000",
  "emoji": "🇦🇫",
  "emojiU": "U+1F1E6 U+1F1EB"
}

Countries

1,254

Countries, Languages & Continents data (capital and currency, native name, calling codes).

Pros of Countries

Smaller file size and more lightweight dataset
Includes additional data like country codes, languages, and currencies
Regular updates and active maintenance

Cons of Countries

Less detailed information for states and cities
Fewer total countries, states, and cities in the database
Limited customization options for data output

Code Comparison

Countries:

{
  "name": "Afghanistan",
  "alpha2": "AF",
  "alpha3": "AFG",
  "numeric": "004",
  "locales": ["fa-AF", "ps", "uz-AF", "tk"],
  "currency": {
    "code": "AFN",
    "name": "Afghan afghani",
    "symbol": "؋"
  }
}

countries-states-cities-database:

{
  "id": 1,
  "name": "Afghanistan",
  "iso3": "AFG",
  "iso2": "AF",
  "numeric_code": "004",
  "phone_code": "93",
  "capital": "Kabul",
  "currency": "AFN",
  "currency_name": "Afghan afghani",
  "currency_symbol": "؋"
}

Both repositories provide valuable geographic data, but Countries offers a more concise dataset with additional language information, while countries-states-cities-database provides a more comprehensive list of countries, states, and cities with extra details like phone codes and capitals.

country-list

5,233

:globe_with_meridians: List of all countries with names and ISO 3166-1 codes in all languages and data formats.

Pros of country-list

Supports a wide range of formats (CSV, JSON, SQL, XML, YAML, etc.)
Available in multiple languages (200+)
Includes country codes (ISO 3166-1)

Cons of country-list

Limited to country data only (no states or cities)
Less frequent updates compared to countries-states-cities-database
Smaller community and fewer contributors

Code Comparison

countries-states-cities-database:

{
  "id": 101,
  "name": "India",
  "iso3": "IND",
  "iso2": "IN",
  "numeric_code": "356",
  "phone_code": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "currency_name": "Indian rupee",
  "currency_symbol": "₹",
  "tld": ".in",
  "native": "भारत",
  "region": "Asia",
  "subregion": "Southern Asia",
  "timezones": [
    {
      "zoneName": "Asia/Kolkata",
      "gmtOffset": 19800,
      "gmtOffsetName": "UTC+05:30",
      "abbreviation": "IST",
      "tzName": "Indian Standard Time"
    }
  ],
  "translations": {
    "kr": "인도",
    "pt-BR": "Índia",
    "pt": "Índia",
    "nl": "India",
    "hr": "Indija",
    "fa": "هند",
    "de": "Indien",
    "es": "India",
    "fr": "Inde",
    "ja": "インド",
    "it": "India",
    "cn": "印度"
  },
  "latitude": "20.00000000",
  "longitude": "77.00000000",
  "emoji": "🇮🇳",
  "emojiU": "U+1F1EE U+1F1F3"
}

country-list:

AF: Afghanistan
AX: Åland Islands
AL: Albania
DZ: Algeria
AS: American Samoa

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

ð Countries States Cities Database

release size

Full Database of city state country available in JSON, MYSQL, PSQL, SQLITE, XML, YAML, MONGODB & CSV format. All Countries, States & Cities are Covered & Populated with Different Combinations & Versions.

CSC Platform Ecosystem
API
Export Tool
Available Formats
Distribution Files Info
Demo
Insights
Next API Database Update
Import MongoDB
Export to DuckDB
License
Contributing
Repo Activity
Sponsors
Other Publishings
Support My Work
Suggestions / Feedbacks
Disclaimer

ð CSC Platform Ecosystem

Easily access all the tools and services in the Countries States Cities platform:

Tool	Description	Link
Demo Database	Browse the full database online	demo.countrystatecity.in
API Service	Programmatic access to countries, states, cities	countrystatecity.in
Export Tool	Export data in multiple formats	export.countrystatecity.in
Update Tool	Submit and track data change requests	manager.countrystatecity.in

API ð

ð Introducing API for Countries States Cities Database.

API Documentation

ð ï¸ Export Tool

ð¯ Transform your data with our powerful export tool!

Looking to export the Countries States Cities database in your preferred format? Our dedicated export tool makes it easy to convert and download data in multiple formats with just a few clicks.

Try the Export Tool - Export data in JSON, CSV, XML, YAML, and more!

Features:

Multiple Export Formats: JSON, CSV, XML, YAML, and more
Flexible Data Selection: Choose specific countries, states, or cities
Custom Filtering: Filter by regions, subregions, or specific criteria
Bulk Downloads: Export large datasets efficiently
Real-time Processing: Get your data instantly
User-friendly Interface: Simple and intuitive design

Perfect for developers, researchers, and businesses who need clean, structured geographical data for their applications.

Available Formats

JSON
MYSQL
PSQL
SQLITE
SQLSERVER
MONGODB
XML
YAML
CSV

Note: DuckDB format is available via manual conversion from SQLite files. See the Export to DuckDB section for instructions.

Distribution Files Info

File	JSON	MYSQL	PSQL	SQLITE	SQLSERVER	MONGODB	XML	YAML	CSV
Regions	â	â	â	â	â	â	â	â	â
Subregions	â	â	â	â	â	â	â	â	â
Countries	â	â	â	â	â	â	â	â	â
States	â	â	â	â	â	â	â	â	â
Cities	â	â	â	â	â	â	â	â	â
Country+States	â	NA	NA	NA	NA	NA	NA	NA	NA
Country+Cities	â	NA	NA	NA	NA	NA	NA	NA	NA
Country+State+Cities/World	â	â	â	â	â	â	NA	NA	NA

Demo

https://dr5hn.github.io/countries-states-cities-database/

Insights

Total Regions : 6
Total Sub Regions : 22
Total Countries : 250
Total States/Regions/Municipalities : 5,038
Total Cities/Towns/Districts : 151,024

Last Updated On : 17th Aug 2025

Next API Database Update

The API database is regularly updated to ensure the latest data is available to users. The next scheduled update is on:

Upcoming API Database Update Date: 8th April 2025

Please note that this date is subject to change based on unforeseen circumstances. Although we strive to adhere to the schedule, there may be instances where the update date is missed. We apologize for any inconvenience caused in such cases.

We appreciate your understanding and patience. Thank you for using the Countries States Cities Database!

Import MongoDB

How to import MongoDB database?

# First extract the tar.gz file
tar -xzvf world-mongodb-dump.tar.gz

# Then restore the MongoDB dump
mongorestore --host localhost:27017 --db world mongodb-dump/world

Export to DuckDB

Want to export the database to DuckDB format? You can easily convert the existing SQLite files to DuckDB format using our conversion script.

Prerequisites

First, install DuckDB Python package:

pip install duckdb

Convert SQLite to DuckDB

Use the provided conversion script to convert SQLite files to DuckDB format:

# Convert the complete world database
python3 bin/import_duckdb.py --input sqlite/world.sqlite3 --output duckdb/world.db

# Convert individual table databases
python3 bin/import_duckdb.py --input sqlite/regions.sqlite3 --output duckdb/regions.db
python3 bin/import_duckdb.py --input sqlite/subregions.sqlite3 --output duckdb/subregions.db
python3 bin/import_duckdb.py --input sqlite/countries.sqlite3 --output duckdb/countries.db
python3 bin/import_duckdb.py --input sqlite/states.sqlite3 --output duckdb/states.db
python3 bin/import_duckdb.py --input sqlite/cities.sqlite3 --output duckdb/cities.db

The conversion script will create DuckDB database files that maintain the same structure and data as the original SQLite files, optimized for analytical workloads.

License

This Countries States Cities Database is made available under the Open Database License. Any rights in individual contents of the database are licensed under the Database Contents License.

Contributing

ðð First off, thanks for your interest in contributing! ðð

Using Our Database Update Tool

We've launched a dedicated web tool to make contributing to this database easier than ever!

CSC Update Tool - Our official tool to submit database change requests

The update tool allows you to:

Browse and search through all regions, subregions, countries, states, and cities
Easily identify and correct outdated or inaccurate data
Submit change requests through a streamlined review process
Track the status of your submissions

Alternative Manual Process

If you prefer to contribute directly through GitHub, you can still follow these steps:

Fork the repository and clone it to your local machine
Make the necessary changes to the data:
- To fix cities records, update the sql/world.sql > cities Table
- To fix states/provinces records, update the sql/world.sql > states Table
- To fix countries records, update the sql/world.sql > countries Table
- To fix regions records, update the sql/world.sql > regions Table
- To fix subregions records, update the sql/world.sql > subregions Table
Once you've made the changes, create a pull request with a clear description of the modifications you've made

Please ensure your contributions align with our data standards and formatting. You can find the detailed contribution guidelines here.

We review all submissions carefully to maintain data quality and appreciate your help in making this database more accurate and comprehensive.

Repo Activity

As always, thanks to our amazing contributors!

Made with contrib.rocks.

Make the world more Greener ð´

Contribute towards better earth buy the world a tree

Other Publishings

Find this project on

Follow me at

ðââï¸ Support My Work

Suggestions / Feedbacks

Suggestions & Feedbacks are Most Welcome
gadadarshan[at]gmail[dot]com

Disclaimer

Please note that while every effort has been made to ensure the accuracy and completeness of the Countries States Cities Database, it may still contain errors or omissions. The database is continuously being refined and improved based on user feedback and contributions.

Contributors are encouraged to review the Contribution Guidelines and follow the specified guidelines for updating and correcting data in the database. However, due to the collaborative nature of the project, we cannot guarantee the absolute accuracy or reliability of the information provided.

The Countries States Cities Database is made available under the Open Database License, and any rights in individual contents of the database are licensed under the Database Contents License. Users are responsible for independently verifying the data and using it at their own discretion.

We appreciate the efforts of contributors in identifying and addressing issues in the database, and we encourage users to report any inaccuracies or suggest improvements through creating issues. However, please note that the database may not always reflect the latest geopolitical changes or political status.

It is recommended that users consult official sources and corroborate the data from the Countries States Cities Database with other reliable references for critical applications or decision-making processes.

By accessing and using the Countries States Cities Database, users acknowledge and agree to the aforementioned disclaimer and the terms of the Open Database License and the Database Contents License.

That's all Folks. Enjoy.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Competitor Comparisons

Pros of Countries

Cons of Countries

Code Comparison

Pros of world_countries

Cons of world_countries

Code Comparison

Pros of Countries

Cons of Countries

Code Comparison

Pros of country-list

Cons of country-list

Code Comparison

Convert designs to code with AI

README

ð Countries States Cities Database

Table of Contents

ð CSC Platform Ecosystem

API ð

ð ï¸ Export Tool

Features:

Available Formats

Distribution Files Info

Demo

Insights

Next API Database Update

Import MongoDB

Export to DuckDB

Prerequisites

Convert SQLite to DuckDB

License

Contributing

Using Our Database Update Tool

Alternative Manual Process

Repo Activity

Sponsors

Make the world more Greener ð´

Other Publishings

Follow me at

ðââï¸ Support My Work

Suggestions / Feedbacks

Disclaimer

Top Related Projects

Convert designs to code with AI

ð Countries States Cities Database

ð CSC Platform Ecosystem

API ð

ð ï¸ Export Tool

Make the world more Greener ð´

ðââï¸ Support My Work