Geocoding API

The V1 endpoints for final destination are now legacy. It is strongly recommended to use the V2 endpoint, which can be found here

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/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
  "address_string": Option<String>, 
  "country": Option<String>,
  "latitude": Optional<Float>,
  "longitude": Optional<Float>,
  "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.
address_stringStringYesNoneAn address string. Good formatting, spelling, and completeness will offer the best search results.
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.
address_structuredObjectYesNoneSee 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 '{"naurt_address_string": "Westminster Hall" ,"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>>,
  "version": Optional<String>,
  "request_id": Optional<String>
}

Should you experience any issues with a request, please cite the reuqest_id in communications with Naurt.

Naurt will identify the single best match for you. 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>
}
  • Note that the address field is the normalised address and may not match the address you searched with.
  • 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.

Code Examples

Below are some basic coded templates showing how to use the final-destination API from different languages.

Python
import requests
import json

url = "https://api.naurt.net/final-destination/v1"

payload = json.dumps({
  "latitude": 11.0,
  "longitude": 12.0,

})
headers = {'Content-Type': 'application/json', 'Authorization':'<API_KEY_HERE>'}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
Javascript
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "<API_KEY_HERE>");
var raw = JSON.stringify({
  "latitude": 11.0,
  "longitude": 12.0
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.naurt.net/final-destination/v1", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::builder()
        .build()?;

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Content-Type", "application/json".parse()?);
    headers.insert("Authorization", "<API_KEY_HERE>".parse()?);
    let data = r#"{
    "latitude": 11.0,
    "longitude": 12.0
    }"#;

    let json: serde_json::Value = serde_json::from_str(&data)?;

    let request = client.request(reqwest::Method::POST, "https://api.naurt.net/final-destination/v1")
        .headers(headers)
        .json(&json);

    let response = request.send().await?;
    let body = response.text().await?;

    println!("{}", body);

    Ok(())
}
Java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"latitude\": 11.0,\r\n    \"longitude\": 12.0\r\n}");
Request request = new Request.Builder()
  .url("https://api.naurt.net/final-destination/v1")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "<API_KEY_HERE>")
  .build();
Response response = client.newCall(request).execute();
C
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
  curl_easy_setopt(curl, CURLOPT_URL, "https://api.naurt.net/final-destination/v1");
  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
  curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, "Authorization: <API_KEY_HERE>");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  const char *data = "{\r\n   \"latitude\": 11.0,\r\n    \"longitude\": 12.0\r\n}";
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
  res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);
PHP

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.naurt.net/final-destination/v1',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "latitude": 11.0,
    "longitude": 12.0
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: <API_KEY_HERE>'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
Ruby
  require "uri"
  require "json"
  require "net/http"

  url = URI("https://api.naurt.net/final-destination/v1")

  https = Net::HTTP.new(url.host, url.port)
  https.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Content-Type"] = "application/json"
  request["Authorization"] = "<API_KEY_HERE>"
  request.body = JSON.dump({
    "latitude": 11.0,
    "longitude": 12.0
  })

  response = https.request(request)
  puts response.read_body

Request Examples

POST  https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "address_string": "Tower of London",
    "country": "UK"
}

{
    "best_match": {
        "address": "Byward Tower, The Tower Of London, Tower Hill, London, Greater London, England, United Kingdom, EC3N 4AB",
        "geojson": {
        "features": [
            {
            "geometry": {
                "coordinates": [
                [
                    -0.077962,
                    51.50782
                ]
                ],
                "type": "MultiPoint"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_door"
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    -0.077907,
                    51.507896
                    ],
                    [
                    -0.077934,
                    51.5079
                    ],
                    [
                    -0.077961,
                    51.507896
                    ],
                    [
                    -0.077979,
                    51.507881
                    ],
                    [
                    -0.077983,
                    51.507866
                    ],
                    [
                    -0.077974,
                    51.507847
                    ],
                    [
                    -0.077952,
                    51.507835
                    ],
                    [
                    -0.077962,
                    51.50782
                    ],
                    [
                    -0.077975,
                    51.507801
                    ],
                    [
                    -0.078003,
                    51.507801
                    ],
                    [
                    -0.078029,
                    51.507797
                    ],
                    [
                    -0.078047,
                    51.507782
                    ],
                    [
                    -0.078052,
                    51.507767
                    ],
                    [
                    -0.078042,
                    51.507751
                    ],
                    [
                    -0.078021,
                    51.50774
                    ],
                    [
                    -0.077993,
                    51.507736
                    ],
                    [
                    -0.077967,
                    51.50774
                    ],
                    [
                    -0.077949,
                    51.507755
                    ],
                    [
                    -0.077903,
                    51.507744
                    ],
                    [
                    -0.07792,
                    51.507713
                    ],
                    [
                    -0.077899,
                    51.507675
                    ],
                    [
                    -0.077839,
                    51.507694
                    ],
                    [
                    -0.077822,
                    51.507725
                    ],
                    [
                    -0.077833,
                    51.507729
                    ],
                    [
                    -0.077805,
                    51.507771
                    ],
                    [
                    -0.077863,
                    51.507786
                    ],
                    [
                    -0.077856,
                    51.507797
                    ],
                    [
                    -0.077813,
                    51.507866
                    ],
                    [
                    -0.077876,
                    51.507881
                    ],
                    [
                    -0.07789,
                    51.507889
                    ],
                    [
                    -0.077907,
                    51.507896
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "naurt_type": "naurt_building",
                "contributors": [
                     "© OpenStreetMap contributors"
                ]
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    -0.077822,
                    51.507805
                    ],
                    [
                    -0.077841,
                    51.50777
                    ],
                    [
                    -0.078047,
                    51.507815
                    ],
                    [
                    -0.078028,
                    51.507849
                    ],
                    [
                    -0.077822,
                    51.507805
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_parking"
            },
            "type": "Feature"
            }
        ],
        "type": "FeatureCollection"
        },
        "id": "e99e36dd-18ad-9447-be35-9097fcfd8ea4"
    },
    "version": "1.3.0",
    "request_id": "47cdd308-39c8-4ff4-a982-8f6782ca51ab"
}

