Country-State-City Microservice API Review, Pricing & Features
Country State City Microservice API provides free country, state and city data via REST or GraphQL for address forms and location pickers. See features and…
Category
Developer Tools
Pricing
Free tier available on hosted services; underlying open-source datasets are free to self-host under permissive licenses, from Free
Verified
Not yet
Last updated
July 19, 2026
Headquarters
Not applicable (open-source project; primary services are maintainer-run rather than corporate)
What Is a Country-State-City Microservice API?
A Country-State-City Microservice API is a service, hosted or self-hosted, that provides structured, hierarchical geographic reference data: a list of countries, the states or provinces within each country, and the cities within each state. Developers use this data to power address forms, shipping calculators, and location autocomplete fields without maintaining the underlying dataset themselves.
This is a category populated by multiple independent projects rather than a single product. Hosted services such as countrystatecity.in offer REST and GraphQL APIs with a free tier, while open-source datasets such as the countries-states-cities-database project on GitHub let teams self-host the same kind of data as a lightweight internal microservice.
How the Underlying Data Is Sourced and Licensed
Hosted implementations like countrystatecity.in describe their core geographic database as licensed under ODbL-1.0, with an MIT license covering accompanying software packages, and describe community-driven updates, automated syncing, and real-time data validation as part of their maintenance process.
Open-source datasets in this space, most notably the countries-states-cities-database project, are distributed in multiple formats, including JSON, SQL, PostgreSQL, SQL Server, MongoDB, SQLite, XML, YAML, and CSV, and typically include ISO2 and ISO3 country codes, calling codes, capitals, native names, and time zone data, letting teams import the dataset directly into their own database rather than depending on a third-party API.
Hosted API vs Self-Hosted Dataset
Teams evaluating this category generally choose between a hosted API, which offers convenience, a free tier, and no infrastructure to maintain, and a self-hosted open-source dataset, which offers full control over data freshness, uptime, and licensing at the cost of needing to run and update the microservice internally.
Hosted options are typically a better fit for smaller applications or teams that want to move quickly without managing infrastructure, while self-hosted datasets are more common in larger applications that need guaranteed uptime independent of a third-party provider, tighter data privacy controls, or the ability to customize or supplement the base dataset.
Key Features
Hierarchical Country, State, and City Data — Structured data covering countries, their states or provinces, and cities nested underneath each, suitable for cascading address form fields.
REST and GraphQL Endpoints — Hosted implementations such as countrystatecity.in expose data through both REST and GraphQL APIs.
Multiple Export Formats — Data available in CSV, JSON, SQL, and additional formats (including PostgreSQL, SQL Server, MongoDB, SQLite, XML, and YAML in open-source datasets) for direct import.
ISO Country Codes and Metadata — Includes ISO2 and ISO3 country codes, calling codes, capitals, native names, and time zone data in many implementations.
Free Tier and Open-Source Options — Hosted services commonly offer a free tier to start building, while the underlying datasets are also available as free, self-hostable open-source projects.
Search and Autocomplete Support — Many implementations support search and autocomplete endpoints for building location-picker style UI components.
NPM, PyPI, and CLI Distribution — Some implementations distribute the dataset directly via package managers like NPM and PyPI or a command-line interface for local or offline use.
MCP Server Support — Newer implementations ship as an MCP (Model Context Protocol) server, allowing AI coding assistants and agents to query geographic data directly.
Pros & Cons
Pros
Free tier or fully open-source options make this data accessible without licensing cost for most use cases
Saves significant development time compared to manually building and maintaining a country, state, and city reference dataset
Available in multiple formats and through multiple distribution channels, hosted API, package manager, or direct database import
Widely used, with the leading hosted service reporting tens of thousands of developers and billions of cumulative requests
Open-source datasets allow full self-hosting for teams with strict uptime, privacy, or customization requirements
Supports both REST and GraphQL in leading hosted implementations, fitting different application architectures
Cons
As a fragmented category rather than one product, data completeness and accuracy vary across implementations
City-level data can be less precise or complete for smaller countries or less-documented administrative regions
Community-maintained datasets may update on inconsistent schedules compared to an official government geographic data source
Hosted free tiers may include rate limits that require upgrading or self-hosting for high-volume production use
No single official maintainer or company backs the category, making long-term support commitments harder to assess
Licensing details (such as ODbL for underlying data) require attention to ensure compliance with attribution or share-alike requirements in commercial use
Frequently Asked Questions
What is a Country-State-City Microservice API used for?
It provides hierarchical country, state, and city reference data, typically used to power cascading address form fields, shipping and tax calculators, and location autocomplete components in applications.
Is Country-State-City API data free to use?
Hosted services in this category, such as countrystatecity.in, offer a free tier to start building, and the underlying datasets, such as the countries-states-cities-database project, are also freely available as open source.
How much geographic data do these APIs typically cover?
Leading implementations cover more than 250 countries, several thousand states or provinces, and well over 100,000 cities, though completeness at the city level varies by country.
Can I self-host a Country-State-City dataset instead of using a hosted API?
Yes, open-source projects such as countries-states-cities-database distribute the dataset in formats including JSON, SQL, PostgreSQL, MongoDB, and CSV so it can be imported directly into a self-hosted database.
Do these APIs support GraphQL as well as REST?
Some hosted implementations, including countrystatecity.in, expose data through both REST and GraphQL endpoints.
Do Country-State-City APIs include ISO country codes?
Many implementations include ISO2 and ISO3 country codes, along with calling codes, capitals, native language names, and time zone data for countries.
Is there a single company that owns Country-State-City Microservice APIs?
No, this is a category populated by multiple independent hosted services and open-source projects rather than a single owned product or company.
Can AI coding assistants use this kind of geographic data directly?
Some newer implementations in this category ship as an MCP (Model Context Protocol) server, letting AI coding assistants and agents query country, state, and city data directly as part of a development workflow.