Get Cities by Country

Retrieve all cities within a specific country

GET /v1/countries/{iso2}/cities

cURL

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

200 - Supporter tier (Coordinates)

[
  {
    "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

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

200 - Supporter tier (Coordinates)

[
  {
    "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

City Autocomplete

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);
    });
  }
}

Delivery Zone Setup

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

Tier	Plans	Fields
Basic	Community, Starter, Legacy	id, name
Coordinates	Supporter	All Basic + state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, native
Full	Professional, Business	All Coordinates + translations, wikiDataId

See Pricing for plan details.