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"
  }
]
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.

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

​
Authentication

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

​
Response

​
id
integer
Unique identifier for the city
​
name
string
Official name of the city
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.