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.


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 -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":"restaurant_debug"}'

Create Parameters

  • latitude: A valid latitude in WGS84 degrees. Range: -90 <= lat <= 90.

  • longitude: A valid longitude in WGS84 degrees. Range: -180 <= lon < 180.

  • poi_type: 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.

  • Optional<metadata>: 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

  • Optional<address_string> OR Optional<address_json>, but not both. Use this to specify the address


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.

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

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.

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, 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_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': '' } response = requests.request("PUT", 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_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" } }); var requestOptions = { method: 'PUT', 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_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"
  }
}"#;

let json: serde_json::Value = serde_json::from_str(&data)?;

let request = client.request(reqwest::Method::PUT, "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, "{\"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\" }}"); Request request = new Request.Builder() .url("https://api.naurt.net/poi/v3") .method("PUT", 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, "PUT"); 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 = "{\"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\" }}"; 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 => 'PUT',
  CURLOPT_POSTFIELDS =>'{"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"
    }
  }',
  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::Put.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "" request.body = JSON.dump({ "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" } }) response = https.request(request) puts response.read_body




FAQs

What's the lifespan of POIs? Do they ever expire?

POIs never expire. If you want to remove them, you can use the delete request