Overview
The Country State City API provides developers with comprehensive access to geographical data covering 247+ countries, 5000+ states/provinces, and over 151,000 cities worldwide. Our RESTful API is designed for high performance, reliability, and ease of integration.Get your API key
Register for free and start accessing geographical data immediately with 3,000 requests/month.
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.
Free tier includes 3,000 requests per month (100/day) - perfect for development and small applications.
2
Make Your First Request
Use your API key to fetch all countries:
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
Authentication
All API requests require authentication using an API key sent in the request header:Never expose your API key in client-side code or public repositories. Use environment variables or server-side configurations to keep your key secure.
Rate Limits
| Plan | Monthly Requests | Daily Requests | Rate Limit |
|---|---|---|---|
| Community (Free) | 3,000 | 100 | 2 req/second |
| Supporter | 30,000 | 1,000 | 10 req/second |
| Professional | 150,000 | 5,000 | 25 req/second |
View Full Rate Limit Details
Learn about monitoring, best practices, and handling rate limits
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
Error Response
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success - Request completed successfully |
| 401 | Unauthorized - Invalid or missing API key |
| 404 | Not Found - Resource doesn’t exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 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.