Documentation

Authentication

All API requests require authentication using your API key. You can find your API key in the API Keys section.
You can pass your API key in one of two ways:

Authorization Header (recommended)

Authorization: Bearer your_api_key_here

Query Parameter

?api_key=your_api_key_here

Endpoints

Autocomplete

Returns a list of UK places that match the search query.

Endpoint

GET /api/autocomplete?q={searchText}

Parameters

Name Type Description
q string The search query (e.g., town name, city name, or postcode)
limit integer Optional. The maximum number of results to return. Default: 10

Example response

                        [
                          {
                            "name": "Southampton",
                            "county": "Hampshire",
                            "postcode": "SO14 7",
                            "lat": 50.9048900,
                            "lng": -1.4043100,
                            "type": "City"
                          },
                          {
                            "name": "South Ockendon",
                            "county": "Essex",
                            "postcode": "RM15 6",
                            "lat": 51.5107200,
                            "lng": 0.2850600,
                            "type": "Town"
                          }
                        ]

Rate Limiting

API requests are subject to rate limiting based on your account tier. Each API key has a daily quota of requests.
If you exceed your rate limit, the API will return a 429 Too Many Requests response.

Limit response

                    {
                      "error": "Rate limit exceeded",
                      "message": "You have exceeded your daily request quota"
                    }

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request.
Status Code Description
200 OK The request was successful.
400 Bad Request The request was invalid or cannot be otherwise served.
401 Unauthorized Authentication failed or was not provided.
429 Too Many Requests You have exceeded your rate limit.
500 Internal Server Error Something went wrong on our end.