Search POIs


Search Request

Once a POI is created either with the API, or automatically generated via Naurt SDKs, they can be filtered geospatially or by the JSON metadata provided. Additionally, they can be directly retrieved using their unique ID.

POIs can be searched via a POST request to the POI API endpoint. Again, data should be provided as a JSON in the body of the request and not in the URL.

GET/POST  https://api.naurt.net/poi/v3
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
  "latitude": Optional<Float>,
  "longitude": Optional<Float>,
  "distance_filter": Optional<Float>,
  "poi_types": Optional<[String]>,
  "address_json": Optional<{
    "unit": Optional<String>,
    "house_name": Optional<String>,
    "street_number": Optional<String>,
    "street": Optional<String>,
    "city": Optional<String>,
    "county": Optional<String>,
    "state": Optional<String>,
    "country": Optional<String>,
    "postalcode": Optional<String>
  }>,
  "address_string": Option<String>,
  "poi_id": Optional<String>, 
  "metadata": Optional<JSON Object>,
  "additional_results": Optional<Bool>
}
curl -XPOST -H "Content-type: application/json" -H "Authorization: <API_KEY_HERE>" -d '{"poi_types":["naurt_door", "restaurant", "naurt_parking"],"latitude": 52.0,"longitude": 0.1}' 'https://api.naurt.net/poi/v3'

Search Parameters

  • Optional<poi_id>: A unique POI ID.
  • Optional<poi_types>: The types of POI you wish to query. Maximum of 5 unique types per request and a minimum of 1. "*" acts as a wildcard for all types of POI and "^" will append all automatically generated Naurt POI types to your request, currently naurt_door & naurt_parking.
  • Optional<metadata>: A JSON object used to find matches within previous POI metadata. For example a search of {"bench_type":"wooden"} would be a match to existing POIs with the metadata {"bench_type":"wooden", "location":"UK"}. Limited to 8kb.
  • Optional<latitude>: A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90.
  • Optional<longitude>: A valid longitude in WGS84 degrees. Range: -180 <= lon < 180.
  • Optional<distance_filter>: 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.
  • Optional<address_string> OR Optional<address_json>, but not both. Use this to specify the address. Note that address_json may only contain the fields specified above
  • Optional<additional_results>: Default false. Set to true if you want additional results beyond the best match

Minimum search fields

You need to specify at least some search fields in your request, at minimum a poi_id OR poi_types OR a position (with latitude AND longitude)


Search Response

Success

A 200 response code indicates a successful response.

The response format is as follows

{
	"best_match": <POI RESPONSE FORMAT>,
	"additional_matches": Optional<List<POI RESPONSE FORMAT>>
}

Naurt will identify the single best match for you. You will only have an additional_matches field if you set additional_results to true in the request. Note that the first result in additional_matches (if present) will be a duplicate of the best_match

The POI RESPONSE FORMAT is

{
  "poi_id": String,
  "latitude": float,
  "longitude": float,
  "address": Optional<{
    "unit": Optional<String>,
    "house_name": Optional<String>,
    "street_number": Optional<String>,
    "street": Optional<String>,
    "city": Optional<String>,
    "county": Optional<String>,
    "state": Optional<String>,
    "country": Optional<String>,
    "postalcode": Optional<String>,
  }>,
  "metadata": Optional<JSON>,
  "geojson": Optional<JSON>,
  "contributors": Optional<List<String>>,
  "confidence": Optional<float>,
  "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 POI from that position in metres.

naurt_destination

If your `poi_types` contains "*", "^", or "naurt_door" AND "naurt_parking" you might get a poi_type back of naurt_destination - this just means that the address had a naurt_door and a naurt_parking - and Naurt has fused these together


Search Examples



Example Request // to find POIs with matching type and empty metadata.

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["naurt_door"], }


Example Response 

{ "best_match": { "poi_id": "fdb325f3-e360-4c40-bf4a-342bc75d4f30", "poi_type": "naurt_door", "latitude": 10.0, "longitude": 1.0, "address": { "street_number": "Town House", "street": "Wiggly Road", "city": "Metropolis", "county": "Wessex" }, "geojson": { "features": [ { "geometry": { "coordinates": [ 1.0, 10.0 ], "type": "Point" }, "properties": null, "type": "Feature" } ], "type": "FeatureCollection" } } }


Example Request // to find POIs with matching type and metadata

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["bench"], "metadata": {"bench_type": "wooden"}, }


Example Response 

{ "best_match": { "poi_id": "a2f47eb8-faf7-4fd0-af28-434bb52d98d6", "poi_type": "bench", "latitude": 10.0, "longitude": 1.0, "metadata": { "bench_type": "wooden" } } }


