Custom POIs

Naurt also facilities the creation of custom Points of Interest (POIs). This could be anything from the location of a parking meter on the street to the location of the gate in a gated community. Once created, custom POIs can be searched just like any other delivery data Naurt may have. The only difference is that this data is completely private and can only be accessed from your account.

Creating a custom POI

All custom POIs require a poi_type and a location. The location should be provided in WGS84 degrees and the poi_type should be a plain string. For example, in the case of a parking meter, the poi type would be likely be parking_meter.

The value of poi_type is subject to some restrictions...

Now we're ready to add some information to the custom POI.

Addresses

When creating a custom POI with Naurt, you're able to add an address in a structured or unstructured format. Naurt will sanitize it and make it searchable in a flexible way to ensure you don't have to worry about address variations when searching for it.

JSON metadata

To each POI, you're also able to attach JSON metadata (up to 8kb). This could contain any useful information a delivery driver might want to know; such as pin combinations for gates or whether the resident has a dog: {gate_pin":0123,"has_dog": false}. Once stored Naurt offers partial matching so you can retrieve all POIs where has_dog: false.

We recommend using both JSON metadata and an address if possible, but either can be used on it's own.

Request

The same POI endpoint is used for creating custom Points of Interest. However, ensure that you use a PUT request when creating data with Naurt.

PUT

https://api.naurt.net/poi/v3

curl

curl -X PUT \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{
    "poi_type": "test_custom_delivery",
    "latitude": 50.854524,
    "longitude":-0.028251,
    "metadata":{"delivery_difficulty": 10},
    "address_json": {
        "street_number": "100",
        "street": "Wiggles Road", 
        "city": "Metropolis", 
        "country": "United Kingdom"
    }}' \
'https://api.naurt.net/poi/v3'

Response

Naurt responds with a JSON containing a confirmation of creation and a unique poi_id. The id can later be used to search for this POI directly.

JSON

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

Searching custom POIs

When searching for a custom POI you've created, you're also able to search by a partial match on the JSON metadata in addition to the standard ways to search with Naurt. This opens up several combinations of search:

By Address
By Metadata
By Address & Metadata
By Location
By Location & Metadata

When you search for a custom POI, you're able to search by more terms than you would a standard Naurt building entrance or parking spot. You can search with metadata alone, using partial JSON matching, the address, or using a reverse geocode. Also, when custom POIs are present in the Naurt response, their full metadata is also returned.

Metadata

Let's use the example POI above and try and find it with the Naurt POI API. One way would be to specify the type of poi we're looking for, test_custom_delivery and then provide the metadata we would like to match on.

Request

curl

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{
  "poi_types":["test_custom_delivery"],
  "metadata":{"delivery_difficulty": 10}
}' \
'https://api.naurt.net/poi/v3'

Response

JSON

{
  "additional_matches": null,
  "best_match": {
    "address": {
      "city": "metropolis",
      "country": "united kingdom",
      "county": "",
      "house_name": "",
      "postalcode": "",
      "state": "",
      "street": "wiggles road",
      "street_number": "100",
      "unit": ""
    },
    "contributors": [
      "© OpenStreetMap contributors"
    ],
    "latitude": 50.854524,
    "longitude": -0.028251,
    "metadata": {
      "delivery_difficulty": 10
    },
    "poi_id": "36dcd3ce-6123-46b3-9b1c-3868545b8c89",
    "poi_type": "test_custom_delivery"
  }
}

Whenever you make a request with metadata, only your custom POIs will be searched. You will not obtain results from Naurt's parking spot and building entrance data.

Address

If we wanted to search by address instead, we could do that and find the same data.

Request

curl

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{
  "poi_types": ["test_custom_delivery"],
  "address_string": "100 Wiggles Road, Metropolis, United Kingdom"
}' \
'https://api.naurt.net/poi/v3'

Response

JSON

{
  "additional_matches": null,
  "best_match": {
    "address": {
      "city": "metropolis",
      "country": "united kingdom",
      "county": "",
      "house_name": "",
      "postalcode": "",
      "state": "",
      "street": "wiggles road",
      "street_number": "100",
      "unit": ""
    },
    "contributors": [
      "© OpenStreetMap contributors"
    ],
    "latitude": 50.854524,
    "longitude": -0.028251,
    "metadata": {
      "delivery_difficulty": 10
    },
    "poi_id": "36dcd3ce-6123-46b3-9b1c-3868545b8c89",
    "poi_type": "test_custom_delivery"
  }
}

Reverse lookup

Alternatively, we might want to look for all custom POIs tagged with test_custom_delivery in a 200m radius. When we do a reverse look up, the distance to each POI is also provided.

Request

curl

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{
  "poi_types":["test_custom_delivery"], 
  "metadata":{"delivery_difficulty": 10}
  "latitude": 50.85452,
  "longitude": -0.028251,
  "distance_filter": 200,
}' \
'https://api.naurt.net/poi/v3'

Response

JSON

