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

def get_cities_by_country(country_code):
    response = requests.get(
      f'https://api.countrystatecity.in/v1/countries/{country_code}/cities',
      headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
    )
    
    if response.ok:
        cities = response.json()
        print(f'Found {len(cities)} cities in {country_code}')
        return cities
    else:
        print('Country not found or no cities available')
        return []

cities = get_cities_by_country('IN')
const getCitiesByCountry = async (countryCode) => {
  const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/cities`, {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  if (response.ok) {
    const cities = await response.json();
    console.log(`Found ${cities.length} cities in ${countryCode}`);
    return cities;
  } else {
    console.error('Country not found or no cities available');
    return [];
  }
};

getCitiesByCountry('IN');
<?php
function getCitiesByCountry($countryCode) {
    $curl = curl_init();
    
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/cities",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'X-CSCAPI-KEY: YOUR_API_KEY'
      ),
    ));
    
    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode == 200) {
        $cities = json_decode($response, true);
        echo "Found " . count($cities) . " cities in {$countryCode}\n";
        return $cities;
    } else {
        echo "Country not found or no cities available\n";
        return [];
    }
}

$cities = getCitiesByCountry('IN');
?>
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func getCitiesByCountry(countryCode string) []map[string]interface{} {
    url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/cities", countryCode)
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
    
    res, _ := client.Do(req)
    defer res.Body.Close()
    
    if res.StatusCode == 200 {
        body, _ := ioutil.ReadAll(res.Body)
        var cities []map[string]interface{}
        json.Unmarshal(body, &cities)
        
        fmt.Printf("Found %d cities in %s\n", len(cities), countryCode)
        return cities
    } else {
        fmt.Printf("Country not found or no cities available\n")
        return nil
    }
}

func main() {
    cities := getCitiesByCountry("IN")
    fmt.Println(cities)
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Map;

public class CitiesByCountry {
    public static void main(String[] args) throws Exception {
        String countryCode = "IN";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode + "/cities"))
            .header("X-CSCAPI-KEY", "YOUR_API_KEY")
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
            
        if (response.statusCode() == 200) {
            Gson gson = new Gson();
            Type listType = new TypeToken<List<Map<String, Object>>>(){}.getType();
            List<Map<String, Object>> cities = gson.fromJson(response.body(), listType);
            
            System.out.println("Found " + cities.size() + " cities in " + countryCode);
        } else {
            System.out.println("Country not found or no cities available");
        }
    }
}
require 'net/http'
require 'json'

def get_cities_by_country(country_code)
  uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/cities")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'

  response = http.request(request)
  
  if response.code == '200'
    cities = JSON.parse(response.body)
    puts "Found #{cities.length} cities in #{country_code}"
    cities
  else
    puts 'Country not found or no cities available'
    []
  end
end

cities = get_cities_by_country('IN')
[
  {
    "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": "मुंबई"
  }
]
[
  {
    "id": 133024,
    "name": "Mumbai",
    "...": "...all coordinates fields above...",
    "translations": "{\"de\":\"Mumbai\",\"fr\":\"Bombay\",\"ja\":\"ムンバイ\",\"cn\":\"孟买\"}",
    "wikiDataId": "Q1156"
  }
]
{
  "error": "No Cities found."
}
{
  "error": "Unauthorized. You shouldn't be here."
}
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'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities?q=mumbai' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests

def get_cities_by_country(country_code):
    response = requests.get(
      f'https://api.countrystatecity.in/v1/countries/{country_code}/cities',
      headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
    )
    
    if response.ok:
        cities = response.json()
        print(f'Found {len(cities)} cities in {country_code}')
        return cities
    else:
        print('Country not found or no cities available')
        return []

cities = get_cities_by_country('IN')
const getCitiesByCountry = async (countryCode) => {
  const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/cities`, {
    headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
  });

  if (response.ok) {
    const cities = await response.json();
    console.log(`Found ${cities.length} cities in ${countryCode}`);
    return cities;
  } else {
    console.error('Country not found or no cities available');
    return [];
  }
};

getCitiesByCountry('IN');
<?php
function getCitiesByCountry($countryCode) {
    $curl = curl_init();
    
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/cities",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'X-CSCAPI-KEY: YOUR_API_KEY'
      ),
    ));
    
    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode == 200) {
        $cities = json_decode($response, true);
        echo "Found " . count($cities) . " cities in {$countryCode}\n";
        return $cities;
    } else {
        echo "Country not found or no cities available\n";
        return [];
    }
}

$cities = getCitiesByCountry('IN');
?>
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func getCitiesByCountry(countryCode string) []map[string]interface{} {
    url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/cities", countryCode)
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("X-CSCAPI-KEY", "YOUR_API_KEY")
    
    res, _ := client.Do(req)
    defer res.Body.Close()
    
    if res.StatusCode == 200 {
        body, _ := ioutil.ReadAll(res.Body)
        var cities []map[string]interface{}
        json.Unmarshal(body, &cities)
        
        fmt.Printf("Found %d cities in %s\n", len(cities), countryCode)
        return cities
    } else {
        fmt.Printf("Country not found or no cities available\n")
        return nil
    }
}

func main() {
    cities := getCitiesByCountry("IN")
    fmt.Println(cities)
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.reflect.TypeToken;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Map;

public class CitiesByCountry {
    public static void main(String[] args) throws Exception {
        String countryCode = "IN";
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode + "/cities"))
            .header("X-CSCAPI-KEY", "YOUR_API_KEY")
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
            
        if (response.statusCode() == 200) {
            Gson gson = new Gson();
            Type listType = new TypeToken<List<Map<String, Object>>>(){}.getType();
            List<Map<String, Object>> cities = gson.fromJson(response.body(), listType);
            
            System.out.println("Found " + cities.size() + " cities in " + countryCode);
        } else {
            System.out.println("Country not found or no cities available");
        }
    }
}
require 'net/http'
require 'json'

def get_cities_by_country(country_code)
  uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/cities")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['X-CSCAPI-KEY'] = 'YOUR_API_KEY'

  response = http.request(request)
  
  if response.code == '200'
    cities = JSON.parse(response.body)
    puts "Found #{cities.length} cities in #{country_code}"
    cities
  else
    puts 'Country not found or no cities available'
    []
  end
end

cities = get_cities_by_country('IN')
[
  {
    "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": "मुंबई"
  }
]
[
  {
    "id": 133024,
    "name": "Mumbai",
    "...": "...all coordinates fields above...",
    "translations": "{\"de\":\"Mumbai\",\"fr\":\"Bombay\",\"ja\":\"ムンバイ\",\"cn\":\"孟买\"}",
    "wikiDataId": "Q1156"
  }
]
{
  "error": "No Cities found."
}
{
  "error": "Unauthorized. You shouldn't be here."
}

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.