Geocoding API

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.
Currently supported country tags are
  • UK: United Kingdom
  • SG: Singapore
  • 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>
}

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"
}

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"
}

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"
}
Table of Contents