API Interface
Request
Naurt data can be 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.
JSON
POST https://api.naurt.net/final-destination/v2
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"queries": [RequestFormat],
"options": Option<Options>
}
The RequestFormat is as follows
JSON
{
"address_string": Option<String>,
"address_structured": Option<StructuredAddress>,
"location": Option<Location>,
"id": Option<Uuid>,
"country": Option<Country>,
"additional_matches": Option<bool>
}
Location is of the format
JSON
{
"latitude": Float,
"longitude": Float,
"distance_filter": Option<Float>
}
Parameters
| Parameter | Type | Optional | Default | Description |
|---|---|---|---|---|
latitude (within location) | float | Yes | None | A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90. |
longitude (within location) | float | Yes | None | A valid longitude in WGS84 degrees. Range: -180 <= lon < 180. |
distance_filter (within location) | 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. |
| address_string | String | Yes | None | An address string. Good formatting, spelling, and completeness will offer the best search results. |
| 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. |
| address_structured | Object | Yes | None | See this page for more details. |
Currently supported country tags are
- AU: Australia (BETA)
- BR: Brazil (BETA)
- CA: Canada (BETA)
- FR: France (BETA)
- IT: Italy (BETA)
- PT: Portugal (BETA)
- SG: Singapore
- UK: United Kingdom
- US: United States
Example
CURL
curl -XPOST \
-H "Content-type: application/json" \
-H "Authorization: <API_KEY_HERE>" \
-d '{"queries": [{"naurt_address_string": "Westminster Hall" ,"country": "UK"}]}' \
'https://api.naurt.net/final-destination/v2'
Response
Success
A 200 response code indicates a successful response with the format as follows.
JSON
{
"responses": List<RESPONSES FORMAT>,
"version": Optional<String>,
"request_id": Optional<String>
}
Should you experience any issues with a request, please cite the request_id in
communications with Naurt.
The RESPONSES FORMAT is as follows
JSON
{
"best_match": Option<DESTINATION RESPONSE FORMAT>,
"additional_matches": List<DESTINATION RESPONSE FORMAT>,
"status": Status,
}
Naurt will identify the single best match for you.
The best_match and additional_matches fields will always be present. In the
case where you do not request additional matches, the list will be empty. In the
case that no results are found, best_match will be null and additional_matches
will be an empty list, like so
JSON
{
"best_match": null,
"additional_matches": [],
"status": "no_matches"
}
The DESTINATION RESPONSE FORMAT is
JSON
{
"id": String,
"address": String,
"geojson": GeoJSON,
"distance": Optional<float>
}
- Note that the
addressfield is the normalised address and may not match the address you searched with. - Distance will only be present if you search with a
latitudeandlongitudeand 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.
JSON
400 Unauthorized
{"error":"Please ensure the request contains a valid API key."}
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.
Use Cases
Naurt has, in effect, six different ways the final destination API can be queried. These four different methods cover different use cases and depend on what data you have available. These methods are summarised in the below table, with links to the relevant pages
| Query Type | Data Required | Example Use Case |
|---|---|---|
| Forward Geocode | An address as a single string | Customer searches in a single query box |
| Forward Geocode with Location | An address as a single string and a location | Customer searches in a single query box with a location e.g. in a "search this area" feature in a map view |
| Structured Geocode | A parsed address | Customer searches with a form |
| Structured Geocode with Location | A parsed address and location | Customer searches with a form with a location e.g. in a "search this area" feature in a map view |
| Reverse Geocode | A location | Searching by clicking on a map |
| ID Lookup | A Naurt ID | Looking up a previously searched Naurt ID |
Example Requests and Responses
To keep the documentation clean and clear, in later pages, requests and responses
are condensed to improve readability. Specifically, we usually show only the
RequestFormat, of which you can chain multiple together into the queries array.
Just so you can see what examples of full requests and responses look like, some are provided here in full to give you an idea of what they may look like. You'll learn more about what the various options and settings do later in this documentation
Requests
JSON
{
"queries": [
{
"address_string": "11600 NW 14th St, Pembroke Pines, FL 33026, USA",
"location": {
"latitude": 26.019971267831988,
"longitude": -80.30555856674233
}
}
]
}
JSON
{
"queries": [
{
"location": {
"latitude": 48.845567,
"longitude": 2.321982
}
}
]
}
JSON
{
"queries": [
{
"address_string": "11600 NW 14th St, Pembroke Pines, FL 33026, USA",
"location": {
"latitude": 26.019971267831988,
"longitude": -80.30555856674233
}
},
{
"location": {
"latitude": 48.845567,
"longitude": 2.321982
}
}
]
}
Responses
JSON
{
"request_id": "96becf25-e233-4f9c-a05c-4bed90190bdd",
"responses": [
{
"additional_matches": [],
"best_match": {
"address": "11600 NW 14th St, Hollywood, FL 33026-2568, United States",
"geojson": {
"features": [
{
"geometry": {
"coordinates": [
-80.305321,
26.01977499999998
],
"type": "Point"
},
"properties": {
"naurt_type": "basic_geocode"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
-80.30532348845125,
26.01983651209808
]
],
"type": "MultiPoint"
},
"properties": {
"accuracy": {
"quality": "high"
},
"naurt_type": "naurt_door"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-80.30522698906019,
26.01971415663519
],
[
-80.30522974236504,
26.019838198396968
],
[
-80.30534886634625,
26.01983605560204
],
[
-80.30534961769449,
26.019869786929917
],
[
-80.30543425761427,
26.01986826443259
],
[
-80.30543233232864,
26.019781526590165
],
[
-80.305408202082,
26.01978196064377
],
[
-80.30540662559127,
26.01971093663903
],
[
-80.30522698906019,
26.01971415663519
]
]
],
"type": "Polygon"
},
"properties": {
"contributors": [
"© OpenStreetMap contributors"
],
"naurt_type": "naurt_building"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-80.3053968566494,
26.019970355811974
],
[
-80.30539553451139,
26.01993767388558
],
[
-80.3052598067114,
26.01994210803963
],
[
-80.30526112884941,
26.019974789964778
],
[
-80.3053968566494,
26.019970355811974
]
]
],
"type": "Polygon"
},
"properties": {
"accuracy": {
"quality": "high"
},
"minimum_parking_to_door_distance": 16.59,
"naurt_type": "naurt_parking"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"id": "4c6125ba-55a8-36ba-9277-d0aea0f7fdc2"
},
"status": "ok"
}
],
"version": "v2.0.0"
}
JSON
{
"request_id": "1c59bba8-5b31-44bd-843b-dd65b12b185b",
"responses": [
{
"additional_matches": [],
"best_match": {
"address": "99 Rue de Vaugirard, 75006 Paris 6e Arrondissement, France",
"distance": 1.17,
"geojson": {
"features": [
{
"geometry": {
"coordinates": [
2.321996,
48.845562
],
"type": "Point"
},
"properties": {
"naurt_type": "basic_geocode"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
2.3219907979366914,
48.845569910888315
]
],
"type": "MultiPoint"
},
"properties": {
"accuracy": {
"quality": "high"
},
"naurt_type": "naurt_door"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
2.321909647409796,
48.84551523603551
],
[
2.321923185716662,
48.845417282196
],
[
2.32200352893783,
48.84542133499832
],
[
2.3219928913673287,
48.84550581483984
],
[
2.3221249763533054,
48.84551285887346
],
[
2.322116958777533,
48.845605447829826
],
[
2.3219051619324067,
48.84554578895421
],
[
2.321909647409796,
48.84551523603551
]
]
],
"type": "Polygon"
},
"properties": {
"contributors": [
"Centre Scientifique et Technique du Batiment, National Buildings Database, 10 March 2025. This does not constitute an endorsement by Centre Scientifique et Technique du Batiment of this product"
],
"naurt_type": "naurt_building"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
2.3220469076711066,
48.84559689362962
],
[
2.322032301025305,
48.84561882923822
],
[
2.3219079035028907,
48.845582954923714
],
[
2.321922510148693,
48.84556101929939
],
[
2.3220469076711066,
48.84559689362962
]
]
],
"type": "Polygon"
},
"properties": {
"accuracy": {
"quality": "high"
},
"minimum_parking_to_door_distance": 5.09,
"naurt_type": "naurt_parking"
},
"type": "Feature"
}
],
"properties": {
"contributors": [
"data.gouv.fr, Base Adresse Nationale (BAN), 27 May 2025. This does not constitute an endorsement by data.gouv.fr of this product"
]
},
"type": "FeatureCollection"
},
"id": "77fcaa21-6517-3bbe-9793-e2f9ca175004"
},
"status": "ok"
},
{
"additional_matches": [],
"best_match": {
"address": "E.T Turismo Pillco, Jirón Piura 109, Amarilis 10002, Huánuco, Perú",
"geojson": {
"features": [
{
"geometry": {
"coordinates": [
-76.2358,
-9.938199999999997
],
"type": "Point"
},
"properties": {
"naurt_type": "basic_geocode"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
-76.23580998054682,
-9.938175236388162
]
],
"type": "MultiPoint"
},
"properties": {
"accuracy": {
"quality": "high"
},
"naurt_type": "naurt_door"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-76.2357346924313,
-9.938203482370367
],
[
-76.2358007096406,
-9.938161056394136
],
[
-76.2358197328575,
-9.93819015269706
],
[
-76.23575371564591,
-9.9382325786772
],
[
-76.2357346924313,
-9.938203482370367
]
]
],
"type": "Polygon"
},
"properties": {
"contributors": [
"© OpenStreetMap contributors"
],
"naurt_type": "naurt_building"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-76.23575240833136,
-9.938113097778851
],
[
-76.23578157576479,
-9.938091660808922
],
[
-76.23586279838965,
-9.938198881754204
],
[
-76.23583363095622,
-9.938220318717114
],
[
-76.23575240833136,
-9.938113097778851
]
]
],
"type": "Polygon"
},
"properties": {
"accuracy": {
"quality": "high"
},
"minimum_parking_to_door_distance": 9.35,
"naurt_type": "naurt_parking"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"id": "cae2fd05-545b-3ce9-9ae6-ed2eaab357e8"
},
"status": "ok"
}
],
"version": "v2.0.0"
}