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

ParameterTypeOptionalDefaultDescription
idString (UUID)YesNoneThe unique address ID for direct lookup.
countryStringYesNoneOptional but strongly suggested two digit country code which helps with performance.
Currently supported country tags are
  • UK: United Kingdom
  • SG: Singapore

Example

CURL
curl -XPOST \
-H "Content-type: application/json" \
-H "Authorization: <API_KEY_HERE>"  \
-d '{"id":"3b32df10-4fd2-cc33-a3c6-3e4bd657e8ec3b32df10-4fd2-cc33-a3c6-3e4bd657e8ec", "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>,
  "contributors": Optional<List<String>>,
  "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,
  "distance": Optional<float>
}

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": "3b32df10-4fd2-cc33-a3c6-3e4bd657e8ec" // The `id` field
    }, 
    "contributors": [
        "© OpenStreetMap contributors"
    ],
    "version": "1.0.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

GET/POST  https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "id": "3b32df10-4fd2-cc33-a3c6-3e4bd657e8ec",
    "country": "UK"
    
}
{
    "additional_matches": null,
    "best_match": {
        "address": "The Martha Gunn, 100, Upper Lewes Road, Brighton, East Sussex, England, United Kingdom, BN2 3FE",
        "geojson": {
            "features": [
                {
                    "geometry": {
                        "coordinates": [
                            [
                                [
                                    -0.12752,
                                    50.83547
                                ],
                                [
                                    -0.127566,
                                    50.835447
                                ],
                                [
                                    -0.127697,
                                    50.835555
                                ],
                                [
                                    -0.127652,
                                    50.835577
                                ],
                                [
                                    -0.12752,
                                    50.83547
                                ]
                            ]
                        ],
                        "type": "Polygon"
                    },
                    "properties": {
                        "naurt_type": "naurt_door"
                    },
                    "type": "Feature"
                },
                {
                    "geometry": {
                        "coordinates": [
                            [
                                [
                                    -0.127597,
                                    50.835464
                                ],
                                [
                                    -0.12773,
                                    50.8354
                                ],
                                [
                                    -0.127757,
                                    50.835423
                                ],
                                [
                                    -0.127775,
                                    50.835415
                                ],
                                [
                                    -0.12786,
                                    50.835484
                                ],
                                [
                                    -0.127709,
                                    50.835556
                                ],
                                [
                                    -0.127597,
                                    50.835464
                                ]
                            ]
                        ],
                        "type": "Polygon"
                    },
                    "properties": {
                        "naurt_type": "naurt_building"
                    },
                    "type": "Feature"
                },
                {
                    "geometry": {
                        "coordinates": [
                            [
                                [
                                    -0.12752,
                                    50.83547
                                ],
                                [
                                    -0.127566,
                                    50.835447
                                ],
                                [
                                    -0.127697,
                                    50.835555
                                ],
                                [
                                    -0.127652,
                                    50.835577
                                ],
                                [
                                    -0.12752,
                                    50.83547
                                ]
                            ]
                        ],
                        "type": "Polygon"
                    },
                    "properties": {
                        "naurt_type": "naurt_parking"
                    },
                    "type": "Feature"
                }
            ],
            "type": "FeatureCollection"
        },
        "id": "3b32df10-4fd2-cc33-a3c6-3e4bd657e8ec"
    },
    "contributors": [
        "© OpenStreetMap contributors"
    ],
    "version": "1.0.0"
}