Example Request // to find closest POIs of any type.

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["*"], "latitude": 11.0, "longitude": 12.0 }


Example Response

{ "best_match": { "poi_id":"d9278c7d1-c8b5-4480-8434-10bd1fe9aa3b", "poi_type": "bench", "latitude": 11.0, "longitude": 12.0, "distance": 0.0, "metadata": { "bench_type": "wooden" } } }


Example Request // to find closest POIs of any type within 1km.

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["*"], "latitude": 11.0, "longitude": 12.0, "distance_filter": 1000.0 }


Response

{ "best_match": { "poi_id":"6f1a5a9b-de0d-4054-a6e0-7e1ddd1bebef", "poi_type": "bench", "latitude": 11.0, "longitude": 12.0, "distance": 0.0, "metadata": { "bench_type": "wooden" } } }


Example Request // to find closest POIs with matching type & metadata, and within 1km

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["bench"], "metadata": {"bench_type": "wooden"}, "longitude": 12.0, "latitude": 11.0, "distance_filter": 1000.0, }


Response

{ "bench": [ { "poi_id":"364ee39e-e820-45d1-b720-89662090ffa6", "latitude": 11.0, "longitude": 12.0, "distance": 0.0, "metadata": { "bench_type": "wooden", "bench_size": "Large", "country": "Italy" } } ] }


Example Request // to find closest POIs of each POI type requested.

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["bench", "naurt_parking"], "longitude": 12.0, "latitude": 11.0, "additional_matches": true }


Response

