Bulk API - Beta
Introduction
Endpoint
All bulk requests should be sent to Naurt's final-destination-bulk endpoint.
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.
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...
}
]
}
Parameters
Parameter | Type | Optional | Default | Description |
---|---|---|---|---|
latitude | float | Yes | None | A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90. |
longitude | float | Yes | None | A valid longitude in WGS84 degrees. Range: -180 <= lon < 180. |
distance_filter | float | Yes | 5000 | A 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_string | String | Yes | None | An address string. Good formatting, spelling, and completeness will offer the best search results. |
country | String | Yes | None | Optional but strongly suggested two digit country code which helps with performance. |
- UK: United Kingdom
- SG: Singapore
- US: United States
Example
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.
{
"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
{
"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
andlongitude
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.
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.
{ "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.
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)
Request Examples
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"
}
]
}
You can also provide a latitude
and longitude
to help narrow down the area
of the search.
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"
}
]
}
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.
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"
}
]
}