Skip to main content
GET
/
v1
/
countries
/
{iso2}
/
cities
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 133024,
    "name": "Mumbai",
    "state_id": 4008,
    "state_code": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.07283000",
    "longitude": "72.88261000",
    "timezone": "Asia/Kolkata",
    "population": 12442373,
    "type": null,
    "level": null,
    "parent_id": null,
    "native": "मुंबई"
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve all cities within a specific country using the country’s ISO2 code. This endpoint is useful for building location selectors and geographical applications.

​
Path Parameters

​
iso2
string
required
ISO2 code of the country (e.g., “IN” for India, “US” for United States)
Trim and order results: Add ?fields= to limit columns returned, or ?sort= to order the list. Both are available on Supporter+ plans. See the Field Filtering & Sorting guide for syntax and per-entity sortable fields.

​
Authentication

​
X-CSCAPI-KEY
string
required
Your API key for authentication

​
Query Parameters

​
q
string
Search filter on name. Case-insensitive match on name and native fields. Minimum 2 characters. Requires Supporter+ plan. Without this parameter, all results are returned (no plan restriction for search).

​
Response

​
id
integer
Unique identifier for the city
​
name
string
Official name of the city
City responses on the Basic tier only return id and name. Upgrading to Supporter+ unlocks state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, and native. Professional+ adds translations and wikiDataId. See Tier-Based Field Availability below.
Availability: /countries/{iso2}/cities (all cities in a country) requires Supporter+. Community/Starter users must use Get Cities by State instead.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 133024,
    "name": "Mumbai",
    "state_id": 4008,
    "state_code": "MH",
    "country_id": 101,
    "country_code": "IN",
    "latitude": "19.07283000",
    "longitude": "72.88261000",
    "timezone": "Asia/Kolkata",
    "population": 12442373,
    "type": null,
    "level": null,
    "parent_id": null,
    "native": "मुंबई"
  }
]

​
Common Use Cases

Implement type-ahead city search for a specific country.
class CountryCityAutocomplete {
  constructor(countryCode) {
    this.countryCode = countryCode;
    this.cities = [];
    this.loadCities();
  }
  
  async loadCities() {
    this.cities = await getCitiesByCountry(this.countryCode);
  }
  
  search(query) {
    const lowerQuery = query.toLowerCase();
    return this.cities.filter(city => 
      city.name.toLowerCase().includes(lowerQuery)
    ).slice(0, 10);
  }
  
  setupAutocomplete(inputElement) {
    inputElement.addEventListener('input', (e) => {
      const results = this.search(e.target.value);
      // Display results in dropdown
      this.displaySuggestions(results);
    });
  }
}
Group cities for shipping or service area calculations.
const setupDeliveryZones = async (countryCode) => {
  const cities = await getCitiesByCountry(countryCode);
  
  // Group cities alphabetically for easier management
  const zones = cities.reduce((acc, city) => {
    const firstLetter = city.name.charAt(0).toUpperCase();
    acc[firstLetter] = acc[firstLetter] || [];
    acc[firstLetter].push(city);
    return acc;
  }, {});
  
  return zones;
};
Large Datasets: Countries like the United States, India, and China have thousands of cities. Consider implementing pagination or using the state-filtered endpoint for better performance.
For better user experience, consider loading cities by state instead of by country for countries with many administrative divisions.

​
Tier-Based Field Availability

TierPlansFields
BasicCommunity, Starter, Legacyid, name
CoordinatesSupporterAll Basic + state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, native
FullProfessional, BusinessAll Coordinates + translations, wikiDataId
See Pricing for plan details.