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.

JSON
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

ParameterTypeOptionalDefaultDescription
latitudefloatYesNoneA valid latitude in WGS84 degrees. Range: -90 <= lat <= 90.
longitudefloatYesNoneA valid longitude in WGS84 degrees. Range: -180 <= lon < 180.
distance_filterfloatYes5000A 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_matchesBooleanYesFalseProvides up to 4 results beyond what Naurt classifies as the best_match.
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 '{"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.

JSON
{
  "best_match": Optional<DESTINATION RESPONSE FORMAT>,
  "additional_matches": Optional<List<DESTINATION RESPONSE FORMAT>>,
  "contributors": Optional<List<String>>,
  "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

JSON
{
  "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.

JSON
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.

JSON
{"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

GET/POST  https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "latitude": 50.835551,
    "longitude": -0.127613,
    "country": "UK"
}
{
    "best_match": {
        "address": "The Martha Gunn, 100, Upper Lewes Road, Brighton, East Sussex, England, United Kingdom, BN2 3FE",
        "distance": 5.26,
        "geojson": {
        "features": [
            {
            "geometry": {
                "coordinates": [
                [
                    -0.127653,
                    50.835511
                ]
                ],
                "type": "MultiPoint"
            },
            "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"
}

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.

GET/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"
}
{
    "best_match": {
        "address": "Bolton Buildings Ltd, Unit 5, Bluebell Business Estate, Sheffield Park, Uckfield, East Sussex, England, United Kingdom, TN22 3HQ",
        "distance": 431.03,
        "geojson": {
        "features": [
            {
            "geometry": {
                "coordinates": [
                [
                    -0.002799,
                    50.996547
                ]
                ],
                "type": "MultiPoint"
            },
            "properties": {
                "naurt_type": "naurt_door"
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    -0.00289,
                    50.996513
                    ],
                    [
                    -0.003138,
                    50.996788
                    ],
                    [
                    -0.002915,
                    50.996868
                    ],
                    [
                    -0.002857,
                    50.996803
                    ],
                    [
                    -0.002759,
                    50.996841
                    ],
                    [
                    -0.002568,
                    50.996632
                    ],
                    [
                    -0.00289,
                    50.996513
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "naurt_type": "naurt_building"
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    -0.002698,
                    50.996516
                    ],
                    [
                    -0.002667,
                    50.996485
                    ],
                    [
                    -0.002849,
                    50.996412
                    ],
                    [
                    -0.00288,
                    50.996443
                    ],
                    [
                    -0.002698,
                    50.996516
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "naurt_type": "naurt_parking"
            },
            "type": "Feature"
            }
        ],
        "type": "FeatureCollection"
        },
        "id": "f3d2bf89-af4d-2d45-425b-b49dafc57b89"
    },
    "contributors": [
        "© OpenStreetMap contributors"
    ],
    "version": "1.0.0"
}