curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?q=pune' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
def get_cities_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} cities in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_cities_by_state('IN', 'MH')
import requests
def get_settlements_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
params={'kind': 'settlement'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} settlements in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_settlements_by_state('IN', 'MH')
const getCitiesByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} cities in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getCitiesByState('IN', 'MH');
const getSettlementsByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities?kind=settlement`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} settlements in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getSettlementsByState('IN', 'MH');
<?php
function getCitiesByState($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}/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 {$stateCode}, {$countryCode}\n";
return $cities;
} else {
echo "State not found or no cities available\n";
return [];
}
}
$cities = getCitiesByState('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getCitiesByState(countryCode, stateCode string) []map[string]interface{} {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s/cities",
countryCode, stateCode)
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, %s\n", len(cities), stateCode, countryCode)
return cities
} else {
fmt.Printf("State not found or no cities available\n")
return nil
}
}
func main() {
cities := getCitiesByState("IN", "MH")
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 CitiesByState {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode + "/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 " + stateCode + ", " + countryCode);
} else {
System.out.println("State not found or no cities available");
}
}
}
require 'net/http'
require 'json'
def get_cities_by_state(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_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 #{state_code}, #{country_code}"
cities
else
puts 'State not found or no cities available'
[]
end
end
cities = get_cities_by_state('IN', 'MH')
[
{ "id": 133024, "name": "Mumbai", "kind": "settlement" },
{ "id": 133504, "name": "Pune", "kind": "settlement" },
{ "id": 133177, "name": "Nashik", "kind": "settlement" }
]
[
{
"id": 133024,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07283000",
"longitude": "72.88261000",
"timezone": "Asia/Kolkata",
"population": 12442373,
"type": "adm1",
"level": null,
"parent_id": null,
"native": "मुंबई",
"translations": "{\"de\":\"Mumbai\",\"fr\":\"Bombay\",\"ja\":\"ムンバイ\",\"cn\":\"孟买\"}",
"wikiDataId": "Q1156"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
Get Cities by State
Retrieve all cities within a specific state/province of a country
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?q=pune' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
def get_cities_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} cities in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_cities_by_state('IN', 'MH')
import requests
def get_settlements_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
params={'kind': 'settlement'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} settlements in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_settlements_by_state('IN', 'MH')
const getCitiesByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} cities in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getCitiesByState('IN', 'MH');
const getSettlementsByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities?kind=settlement`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} settlements in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getSettlementsByState('IN', 'MH');
<?php
function getCitiesByState($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}/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 {$stateCode}, {$countryCode}\n";
return $cities;
} else {
echo "State not found or no cities available\n";
return [];
}
}
$cities = getCitiesByState('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getCitiesByState(countryCode, stateCode string) []map[string]interface{} {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s/cities",
countryCode, stateCode)
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, %s\n", len(cities), stateCode, countryCode)
return cities
} else {
fmt.Printf("State not found or no cities available\n")
return nil
}
}
func main() {
cities := getCitiesByState("IN", "MH")
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 CitiesByState {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode + "/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 " + stateCode + ", " + countryCode);
} else {
System.out.println("State not found or no cities available");
}
}
}
require 'net/http'
require 'json'
def get_cities_by_state(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_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 #{state_code}, #{country_code}"
cities
else
puts 'State not found or no cities available'
[]
end
end
cities = get_cities_by_state('IN', 'MH')
[
{ "id": 133024, "name": "Mumbai", "kind": "settlement" },
{ "id": 133504, "name": "Pune", "kind": "settlement" },
{ "id": 133177, "name": "Nashik", "kind": "settlement" }
]
[
{
"id": 133024,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07283000",
"longitude": "72.88261000",
"timezone": "Asia/Kolkata",
"population": 12442373,
"type": "adm1",
"level": null,
"parent_id": null,
"native": "मुंबई",
"translations": "{\"de\":\"Mumbai\",\"fr\":\"Bombay\",\"ja\":\"ムンバイ\",\"cn\":\"孟买\"}",
"wikiDataId": "Q1156"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
?fields= to limit columns returned, or ?sort= to order the list. Both are available on Starter+ plans. See the Field Filtering & Sorting guide for syntax and per-entity sortable fields.id, name, and kind. Upgrading to Supporter+ unlocks the full field set: state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, native, translations, and wikiDataId. See Tier-Based Field Availability below.curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?q=pune' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?kind=settlement' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?include_translations=true' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requests
def get_cities_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} cities in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_cities_by_state('IN', 'MH')
import requests
def get_settlements_by_state(country_code, state_code):
response = requests.get(
f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities',
params={'kind': 'settlement'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
if response.ok:
cities = response.json()
print(f'Found {len(cities)} settlements in {state_code}, {country_code}')
return cities
else:
print('State not found or no cities available')
return []
cities = get_settlements_by_state('IN', 'MH')
const getCitiesByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities`,
{
headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' }
}
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} cities in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getCitiesByState('IN', 'MH');
const getSettlementsByState = async (countryCode, stateCode) => {
const response = await fetch(
`https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities?kind=settlement`,
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
if (response.ok) {
const cities = await response.json();
console.log(`Found ${cities.length} settlements in ${stateCode}, ${countryCode}`);
return cities;
} else {
console.error('State not found or no cities available');
return [];
}
};
getSettlementsByState('IN', 'MH');
<?php
function getCitiesByState($countryCode, $stateCode) {
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}/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 {$stateCode}, {$countryCode}\n";
return $cities;
} else {
echo "State not found or no cities available\n";
return [];
}
}
$cities = getCitiesByState('IN', 'MH');
?>
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func getCitiesByState(countryCode, stateCode string) []map[string]interface{} {
url := fmt.Sprintf("https://api.countrystatecity.in/v1/countries/%s/states/%s/cities",
countryCode, stateCode)
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, %s\n", len(cities), stateCode, countryCode)
return cities
} else {
fmt.Printf("State not found or no cities available\n")
return nil
}
}
func main() {
cities := getCitiesByState("IN", "MH")
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 CitiesByState {
public static void main(String[] args) throws Exception {
String countryCode = "IN";
String stateCode = "MH";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.countrystatecity.in/v1/countries/" + countryCode +
"/states/" + stateCode + "/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 " + stateCode + ", " + countryCode);
} else {
System.out.println("State not found or no cities available");
}
}
}
require 'net/http'
require 'json'
def get_cities_by_state(country_code, state_code)
uri = URI("https://api.countrystatecity.in/v1/countries/#{country_code}/states/#{state_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 #{state_code}, #{country_code}"
cities
else
puts 'State not found or no cities available'
[]
end
end
cities = get_cities_by_state('IN', 'MH')
[
{ "id": 133024, "name": "Mumbai", "kind": "settlement" },
{ "id": 133504, "name": "Pune", "kind": "settlement" },
{ "id": 133177, "name": "Nashik", "kind": "settlement" }
]
[
{
"id": 133024,
"name": "Mumbai",
"kind": "settlement",
"state_id": 4008,
"state_code": "MH",
"country_id": 101,
"country_code": "IN",
"latitude": "19.07283000",
"longitude": "72.88261000",
"timezone": "Asia/Kolkata",
"population": 12442373,
"type": "adm1",
"level": null,
"parent_id": null,
"native": "मुंबई",
"translations": "{\"de\":\"Mumbai\",\"fr\":\"Bombay\",\"ja\":\"ムンバイ\",\"cn\":\"孟买\"}",
"wikiDataId": "Q1156"
}
]
{
"error": "Unauthorized. You shouldn't be here."
}
Common Use Cases
Cascading Location Selector
Cascading Location Selector
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);
});
}
}
Regional Service Areas
Regional Service Areas
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);
Tier-Based Field Availability
| Tier | Plans | Fields |
|---|---|---|
| Basic | Community, Starter, Legacy | id, name, kind |
| Full | Supporter, Professional, Business | All Basic + state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, native, translations, wikiDataId, localized_name, matched_locale |
translations is part of Full access but is not returned by default: add include_translations=true, or name it in ?fields=. localized_name and matched_locale are computed from the translations rather than stored, and appear only when you pass locale. See Localized Place Names.
See Pricing for plan details.Authorizations
API key for authentication. Get your free key at app.countrystatecity.in.
Path Parameters
ISO2 code of the country (e.g., IN)
"IN"
ISO2 code of the state (e.g., MH)
"MH"
Query Parameters
Search filter. Case-insensitive match on name and native fields. Min 2 characters. Requires Starter+ plan.
2 - 100"mum"
Filter by derived place classification. Comma-separated list of settlement, administrative, section, unknown. Free on every plan. Invalid values return 400 listing the accepted values.
"settlement"
Filter by the raw source type value. Comma-separated, e.g. city,adm2. Requires Supporter+ plan (type is an extended field); lower plans receive 400 rather than the filter being ignored. Unrecognised values match zero rows.
"city"
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
"name,latitude,longitude"
Comma-separated sort tokens: field or field:asc|desc. Requires Starter+ plan.
"name:asc"
BCP 47 locale code (e.g. pt-BR) to request a localized name. Adds localized_name (resolved via exact locale → base language → native name → English name fallback) and matched_locale (which tier matched) to each result; name is unaffected. Supporter+ plans only — silently omitted (not an error) on lower tiers. A malformed value is rejected with a 400 on every tier.
2 - 7^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$"pt-BR"
When true, includes the full translations field (JSON string keyed by language code). Supporter+ plans only — silently omitted (not an error) on lower tiers. Note that an explicit fields=translations also returns the field and takes precedence over this flag.
true
Response
List of cities
Unique identifier
57606
City name in English
"Mumbai"
Derived classification of the place, computed from type. Returned on every tier, including Basic. See City Types.
settlement, administrative, section, unknown "settlement"
Parent state ID. Coordinates tier and above.
Parent state ISO2 code. Coordinates tier and above.
"MH"
Parent country ID. Coordinates tier and above.
Parent country ISO2 code. Coordinates tier and above.
"IN"
Latitude coordinate. Coordinates tier and above.
"19.07283000"
Longitude coordinate. Coordinates tier and above.
"72.88261000"
IANA timezone identifier. Coordinates tier and above.
"Asia/Kolkata"
Population count. Coordinates tier and above.
Raw source settlement type, e.g. city, adm2. See City Types. Coordinates tier and above.
Administrative level. Coordinates tier and above.
Parent city ID. Coordinates tier and above.
Name in native language. Coordinates tier and above.
JSON string keyed by language code. Supporter+ plans only. Returned when include_translations=true or when fields=translations explicitly requests it.
Wikidata item identifier. Full access level only.
"Q1156"
Name resolved via the locale query param's fallback chain (exact locale → base language → native name → English name). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.
"Mumbai"
Which fallback tier satisfied the locale request: the exact locale (e.g. pt-BR), its base language (e.g. pt), native, or en (English fallback). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.
"en"