Zip / Postal Codes API

Description

Lookup a specific zip/postal code from among the 1.5M+ entries in our database. The data was aggregated from a variety of governmental sources as well as regional data providers.

Bulk Data Download:

If you need a complete data dump of our entire Zip & Postal Codes 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/zipcodes

Headers

Field	Description
api_key	`Required` Your API Key

Parameters

Field	Type	Description
code	String	`Required` The zip code/postal code to lookup Examples: `SY14`: Stretton, United Kingdom `836-0894`: Kyoragi, Japan `109 80`: Stockholm, Sweden

Zip/Postal Code Uniqueness:

Our database registers the zip/postal code as given to us by the governmental agencies and various providers. For that reason 109 80 will not result in the same response as 10980. The former is in Stockholm - Sweden while the latter exists in both Spain as well as the United States.

Additionally, UK codes are reported differently from most other countries. We've managed to import a large number of these into our database. However, some areas like Hackney - London will not be found if you search for E2 8FW. Meanwhile an area search for E2 will return the correct result.

If you need this endpoint to apply a less strict search convention, please let us know and we'll add that to future releases.

Response

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

Response Limit:

We've restricted the response limit to a maximum of 20 entries.

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 `3885-778`

curl -G \
https://api.jsonrepo.com/v1/knowledge/location/zipcodes \
-H "api_key: {YOUR_API_KEY_HERE}" \
--data-urlencode "code=3885-778"

Success Response

{
    "http_code": 200,
    "http_message": "Ok",
    "message": "Successful execution",
    "payload": {
        "codes": [
            {
                "id": 1110826,
                "code": "3885-778",
                "locale": "Maceda",
                "country": "Portugal",
                "country_code_2": "PT",
                "state": "Aveiro",
                "province": "Ovar",
                "community": "Maceda",
                "coordinates": {
                    "latitude": 40.9364,
                    "longitude": -8.6172
                },
                "db_entry_last_updated_at": "2024-07-31 21:30:17"
            }
        ]
    }
}

Error Response Examples

// Request with missing `code` parameter

{
    "http_code": 400,
    "http_message": "Bad Request",
    "message": "Malformed request: `code` must be provided.",
    "payload": []
}