Create a POI

Create Request

POIs can be created via a PUT request to the POI API endpoint. The data should be provided as a JSON in the body of the request and not in the URL. You should provide your Naurt API key within the header of the request under Authorization.

JSON

PUT https://api.naurt.net/poi/v3
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
  "latitude": Float,
  "longitude": Float,
  "poi_type": 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>,
  "metadata": Optional<JSON Object>
}

curl

curl -X PUT \ 
https://api.naurt.net/poi/v3 \
-H "Content-Type: application/json" 
-H "Authorization:<API_KEY_HERE>" \
-d '{"latitude":52.0,"longitude":0.1,"poi_type":"delivery_debug", "metadata":{"delivery_difficulty":10}}'

Create Parameters

Parameter	Type	Optional	Default	Description
latitude	float	No	None	A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90.
longitude	float	No	None	A valid longitude in WGS84 degrees. Range: -180 <= lon < 180.
poi_type	String	No	None	An alphanumeric string which classifies your POI. For instance, `restaurant`, `bench`, `office`. Only alphanumeric characters are allowed with the exception of '_' and '-''. It also cannot contain "naurt" (case insensitive), be empty, or over 128 characters.
metadata	JSON	Yes	None	An optional but recommended JSON object which can later be used to filter POIs using matching patterns. Restricted the following may not be keys in your custom metadata - `unit`, `house_name`, `street_number`, `street`, `city`, `county`, `state`, `country`, `postalcode`, `address_string`, `address`.
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.

Create Response

Responses will always be formatted as a JSON whether successful or not. Upon successful creation of a new POI, a POI ID will be assigned and returned. This is the way a POI can be uniquely identified throughout Naurt's services and is formatted as a UUID v4. If a POI is created with an identical type and metadata to an existing POI, the location will be averaged and the same POI ID will be returned. This prevents identical data being represented as different locations inside the Naurt POI system.

Success

A 200 response code indicates a successful response and will look as follows.

JSON

200 OK
{"naurt_info":"Successful POI PUT","poi_id":"4ba21fcf-aed2-4729-a977-daf65ae79f0c"}

A POIs ID can also be retrieved via a GET request. It will later be needed if you wish to delete or modify a POI.

Failure

A response code other than 200 will indicate a failed request of some nature, for instance

JSON

401 Unauthorized 
{"error":"Please ensure the request contains a valid API key."}

Create Restrictions

POIs inserted 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 is limited to 8kb to ensure proper use and must be a JSON Object.
poi_type must be alphanumeric (except for "-" and "_") and cannot contain "naurt" (case insensitive), be an empty string, or over 128 characters.

Create Examples

When creating a custom POI ensure you include a detailed metadata that will enable you to search your data in a variety of ways later.

JSON

PUT https://api.naurt.net/poi/v3
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
  "poi_type": "delivery_debug",
  "metadata": {
    "delivery_difficulty": 9,
    "has_dog": false
  },
  "longitude": 10.0,
  "latitude": 1.0,
  "address_json": {
    "street_number": "12",
    "street": "Wiggly Road",
    "city": "Metropolis",
    "county": "Wessex",
    "state": "Midlandia",
    "country": "England",
    "postalcode": "SW1W 0NY",
  }
}

The above POI contains great metadata as it has been segmented and then could later be searched by any of the address fields as well as some custom rating data. The more detailed but segmented your data, the better.

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

python

import requests
import json 

url = "https://api.naurt.net/poi/v3"

payload = json.dumps({
  "poi_type": "delivery_debug",
  "metadata": {
    "delivery_difficulty": 9,
    "has_dog": false
  },
  "longitude": 10.0,
  "latitude": 1.0,
  "address_json": {
    "street_number": "12",
    "street": "Wiggly Road",
    "city": "Metropolis",
    "county": "Wessex",
    "state": "Midlandia",
    "country": "England",
    "postalcode": "SW1W 0NY"
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': '<API_KEY_HERE>'
}
response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

Poi_apiIntroduction

Poi_apiSearch POIs