Search by ID
You may have noticed that every destination comes with an id field. This is a
unique ID for every address. You can also search by this. You could, for example,
keep a list of favourite addresses.
Request
JSON
POST https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"id": Option<String>,
"country": Option<String>
}
Parameters
| Parameter | Type | Optional | Default | Description |
|---|---|---|---|---|
| id | String (UUID) | Yes | None | The unique address ID for direct lookup. |
| country | String | Yes | None | Optional but strongly suggested two digit country code which helps with performance. |
Currently supported country tags are
- AU: Australia
- BR: Brazil (BETA)
- CA: Canada
- DE: Germany (BETA)
- FR: France (BETA) (Please note that Naurt currently only covers Metropolitan France)
- HK: Hong Kong (Preview)
- IT: Italy (BETA)
- JP: Japan (Preview)
- KR: South Korea (Preview)
- NZ: New Zealand
- PT: Portugal (BETA)
- SG: Singapore
- TW: Taiwan (Preview)
- UK: United Kingdom
- US: United States
Example
CURL
curl -XPOST \
-H "Content-type: application/json" \
-H "Authorization: <API_KEY_HERE>" \
-d '{"id":"ca7e417f-d959-5f73-6d53-d9172593422b", "country": "UK"}' \
'https://api.naurt.net/final-destination/v1'
Response
Success
A 200 response code indicates a successful response with the format as follows.
JSON
{
"best_match": Optional<DESTINATION RESPONSE FORMAT>,
"version": Optional<String>
}
The best_match in this case will be the matching ID.
The DESTINATION RESPONSE FORMAT is
JSON
{
"id": String,
"address": String,
"geojson": GeoJSON
}
Failure
A response code other than 200 indicates a failure to retrieve the requested destination.
JSON
401 Unauthorized
{"error":"Please ensure the request contains a valid API key."}
In the case that no matching ID can be found, the response JSON will not contain any results, but instead a "naurt_info" message.
JSON
{"naurt_info":"Successful request. No destinations match search conditions."}
Example
{
"additional_matches": null,
"best_match": {
"address": "The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE",
"geojson": {...}, // omitted for brevity
"id": "c56dbebb-c7ab-ede2-a7ac-f84e57d1878d" // The `id` field
},
"version": "1.3.0"
}
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>
{
"id": "c56dbebb-c7ab-ede2-a7ac-f84e57d1878d",
"country": "UK"
}