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."
}
Cities Endpoints
Get Cities by Country
Retrieve all cities within a specific country
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.
See Pricing for plan details.
Path Parameters
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
Your API key for authentication
Query Parameters
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
Unique identifier for the city
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
City Autocomplete
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
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 |
Was this page helpful?
⌘I