M
API Matrix

CountryStateCity API

⭐ Beginner's Pick Geocoding / API Key Intermediate HTTPS CORS
Varies by plan (check documentation)
77 Score
Grade B
Visit Official Site Compare Alternatives

Overview

CountryStateCity provides a comprehensive API with world countries, states, regions, and cities data in multiple formats including JSON, SQL, and CSV. It is perfect for building address forms, dropdown menus, or any feature that needs structured geographic data. An API key is required but free registration is available.

💡

Beginner Tip

Start by fetching the list of all countries to get country ISO codes, then use those codes to fetch states and cities. Cache the responses since this data rarely changes.

Available Data

country name and code
population
capital city
region and subregion
flag image URL
vehicle make and model

Example Response

JSON Response 
{
  "name": "Japan",
  "capital": "Tokyo",
  "population": 125800000,
  "region": "Asia",
  "languages": [
    "Japanese"
  ],
  "flag": "https://flagcdn.com/jp.svg",
  "currencies": [
    {
      "code": "JPY",
      "name": "Japanese yen"
    }
  ]
}

Field Reference

id Internal numeric identifier for the country, state, or city record.
name Official name of the country, state, or city in English.
iso2 Two-letter ISO 3166-1 alpha-2 code for countries (e.g., "US", "GB").
iso3 Three-letter ISO 3166-1 alpha-3 code for countries (e.g., "USA", "GBR").
phone_code International dialing prefix for the country (e.g., "1" for the US).
currency ISO 4217 currency code used in that country (e.g., "USD", "EUR").

Implementation Example 

const url = "https://countrystatecity.in/";
// Replace headers or query params with the values required by this API.
const response = await fetch(url, {
  headers: {
  "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

401 Unauthorized Missing or invalid API key in the request header.
✓ Register at countrystatecity.in to get a free API key and include it as the X-CSCAPI-KEY header.
404 Not Found for a state or city Using an incorrect country or state ISO code in the URL path.
✓ First fetch /v1/countries to get valid ISO2 codes, then use those codes in subsequent requests like /v1/countries/{iso2}/states.
Rate limit exceeded Sending too many requests in a short period on a free plan.
✓ Cache API responses locally since geographic data is relatively static. Upgrade to a paid plan for higher limits.

Matrix Score Breakdown

🌐 Reachability 30/30
⚡ Speed 5/20
🔒 Security 15/15
🛠 Developer XP 17/20
✓ Reliability 10/15

Partially tested on Apr 5, 2026

Technical Specifications

Auth API Key
HTTPS REQUIRED
CORS YES
Category Geocoding
Difficulty Intermediate
Verified: 2026-04-04

Similar APIs

View All →

Actinia Grass GIS

0

Actinia Grass GIS provides programmatic access to actinia is an open source rest api for geographical data that uses grass gis via REST API.

API Key Intermediate HTTPS

Apiip

82

Apiip is an IP geolocation API that returns detailed location data including city, country, timezone, and currency for any IP address.

API Key Intermediate HTTPS

Battuta

22

Battuta is a hierarchical location API that lets you browse countries, regions, and cities in a cascade, making it easy to build location pickers with dependent dropdowns.

API Key Intermediate

BigDataCloud

⭐ Beginner's Pick
77

BigDataCloud offers a fast and highly accurate IP geolocation API that also includes network security checks and a confidence area metric to indicate how precise the location is.

API Key Intermediate HTTPS

Bing Maps

87

Bing Maps (now Azure Maps) is Microsoft's mapping platform that lets you geocode addresses, reverse geocode coordinates, get routes, and embed interactive maps in your applications.

API Key Intermediate HTTPS