Reverse Geocoding API
Request
Naurt data can be reverse-searched via a POST request to the final-destination endpoint.
Again, data should be provided as a JSON in the body of the request and not in the URL.
POST https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"latitude": Optional<Float>,
"longitude": Optional<Float>,
"country": Option<String>,
"distance_filter": Optional<Float>,
"additional_matches": Optional<Bool>,
}
Parameters
| Parameter | Type | Optional | Default | Description |
|---|---|---|---|---|
| latitude | float | Yes | None | A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90. |
| longitude | float | Yes | None | A valid longitude in WGS84 degrees. Range: -180 <= lon < 180. |
| distance_filter | float | Yes | 5000 | A distance in metres (larger than 0) within which you wish to search for POIs. When a filter is applied a latitude and longitude must also be provided. Maximum value of 25000 metres |
| additional_matches | Boolean | Yes | False | Provides up to 4 results beyond what Naurt classifies as the best_match. |
| country | String | Yes | None | Optional but strongly suggested two digit country code which helps with performance. |
- UK: United Kingdom
- SG: Singapore
- US: United States
Example
curl -XPOST \
-H "Content-type: application/json" \
-H "Authorization: <API_KEY_HERE>" \
-d '{"latitude": 52.0, "longitude": 0.0, "country": "UK"}' \
'https://api.naurt.net/final-destination/v1'
Response
Success
A 200 response code indicates a successful response with the format as follows.
{
"best_match": Optional<DESTINATION RESPONSE FORMAT>,
"additional_matches": Optional<List<DESTINATION RESPONSE FORMAT>>,
"version": Optional<String>
}
Naurt's best match will be the closest destination to the requested location.
You will only have an additional_matches field if you set additional_matches to true in the request.
The DESTINATION RESPONSE FORMAT is
{
"id": String,
"address": String,
"geojson": GeoJSON,
"distance": Optional<float>
}
Distance will only be present if you search with a latitude and longitude
and will be the distance of the destination from that position in metres.
Failure
A response code other than 200 indicates a failure to retrieve the requested destination.
401 Unauthorized
{"error":"Please ensure the request contains a valid API key."}
If there are no destinations available which match the search term, the response JSON will not contain any results, but instead a "naurt_info" message.
{"naurt_info":"Successful request. No destinations match search conditions."}
Search Restrictions
Destinations requested via the API are subject to some restrictions.
- No more than 300 requests per minute can be sent to this endpoint per API key. This limit can be adjusted by speaking to our support team.
- Currently there is a maximum return of 5 destinations per request.
Full Examples
POST https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"latitude": 50.835551,
"longitude": -0.127613,
"country": "UK"
}
To limit the search to a specific radius, you can apply a distance_filter up to a maximum of 25000m. If unused, it defaults to 5000m.
POST https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"latitude": 51.0,
"longitude": 0.0,
"distance_filter": 1000.0,
"country": "UK"
}