Bulk API - Beta

The bulk API is currently in beta, and you should expect breaking changes to the interface before it is finalised

Introduction

Endpoint

All bulk requests should be sent to Naurt's final-destination-bulk endpoint.

POST
https://api.naurt.net/final-destination-bulk/v1

Key things to know

  • The bulk API allows you to make many Naurt geocodes within one API call.
  • Up to 200 geocodes can be sent in a single request.
  • Your API key usage is shared between the bulk and standard final destination endpoint.
  • Each individual geocode is equivalent to one API call. For example, one bulk request that contains 5 search addresses will result in 5 API calls being tallied against your key.

The interface and search functionality is virtually identical to the standard final destination geocoder, albeit nested into lists. Therefore, you may consult the standard final destination documentation for precise details.

Request

Naurt data can be searched via a POST request to the final-destination bulk 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-bulk/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "batch_requests": [
        {
            "address_string": Option<String>,
            "country": Option<String>,
            "latitude": Optional<Float>,
            "longitude": Optional<Float>,
            "distance_filter": Optional<Float>
        },
        {
            // More requests here...
        }
    ]
}
Additional matches are NOT currently supported within the bulk API.

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 25,000 metres.
address_stringStringYesNoneAn address string. Good formatting, spelling, and completeness will offer the best search results.
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 '{"batch_requests": [{"address_string": "Westminster Hall" ,"country": "UK"}, {"address_string": "Wales Millennium Centre", "country": "UK"}]}' \
'https://api.naurt.net/final-destination-bulk/v1'

Response

Success

A 200 response code indicates a successful response with the format as follows.

JSON
{
    "matches": [
        {
            "best_match": Optional<FINAL DESTINATION RESPONSE FORMAT>
        }
    ],
    "version": Optional<String>,
    "request_id": Optional<String>
}

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

Naurt will identify the single best match for you. Currently, the bulk endpoint does not support additional matches.

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

Naurt will keep the addresses you searched for in the same order in the response. Therefore, a no match message will appear for each individual request which had no matches.

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.
  • No more than 200 geocodes can be sent in a single 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-bulk/v1"

payload = json.dumps({
    "batch_requests":[{
        "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({
  batch_requests: [
    {
      latitude: 11.0,
      longitude: 12.0,
    },
  ],
});

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

fetch("https://api.naurt.net/final-destination-bulk/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#"{
    "batch_requests": [
        {
        "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-bulk/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 \"batch_requests\": [{ \"latitude\": 11.0,\r\n    \"longitude\": 12.0 }]   \r\n}");
Request request = new Request.Builder()
  .url("https://api.naurt.net/final-destination-bulk/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-bulk/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 \"batch_requests\": [{ \"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-bulk/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 =>'{
  "batch_requests": [
    {
    "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-bulk/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({
  "batch_requests": [
    {
        "latitude": 11.0,
        "longitude": 12.0
    }
  ]
  })

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

Request Examples

Request
POST  https://api.naurt.net/final-destination-bulk/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "batch_requests": [
        {
            "address_string": "Tower of London",
            "country": "UK"
        }
    ]
}
Response
{
    "matches": [
        "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.

Request
POST https://api.naurt.net/final-destination-bulk/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "batch_requests": [
        {
        "address_string": "Trinity Trees",
        "latitude": 50.76,
        "longitude": 0.28,
        "country": "UK"
        }
    ]
}
Response
{
    "matches": [
        "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 25,000m.

Request
POST https://api.naurt.net/final-destination-bulk/v1
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "batch_requests": [
        {
        "address_string": "Trinity Trees",
        "latitude": 50.77,
        "longitude": 0.29,
        "distance_filter": 7000,
        "country": "UK"
        }
    ]
}
Response
{
    "matches": [
        "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