Country State City API

Access comprehensive geographical data with our RESTful API featuring 250 countries, 5,299+ states, and 153,765+ cities

Overview

The Country State City API provides developers with comprehensive access to geographical data covering 250 countries, 5,299+ states/provinces, and over 153,000 cities worldwide. Our RESTful API is designed for high performance, reliability, and ease of integration.

Get your API key

Register and start accessing geographical data immediately.

Key Features

Comprehensive Coverage

Access complete geographical hierarchies from countries down to individual cities with detailed metadata.

High Performance

Optimized endpoints with efficient data structures and caching for fast response times.

Developer Friendly

RESTful design with consistent responses, comprehensive error handling, and extensive documentation.

Always Current

Regular updates ensure data accuracy with automated validation and quality checks.

Quick Start

1. Get Your API Key

   Register at our portal to obtain your free API key.

2. Make Your First Request

   Use your API key to fetch all countries:

   cURL

   curl -X GET 'https://api.countrystatecity.in/v1/countries' \
     -H 'X-CSCAPI-KEY: YOUR_API_KEY'
   

   const response = await fetch('https://api.countrystatecity.in/v1/countries', {
     headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
   });
   const countries = await response.json();
   

   import requests
   
   response = requests.get(
     'https://api.countrystatecity.in/v1/countries',
     headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
   )
   countries = response.json()
   
3. Explore the Endpoints

   Browse our comprehensive endpoint documentation to integrate geographical data into your application.

   All endpoints return consistent JSON responses with proper HTTP status codes.

Base URL

https://api.countrystatecity.in/v1

Authentication

All API requests require authentication using an API key sent in the request header:

X-CSCAPI-KEY: YOUR_API_KEY

Never expose your API key in client-side code or public repositories. Use environment variables or server-side configurations to keep your key secure.

Available Endpoints

Countries

Get all countries or specific country details with ISO codes, currencies, and regional information.

States

Access states, provinces, and regions with filtering by country and detailed geographical data.

Cities

Retrieve cities with coordinates, timezone data, and hierarchical filtering by country and state.

Countries Endpoints

• Get All Countries - Retrieve list of all countries
• Get Country Details - Get detailed information for a specific country

States Endpoints

• Get All States - Retrieve list of all states
• Get States by Country - Get states within a specific country
• Get State Details - Get detailed information for a specific state

Cities Endpoints

• Get Cities by Country - Get cities within a specific country
• Get Cities by State - Get cities within a specific state

Response Format

All API endpoints return JSON responses with consistent structure:

Success Response

{
  "data": [...], // Array of results or single object
  "total": 250,  // Total count (for list endpoints)
  "page": 1      // Current page (for paginated endpoints)
}

Error Response

{
  "error": "Unauthorized. You shouldn't be here.",
  "code": 401,
  "message": "Invalid or missing API key"
}

HTTP Status Codes

Code	Description
200	Success - Request completed successfully
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn’t exist
500	Internal Server Error - Something went wrong on our end

For 5xx errors, implement exponential backoff in your retry logic. Most issues are temporary and resolve quickly.

Need Help?

Sample Code

Complete integration examples in multiple programming languages.

Support

Common questions, troubleshooting, and community support.