You can also provide a latitude and longitude to help narrow down the area of the search.

POST  https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "address_string": "Trinity Trees",
    "latitude": 50.76,
    "longitude": 0.28,
    "country": "UK"
}

{
    "best_match": {
        "address": "Flat 3, Trinity House, 28, Trinity Trees, Eastbourne, East Sussex, England, United Kingdom, BN21 3LH",
        "geojson": {
        "features": [
            {
            "geometry": {
                "coordinates": [
                [
                    0.288579,
                    50.767509
                ]
                ],
                "type": "MultiPoint"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_door"
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    0.288532,
                    50.767563
                    ],
                    [
                    0.288443,
                    50.767601
                    ],
                    [
                    0.288213,
                    50.767529
                    ],
                    [
                    0.28833,
                    50.76741
                    ],
                    [
                    0.288596,
                    50.76749
                    ],
                    [
                    0.288563,
                    50.767529
                    ],
                    [
                    0.288532,
                    50.767563
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "naurt_type": "naurt_building",
                "contributors": [
                     "© OpenStreetMap contributors"
                ]
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    0.288383,
                    50.76735
                    ],
                    [
                    0.288357,
                    50.767383
                    ],
                    [
                    0.288549,
                    50.767444
                    ],
                    [
                    0.288575,
                    50.767411
                    ],
                    [
                    0.288383,
                    50.76735
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_parking"
            },
            "type": "Feature"
            }
        ],
        "type": "FeatureCollection"
        },
        "id": "871006b6-ead4-8432-78bd-da39ffaf1c39"
    },
    "version": "1.3.0",
    "request_id": "47cdd308-39c8-4ff4-a982-8f6782ca51ab"
}

To narrow down results to a certain place, a distance_filter can be applied. By default, this is set to 5000m. The largest value a distance_filter can be set to is 25000m.

POST  https://api.naurt.net/final-destination/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "address_string": "Trinity Trees",
    "latitude": 50.77,
    "longitude": 0.29,
    "distance_filter": 7000,
    "country": "UK"
}

{
    "best_match": {
        "address": "Flat 3, Trinity House, 28, Trinity Trees, Eastbourne, East Sussex, England, United Kingdom, BN21 3LH",
        "distance": 1022.66601273,
        "geojson": {
        "features": [
            {
            "geometry": {
                "coordinates": [
                [
                    0.288579,
                    50.767509
                ]
                ],
                "type": "MultiPoint"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_door"
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    0.288532,
                    50.767563
                    ],
                    [
                    0.288443,
                    50.767601
                    ],
                    [
                    0.288213,
                    50.767529
                    ],
                    [
                    0.28833,
                    50.76741
                    ],
                    [
                    0.288596,
                    50.76749
                    ],
                    [
                    0.288563,
                    50.767529
                    ],
                    [
                    0.288532,
                    50.767563
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "naurt_type": "naurt_building",
                "contributors": [
                     "© OpenStreetMap contributors"
                ]
            },
            "type": "Feature"
            },
            {
            "geometry": {
                "coordinates": [
                [
                    [
                    0.288383,
                    50.76735
                    ],
                    [
                    0.288357,
                    50.767383
                    ],
                    [
                    0.288549,
                    50.767444
                    ],
                    [
                    0.288575,
                    50.767411
                    ],
                    [
                    0.288383,
                    50.76735
                    ]
                ]
                ],
                "type": "Polygon"
            },
            "properties": {
                "accuracy": {
                    "quality": "high"
                },
               "naurt_type": "naurt_parking"
            },
            "type": "Feature"
            }
        ],
        "type": "FeatureCollection"
        },
        "id": "871006b6-ead4-8432-78bd-da39ffaf1c39"
    },
    "version": "1.3.0",
    "request_id": "47cdd308-39c8-4ff4-a982-8f6782ca51ab"
}
Table of Contents