Retrieve information about world cities, including coordinates, population, and administrative hierarchy. Cities are identified by GeoNames IDs—the closest thing to a global standard for city identification. We do not guarantee ID stability; GeoNames may reassign or merge IDs over time.
Standards Used
- ISO 3166-1
- ISO 3166-2
- IANA TZDB
- GeoNames
Ambiguous Names#
Name lookups return null when ambiguous. "Springfield", for example, matches 35+ US cities. Use the list endpoint with country or region filters for common names.
The City object#
| Field | Type | Required | Description |
|---|---|---|---|
| country | string | Yes | Country (alpha-2 code). Example: JP |
| id | integer (int32) | Yes | GeoNames ID. Example: 1850147 |
| is_capital | boolean | Yes | Whether this is a national capital. Example: true |
| latitude | number (double) | Yes | Latitude in decimal degrees. Example: 35.6762 |
| longitude | number (double) | Yes | Longitude in decimal degrees. Example: 139.6503 |
| name | string | Yes | City name. Example: Tokyo |
| population | integer (int32) | Yes | Population estimate. Example: 13960000 |
| region | string | No | Region (ISO 3166-2 code). Example: JP-13 |
| timezone | string | Yes | IANA timezone. Example: Asia/Tokyo |
Endpoints#
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| countryquery | string | No | Filter by country (alpha-2 code). Example: US |
| regionquery | string | No | Filter by region (ISO 3166-2 code). Example: US-CA |
| pagequery | integer | No | Page number (1-indexed). Example: 1 |
| per_pagequery | integer | No | Number of results per page. Example: 20 |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| data | object[] | Yes | The data items for this page. |
| pagination | object | Yes | Pagination metadata in response. |
| page | integer | Yes | Current page number. Example: 1 |
| per_page | integer | Yes | Items per page. Example: 20 |
| total_items | integer | Yes | Total number of items. Example: 100 |
| total_pages | integer | Yes | Total number of pages. Example: 5 |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/cities?country=US®ion=US-CA',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/cities',
params={
'country': 'US',
'region': 'US-NY'
},
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/cities?country=US®ion=US-CA"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Missing country or region parameter |
| 404 | Country or region not found |
| 429 | Rate limit exceeded |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| identifierpath | string | Yes | GeoNames ID (numeric) or city name |
Response
| Field | Type | Required | Description |
|---|---|---|---|
| country | string | Yes | Country (alpha-2 code). Example: JP |
| id | integer (int32) | Yes | GeoNames ID. Example: 1850147 |
| is_capital | boolean | Yes | Whether this is a national capital. Example: true |
| latitude | number (double) | Yes | Latitude in decimal degrees. Example: 35.6762 |
| longitude | number (double) | Yes | Longitude in decimal degrees. Example: 139.6503 |
| name | string | Yes | City name. Example: Tokyo |
| population | integer (int32) | Yes | Population estimate. Example: 13960000 |
| region | string | No | Region (ISO 3166-2 code). Example: JP-13 |
| timezone | string | Yes | IANA timezone. Example: Asia/Tokyo |
Example Request
const response = await fetch(
'https://worlddataapi.com/v1/cities/example',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const data = await response.json();import requests
response = requests.get(
'https://worlddataapi.com/v1/cities/example',
headers={
'X-API-Key': 'YOUR_API_KEY'
}
)
data = response.json()curl "https://worlddataapi.com/v1/cities/example"
-H "X-API-Key: YOUR_API_KEY"Error Responses
| Status | Description |
|---|---|
| 400 | Ambiguous city name |
| 404 | City not found |