{
  "additional_matches": null,
  "best_match": {
    "address": {
      "city": "metropolis",
      "country": "united kingdom",
      "county": "",
      "house_name": "",
      "postalcode": "",
      "state": "",
      "street": "wiggles road",
      "street_number": "100",
      "unit": ""
    },
    "contributors": [
      "© OpenStreetMap contributors"
    ],
    "distance": 0.44498196030348697,
    "latitude": 50.854524,
    "longitude": -0.028251,
    "metadata": {
      "delivery_difficulty": 10
    },
    "poi_id": "36dcd3ce-6123-46b3-9b1c-3868545b8c89",
    "poi_type": "test_custom_delivery"
  }
}

Full Naurt search

The search scenarios above were limited to searching for custom POIs. Let's say you've created a POI with the same address as one already in Naurt's publicly available parking and entrance data. To get results from both sources, you can include the naurt_door and naurt_parking types. These are normally specified as the default when the poi_types field is omitted.

In the best match field, Naurt will return the POI which best matches the address, metadata, or latitude/longitude provided. If you want more results, use the additional_matches field.

In the example below, a custom POI has already been created which matched with some Naurt data in Singapore.

Request

curl

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{
  "poi_types": ["test_custom_delivery","naurt_door","naurt_parking"],
  "address_string": "100 Wiggles Road, Metropolis, United Kingdom",
  "additional_matches": true,
}' \
'https://api.naurt.net/poi/v3'

Response

JSON

{
  "additional_matches": [
    {
      "address": {
        "city": "singapore",
        "country": "singapore",
        "county": "",
        "house_name": "northshore straits view",
        "postalcode": "821421",
        "state": "",
        "street": "northshore drive",
        "street_number": "421a",
        "unit": ""
      },
      "contributors": [
        "© OpenStreetMap contributors"
      ],
      "geojson": {
        "features": [
          {
            "geometry": {
              "coordinates": [
                103.90425798935956,
                1.4191534195535354
              ],
              "type": "Point"
            },
            "properties": {
              "number_of_visits": 0
            },
            "type": "Feature"
          },
          {
            "geometry": {
              "coordinates": [
                [
                  [
                    103.90419020186802,
                    1.419166421172768
                  ],
                  [
                    103.9041908425829,
                    1.4192028484887755
                  ],
                  [
                    103.90432683289258,
                    1.419200458037697
                  ],
                  [
                    103.90432619217556,
                    1.4191640307217273
                  ],
                  [
                    103.90419020186802,
                    1.419166421172768
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "properties": {
              "number_of_visits": 0
            },
            "type": "Feature"
          }
        ],
        "type": "FeatureCollection"
      },
      "latitude": 1.4191534195535354,
      "longitude": 103.90425798935956,
      "poi_id": "3e6f7674-af9d-41a1-a23f-1912e0cfaba4",
      "poi_type": "naurt_destination"
    },
    {
      "address": {
        "city": "singapore",
        "country": "singapore",
        "county": "",
        "house_name": "northshore straits view",
        "postalcode": "821421",
        "state": "",
        "street": "northshore drive",
        "street_number": "421a",
        "unit": ""
      },
      "contributors": [
        "© OpenStreetMap contributors"
      ],
      "latitude": 1.419128,
      "longitude": 103.904317,
      "metadata": {
        "delivery_difficulty": 10
      },
      "poi_id": "1419d1cd-f420-4992-acdb-edc5f42caa0b",
      "poi_type": "test_custom_delivery"
    }
  ],
  "best_match": {
    "address": {
      "city": "singapore",
      "country": "singapore",
      "county": "",
      "house_name": "northshore straits view",
      "postalcode": "821421",
      "state": "",
      "street": "northshore drive",
      "street_number": "421a",
      "unit": ""
    },
    "contributors": [
      "© OpenStreetMap contributors"
    ],
    "geojson": {
      "features": [
        {
          "geometry": {
            "coordinates": [
              103.90425798935956,
              1.4191534195535354
            ],
            "type": "Point"
          },
          "properties": {
            "number_of_visits": 0
          },
          "type": "Feature"
        },
        {
          "geometry": {
            "coordinates": [
              [
                [
                  103.90419020186802,
                  1.419166421172768
                ],
                [
                  103.9041908425829,
                  1.4192028484887755
                ],
                [
                  103.90432683289258,
                  1.419200458037697
                ],
                [
                  103.90432619217556,
                  1.4191640307217273
                ],
                [
                  103.90419020186802,
                  1.419166421172768
                ]
              ]
            ],
            "type": "Polygon"
          },
          "properties": {
            "number_of_visits": 0
          },
          "type": "Feature"
        }
      ],
      "type": "FeatureCollection"
    },
    "latitude": 1.4191534195535354,
    "longitude": 103.90425798935956,
    "poi_id": "3e6f7674-af9d-41a1-a23f-1912e0cfaba4",
    "poi_type": "naurt_destination"
  }
}

QuickstartReverse Geocoding

QuickstartGenerate data