{ "best_match": { "poi_id":"64b19847-c64f-4a3a-8ebd-6aa03eb0653b", "poi_type": "naurt_parking", "latitude": 51.8167706, "longitude": -0.1169278, "distance": 4568305.996586231, "address": {"street": "Wiggly road"}, "geojson":{ "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -0.21480920658208905, 53.350378660735345 ], [ -0.21480920658208905, 53.21454311151439 ], [ 0.024463352071904865, 53.21454311151439 ], [ 0.024463352071904865, 53.350378660735345 ], [ -0.21480920658208905, 53.350378660735345 ] ] ], "type": "Polygon" } } ], "type": "FeatureCollection" } }, "additional_matches": [ { "poi_id":"64b19847-c64f-4a3a-8ebd-6aa03eb0653b", "poi_type": "naurt_parking", "latitude": 51.8167706, "longitude": -0.1169278, "distance": 4568305.996586231, "address": {"street": "Wiggly road"}, "geojson":{ "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -0.21480920658208905, 53.350378660735345 ], [ -0.21480920658208905, 53.21454311151439 ], [ 0.024463352071904865, 53.21454311151439 ], [ 0.024463352071904865, 53.350378660735345 ], [ -0.21480920658208905, 53.350378660735345 ] ] ], "type": "Polygon" } } ], "type": "FeatureCollection" } }, { "poi_id":"ca5c9254-5544-44f2-8649-a484def39a7f", "poi_type": "naurt_parking", "latitude": 30.8168135, "longitude": -0.116912, "distance": 4568310.182186027, "address": {"street": "Wiggly road"}, "geojson":{ "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -0.21480920658208905, 53.350378660735345 ], [ -0.21480920658208905, 53.21454311151439 ], [ 0.024463352071904865, 53.21454311151439 ], [ 0.024463352071904865, 53.350378660735345 ], [ -0.21480920658208905, 53.350378660735345 ] ] ], "type": "Polygon" } } ], "type": "FeatureCollection" } }, { "poi_id":"1ca6fd2d-3bc0-45fd-bb19-e1d3bfd55f8a", "poi_type": "bench", "latitude": 11.0, "longitude": 12.0, "distance": 0.0, "metadata": { "bench_type": "wooden", "bench_size": "Large" } }, { "poi_id":"e2ccaa4e-9ce2-4eca-9a34-bfac228791db", "poi_type": "bench", "latitude": 11.0, "longitude": 10.0, "distance": 218549.134624264, "metadata": { "bench_type": "wooden", "bench_size": "Large" } }, ] }


Example Request // to find closest POIs for every naurt type (naurt_door & naurt_parking)

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "poi_types": ["^"], "longitude": 12.0, "latitude": 11.0, "additional_matches": true }


Response

{ "best_match": { "poi_id":"a937a095-4e06-4fe3-a429-becbf3fcd884", "poi_type": "naurt_door", "latitude": 51.8167311, "longitude": -0.1169724, "distance": 4565302.806054892, "metadata": {"building": true}, "geojson": { "features": [ { "geometry": { "coordinates": [ 10.0, 10.0 ], "type": "Point" }, "properties": null, "type": "Feature" } ], "type": "FeatureCollection" } }, "additional_matches": [ { "poi_id":"a937a095-4e06-4fe3-a429-becbf3fcd884", "poi_type": "naurt_door", "latitude": 51.8167311, "longitude": -0.1169724, "distance": 4565302.806054892, "metadata": {"building": true}, "geojson": { "features": [ { "geometry": { "coordinates": [ 10.0, 10.0 ], "type": "Point" }, "properties": null, "type": "Feature" } ], "type": "FeatureCollection" } },{ "poi_id":"92d24787-e363-4ef1-9faa-72d3ee4c4cdc", "poi_type": "naurt_parking", "latitude": 52.8167706, "longitude": -0.16169278, "distance": 4568305.996586231, "address": {"street": "Wiggly Road"}, "geojson":{ "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -0.21480920658208905, 53.350378660735345 ], [ -0.21480920658208905, 53.21454311151439 ], [ 0.024463352071904865, 53.21454311151439 ], [ 0.024463352071904865, 53.350378660735345 ], [ -0.21480920658208905, 53.350378660735345 ] ] ], "type": "Polygon" } } ], "type": "FeatureCollection" } } ] }


Example Request // to find closest POIs of each POI type requested.

GET/POST https://api.naurt.net/poi/v3 Content-Type: application/json Authorization: { "api_key": API_KEY, "poi_id": "6de68e8c-4526-4f80-9d7b-f87716d07555" }


Response

{ "best_match": { "poi_id": "6de68e8c-4526-4f80-9d7b-f87716d07555", "poi_type": "naurt_parking", "latitude": 40.239875, "longitude": 122.2312, "address": {"country": "uk"}, "geojson":{ "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -0.21480920658208905, 53.350378660735345 ], [ -0.21480920658208905, 53.21454311151439 ], [ 0.024463352071904865, 53.21454311151439 ], [ 0.024463352071904865, 53.350378660735345 ], [ -0.21480920658208905, 53.350378660735345 ] ] ], "type": "Polygon" } } ], "type": "FeatureCollection" } } }


If there are no POIs available which match the search term, the response JSON will not contain any poi_types, but instead a "naurt_info" message.

{"naurt_info":"Successful query. No POIs match search conditions"}

Below are some basic coded examples showing how to use the POI API from different languages. If you're on Android or iOS, Naurt Lite & Location Manager SDKs offer a connivent wrapper for this API.


 

import requests import json url = "https://api.naurt.net/poi/v3" payload = json.dumps({ "poi_types": ["naurt_door"], "address": {"country": "UK"}, "latitude": 11.0, "longitude": 12.0 }) headers = {'Content-Type': 'application/json', 'Authorization':''} response = requests.request("POST", url, headers=headers, data=payload) print(response.text)

 

var myHeaders = new Headers(); myHeaders.append("Content-Type", "application/json"); myHeaders.append("Authorization", ""); var raw = JSON.stringify({ "poi_types": [ "naurt_door" ], "address": { "country": "UK" }, "latitude": 11.0, "longitude": 12.0 }); var requestOptions = { method: 'POST', headers: myHeaders, body: raw, redirect: 'follow' }; fetch("https://api.naurt.net/poi/v3", requestOptions) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log('error', error));

 

#[tokio::main] async fn main() -> Result<(), Box> { 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#"{
"poi_types": [
    "bench"
],
"address": {
    "bench_type": "wooden"
},
"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/poi/v3")
    .headers(headers)
    .json(&json);

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

println!("{}", body);

Ok(())

}

 

OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\r\n \"poi_types\": [\"bench\"],\r\n \"metadata\": {\"bench_type\": \"wooden\"},\r\n \"latitude\": 11.0,\r\n \"longitude\": 12.0\r\n}"); Request request = new Request.Builder() .url("https://api.naurt.net/poi/v3") .method("POST", body) .addHeader("Content-Type", "application/json") .addHeader("Authorization", "") .build(); Response response = client.newCall(request).execute();

 

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/poi/v3"); 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: "); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = "{\r\n \"poi_types\": [\"bench\"],\r\n \"metadata\": {\"bench_type\": \"wooden\"},\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);

 


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.naurt.net/poi/v3',
  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 =>'{
    "poi_types": ["bench"],
    "metadata": {"bench_type": "wooden"},
    "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;

 
  

require "uri" require "json" require "net/http" url = URI("https://api.naurt.net/poi/v3") 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"] = "" request.body = JSON.dump({ "poi_types": [ "bench" ], "metadata": { "bench_type": "wooden" }, "latitude": 11.0, "longitude": 12.0 }) response = https.request(request) puts response.read_body



Search Restrictions

POIs 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.
  • metadata for each POI search is limited to 8kb to ensure proper use and must be a JSON Object.
  • Currently there is a maximum return of 25 POIs per request.