REST API
Introduction #
You can query our location data from any programming language or command line tools you like by using the REST API. For front-end implementations we recommend using a JavaScript solution such as Autocomplete.js.
All requests must use POST over SSL via the following base URL:
https://www.placesapi.co.uk/api/1/
Authentication #
All requests must be authenticated with a valid API key, passed via the following HTTP header:
X-PlacesAPI-Key
Rate Limits #
All endpoints are rate-limited. You can make up to 60 calls per minute per IP before receiving a 429 Too Many Requests HTTP response.
Search #
Search for locations by using the query endpoint:
Example
$ curl --location --request POST 'https://www.placesapi.co.uk/api/1/query' \
--header 'Accept: application/json' \
--header 'X-PlacesAPI-Key: YourAPIKey' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query=Guildford'
Options
| Option | Type | Description |
|---|---|---|
| query | String |
The search term to query e.g. Guildford |
| type | String |
The type of location records to search One of: city, town, village, hamlet, locality, suburban area |
| hitsPerPage | Integer |
The number of results to return. Max: 20 |
| aroundLatLng | String |
The lat/long pair to search around e.g. 51.24,-0.58 |
| aroundLatLngViaIP | String |
The IP address to search around e.g. 1.2.3.4 |
| aroundRadius | Integer |
Radius in meters to search around the latitude/longitude from the aroundLatLng or aroundLatLngViaIP options. |
| getRankingInfo | Boolean |
Controls whether Algolia's _rankingInfo object should be included in the results. |
Get by ObjectID #
Retrieve a specific location record by using the id endpoint:
https://www.placesapi.co.uk/api/1/id
Example
$ curl --location \
--request POST 'https://www.placesapi.co.uk/api/1/id' \
--header 'X-PlacesAPI-Key: YourAPIKey' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'objectID=P18343'
Options
| Option | Type | Description |
|---|---|---|
| objectID | String |
The object ID to look up e.g. P18343 |
Reverse Geocoding #
Get the records that are closest to a lat/long pair using the reverse endpoint:
https://www.placesapi.co.uk/api/1/reverse
As per all API requests, the number for records returned is determined by your API key (max 20).
Example
$ curl --location \
--request POST 'https://www.placesapi.co.uk/api/1/reverse?aroundLatLng=51.24,-0.58' \
--header 'X-PlacesAPI-Key: YourAPIKey'
Options
| Option | Type | Description |
|---|---|---|
| aroundLatLng | String |
The lat/long pair to search around e.g. 51.24,-0.58 |