Search POIs
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'
Parameters
| Parameter | Type | Optional | Default | Description |
|---|---|---|---|---|
| poi_id | String (UUID) | True | None | The unique POI ID for direct lookup. |
| poi_types | ListString | Yes | naurt_door & naurt_parking | The types of POI you wish to query. If omitted, this defaults to naurt_parking and naurt_door. There can be a maximum of 5 poi_types in one request. * is a wildcard, and ^ is shorthand for naurt_door and naurt_parking. When used in conjunction with other types, it will append onto the end. |
| metadata | JSON | Yes | None | 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. |
| 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 | None | 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. |
| address_string | String | Yes | None | Used to look up data for an address. Naurt will attempt to normalize the address and search it when provided in this manner. |
| address_json | Json | Yes | None | User to look up data for an address. Addresses provided like this offer more accurate search results. Cannot be used at the same time as address_string. |
| additional_matches | Boolean | Yes | False | Provides up to 20 results beyond what Naurt classifies as the best_match. |
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.
About the naurt_destination return type
Failure
A response code other than 200 indicates a failure to retrieve the requested POIs.
401 Unauthorized
{"error":"Please ensure the request contains a valid API key."}
Search Examples
GET/POST https://api.naurt.net/poi/v3
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
"poi_types": ["bench"],
"metadata": {"bench_type": "wooden"},
}
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's 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':'<API_KEY_HERE>'}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
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.
metadatafor 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.