Cities API

Description

Lookup a specific city. Our database contains information about 130 000 cities from all around the world. The data was aggregated from regional data providers as well as governmental sources.

Bulk Data Download:

If you need a complete data dump of our entire Cities database, reach out to us. We offer that as a separate service option. Trying to scrape our APIs is not recommended as you'll end up consuming your monthly request allowance.

Endpoint

> GET https://api.jsonrepo.com/v1/knowledge/location/cities

Headers

Field Description
api_key Required Your API Key

Parameters

Field Type Description
name String Required The city name to lookup (case insensitive)
country String Optional The country code (case insensitive)
Accepts:ISO a-2
Example: US

Limits & Country ISO:

A lot of cities around the world have duplicate name. That's when the country parameter can help limit the lookup area. But, it is still the case that some duplicates may exist as the same country can have multiple cities with the same name. That's why we decided to have this endpoint always return the 20 best matching search results.

Response

A successful request will result in a populated payload field with the expected output.

Caution:

The population number for some cities is out of date. This is mostly due to reporting conflict(s) between different regional data providers. For larger cities this is most often not an issue. However, smaller cities tend to have issues reporting their data as accurately.

Additionally, please keep in mind that some cities include in their reporting the number of people in the entirety of the area rather than city center only.

A failed request will result in an error output as detailed in Error Rules. If the endpoint validation fails due to missing, badly formatted or invalid parameters, the endpoint will return HTTP code 400 along with a message detailing the error.

See the examples section for more information.

A Lorenum.com product

Twitter Discord Email

Request

  • Curl
// Look up `Stockholm`

curl -G \
https://api.jsonrepo.com/v1/knowledge/location/cities \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "name=stockholm" \
--data-urlencode "country=SE"

Success Response

{
    "http_code": 200,
    "http_message": "Ok",
    "message": "Successful execution",
    "payload": {
        "cities": [
            {
                "id": 87539,
                "name": "Stockholm",
                "alt_names": [
                    "Estocolm",
                    "Estocolme",
                    "斯德哥爾摩",
                    "스톡홀름",
                    "𐍃𐍄𐌿𐌺𐌺𐌰𐌷𐌿𐌻𐌼𐍃",

                    // More alt names in different languages
                    ...
                ],
                "country": "Sweden",
                "country_code_2": "SE",
                "coordinates": {
                    "latitude": 59.32938,
                    "longitude": 18.06871
                },
                "population": 1515017,
                "timezone": "Europe/Stockholm",
                "db_entry_last_updated_at": "2024-07-31 19:57:30"
            }
        ]
    }
}

Error Response Examples

// Request with missing `name` parameter

{
    "http_code": 400,
    "http_message": "Bad Request",
    "message": "Malformed request: `name` parameter was not provided.",
    "payload": []
}