Cities API - Get City Data for Any Country
The Cities API provides structured access to city-level geographic data from countries across the world. It delivers city names, precise latitude and longitude coordinates, administrative unit details including name, code, and level, and ISO alpha-2 country codes. Filter results by country using a standard ISO 3166-1 alpha-2 code and optionally narrow them down further by providing an administrative unit code to retrieve cities within a specific state, province, or territory.
Integrate this Country Cities API into travel platforms, ecommerce applications, logistics systems, address validation tools, and any location-driven application where accurate city-level data adds to a smooth user experience.
Features
Country-Based City Retrieval
Pass any ISO 3166-1 alpha-2 country code and get back a complete, structured list of cities for that country including names, coordinates, and administrative details.
Latitude & Longitude Coordinates
Every city record includes precise latitude and longitude values from standardized geographic databases, suitable for map rendering, proximity filtering, distance calculations, and routing workflows.
Administrative Unit Filtering
Retrieve cities within a specific state, province, or territory using the optional admin_unit parameter. Support region-specific use cases without pulling unnecessary data.
Administrative Unit Details
Each city record includes full administrative unit details - name, code, and level - giving complete geographic context for address systems and regional segmentation.
ISO Country Code Standardization
City lookups are driven by ISO 3166-1 alpha-2 country codes, ensuring consistent, predictable results regardless of language, region, or platform using the country parameter.
Multiple Response Formats
Supports both json and xml response formats via the format parameter, making it easy to integrate across modern applications and enterprise systems alike.
API Endpoint
Retrieve all cities for a given country, optionally filtered by administrative unit using the admin_unit parameter.
$ pip install requestsimport requests
url = "https://api.apifreaks.com/v1.0/geo/cities?country=US"
payload = {}
headers = {
'X-apiKey': 'API-KEY'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
How-to Guides
Complete Cities Data by Country
Pass an ISO 3166-1 alpha-2 country code to retrieve a complete structured list of all cities for that country with coordinates and administrative unit details.
# Response { "cities": [ { "name": "Aberdeen", "latitude": 57.14369, "longitude": -2.09814, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Balmedie", "latitude": 57.25052, "longitude": -2.06163, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Boddam", "latitude": 57.47076, "longitude": -1.78009, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Cove", "latitude": 57.1, "longitude": -2.08333, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Cruden Bay", "latitude": 57.41797, "longitude": -1.85313, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Cults", "latitude": 57.11667, "longitude": -2.16667, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Dyce", "latitude": 57.20522, "longitude": -2.17676, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Ellon", "latitude": 57.36405, "longitude": -2.07313, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Fraserburgh", "latitude": 57.68744, "longitude": -2.01844, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Inverbervie", "latitude": 56.84463, "longitude": -2.27997, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Kingswells", "latitude": 57.15798, "longitude": -2.22426, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" }, { "name": "Kintore", "latitude": 57.23721, "longitude": -2.3454, "admin_unit": { "name": "Aberdeen", "admin_code": "ABE", "admin_level": "council area" }, "iso_alpha_2": "GB" } ] }curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/cities?country=GB&apiKey=API-KEY'
Filter Cities by Administrative Unit
Use the admin_unit parameter with the administrative unit code to retrieve only cities within that specific state, province, or territory.
# Response { "cities": [ { "name": "Bayswater", "latitude": 51.51116, "longitude": -0.18426, "admin_unit": { "name": "Kensington and Chelsea", "admin_code": "KEC", "admin_level": "london borough" }, "iso_alpha_2": "GB" }, { "name": "Chelsea", "latitude": 51.48755, "longitude": -0.16936, "admin_unit": { "name": "Kensington and Chelsea", "admin_code": "KEC", "admin_level": "london borough" }, "iso_alpha_2": "GB" }, { "name": "Greater London", "latitude": 51.5, "longitude": -0.16667, "admin_unit": { "name": "Kensington and Chelsea", "admin_code": "KEC", "admin_level": "london borough" }, "iso_alpha_2": "GB" } ] }curl -X 'GET' 'https://api.apifreaks.com/v1.0/geo/cities?country=GB&admin_unit=KEC&apiKey=API-KEY'
Frequently Asked Questions
US for the United States, DE for Germany, and PK for Pakistan. Passing an invalid or unsupported country code will return a 400 error indicating that only ISO 3166-1 alpha-2 codes are supported.admin_unit parameter and pass the administrative unit code for the state, province, or territory you want to filter by. For example, passing admin_unit=PB with country=PK returns only cities in Punjab, Pakistan. You can find the correct admin unit codes using the Administrative Units API.admin_unit object containing the administrative unit name, admin code, and admin level such as province, state, or territory.admin_unit code, the API returns a 400 Bad Request response with an error indicating the admin code is not valid. Make sure the admin unit code matches a valid administrative unit for the specified country. Use the Administrative Units API to retrieve valid admin codes before querying cities.Pricing
To use the Cities API, you will need API credits. We only charge for successful queries, defined by a 2xx status code. If your request results in a 4xx or 5xx status code, no credits will be charged, and any deducted credits will be returned.
For each successful request, 1 credit will be charged.
Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.