Skip to main content
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)

​
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
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

[
  {
    "id": 133024,
    "name": "Mumbai"
  },
  {
    "id": 131718,
    "name": "Delhi"
  },
  {
    "id": 131645,
    "name": "Bangalore"
  }
]

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