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

[
  { "id": 133024, "name": "Mumbai" },
  { "id": 132332, "name": "Pune" },
  { "id": 133351, "name": "Nashik" }
]

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 state or province using both the country’s ISO2 code and the state’s ISO2 code. This provides the most targeted city data.
Availability: All plans (Community and above). The fields returned vary by tier — see Tier-Based Field Availability below.

​
Path Parameters

​
country_iso2
string
required
ISO2 code of the country (e.g., “IN”, “US”)
​
state_iso2
string
required
ISO2 code of the state/province (e.g., “MH” for Maharashtra, “CA” for California)
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.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  { "id": 133024, "name": "Mumbai" },
  { "id": 132332, "name": "Pune" },
  { "id": 133351, "name": "Nashik" }
]

​
Common Use Cases

Build three-level dropdowns for Country → State → City selection.
class LocationSelector {
  constructor() {
    this.setupEventListeners();
  }
  
  setupEventListeners() {
    const countrySelect = document.getElementById('country');
    const stateSelect = document.getElementById('state');
    const citySelect = document.getElementById('city');
    
    countrySelect.addEventListener('change', async (e) => {
      const countryCode = e.target.value;
      if (countryCode) {
        await this.populateStates(countryCode);
        this.clearCities();
      }
    });
    
    stateSelect.addEventListener('change', async (e) => {
      const stateCode = e.target.value;
      const countryCode = countrySelect.value;
      if (stateCode && countryCode) {
        await this.populateCities(countryCode, stateCode);
      }
    });
  }
  
  async populateCities(countryCode, stateCode) {
    const cities = await getCitiesByState(countryCode, stateCode);
    const citySelect = document.getElementById('city');
    
    citySelect.innerHTML = '<option value="">Select City...</option>';
    cities.forEach(city => {
      const option = document.createElement('option');
      option.value = city.id;
      option.textContent = city.name;
      citySelect.appendChild(option);
    });
  }
}
Define service coverage areas by state and city combinations.
const createServiceArea = async (serviceAreas) => {
  const coverage = {};
  
  for (const area of serviceAreas) {
    const { countryCode, stateCode, serviceName, deliveryTime } = area;
    const cities = await getCitiesByState(countryCode, stateCode);
    
    coverage[`${countryCode}-${stateCode}`] = {
      serviceName,
      deliveryTime,
      cities: cities.length,
      cityIds: cities.map(city => city.id)
    };
  }
  
  return coverage;
};

// Usage
const areas = [
  { countryCode: 'IN', stateCode: 'MH', serviceName: 'Express', deliveryTime: '1-2 days' },
  { countryCode: 'US', stateCode: 'CA', serviceName: 'Standard', deliveryTime: '2-3 days' }
];

const serviceMap = await createServiceArea(areas);
This is the most efficient endpoint for building cascading location selectors as it provides the smallest, most relevant dataset.
This endpoint provides the optimal balance between data size and specificity, making it ideal for form controls and location-based filtering.

​
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.