Geocoding

Geocoding is the process of encoding an address into a latitude & longitude coordinate. With Naurt, this takes on a slightly different form. Instead of responding with a single coordinate, Naurt will respond with a GeoJSON containing building entrance(s) and parking zones.

Requests

All requests should be sent to Naurt's point of interest (POI) endpoint.

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

Unstructured Addresses

The simplest way to send a request to Naurt is via an unstructured address. All this means is that the address forms one long string.

A POST request should be sent to the POI endpoint containing a JSON with the address string.

{
  "address_string": "100, Upper Lewes Road, Brighton & Hove, United kingdom, BN2 3FE"
}

Don't forget to include the API key in the Authorization header.

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"address_string":"100, Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE"}' \
'https://api.naurt.net/poi/v3'

import requests

API_KEY = "<API-KEY-HERE>"

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

json_request = {
  "address_string": "100, Upper Lewes Road, Brighton & Hove, United kingdom, BN2 3FE"
}

response = requests.post(
  url,
  json=json_request,
  headers={
      "Authorization": API_KEY,
  },
)

print(response.text)

Structured Addresses

Structured addresses are where the individual components of the address, such as street number and city, are already split up. Using Naurt to geocode addresses in this format will enhance the accuracy of our search and return more relevant results.

{
  "address_json": {
    "street_number": "100",
    "street": "Upper Lewes Road",
    "city": "Brighton & Hove",
    "country": "United Kingdom",
    "postalcode": "BN2 3FE"
  }
}

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"address_json": {
    "street_number": "100",
    "street": "Upper Lewes Road", 
    "city": "Brighton & Hove", 
    "country": "United Kingdom", 
    "postalcode": "BN2 3FE" 
  }}' \
'https://api.naurt.net/poi/v3'

import requests

API_KEY = "<API-KEY-HERE>"

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

json_request = {
  "address_json": {
    "street_number": "100",
    "street": "Upper Lewes Road",
    "city": "Brighton & Hove",
    "country": "United Kingdom",
    "postalcode": "BN2 3FE"
  }
}

response = requests.post(
  url,
  json=json_request,
  headers={
      "Authorization": API_KEY,
  },
)

print(response.text)

Responses

Naurt responses contain two fields: best_match and additional_matches. The best match contains what Naurt believes to be the best possible match for the delivery address. If Naurt doesn't have data for the exact address or your search contains incomplete address data, Naurt will not return a best match and will instead return data within the additional matches field, though this is turned off by default. Up to 20 additional matches are returned, ordered by relevance.

Naurt provides the structured address and a GeoJSON containing the building entrances and parking polygons. Building entrances are MultiPoint and parking zones are MultiPolygon

An example response can be seen below plotted and as the GeoJSON response.

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"address_string":"100, Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE"}' \
'https://api.naurt.net/poi/v3'

{
  "best_match": {
    "address": {
      "city": "brighton & hove",
      "country": "united kingdom",
      "county": "",
      "house_name": "",
      "postalcode": "bn2 3fe",
      "state": "",
      "street": "upper lewes road",
      "street_number": "100",
      "unit": ""
    },
    "contributors": [
      "© OpenStreetMap contributors"
    ],
    "geojson": {
      "features": [
        {
          "geometry": {
            "coordinates": [
              -0.1276533875362692,
              50.83551065511638
            ],
            "type": "Point"
          },
          "properties": {
            "number_of_visits": 0
          },
          "type": "Feature"
        },
        {
          "geometry": {
            "coordinates": [
              [
                [
                  -0.127519890234697,
                  50.83546952769126
                ],
                [
                  -0.12756553081486807,
                  50.835447244964186
                ],
                [
                  -0.1276972076858581,
                  50.83555481857893
                ],
                [
                  -0.12765156706335587,
                  50.83557710135735
                ],
                [
                  -0.127519890234697,
                  50.83546952769126
                ]
              ]
            ],
            "type": "Polygon"
          },
          "properties": {
            "number_of_visits": 0
          },
          "type": "Feature"
        }
      ],
      "type": "FeatureCollection"
    },
    "latitude": 50.83551065511638,
    "longitude": -0.1276533875362692,
    "poi_id": "745d3e71-079c-4a08-a988-f973669a33be",
    "poi_type": "naurt_destination"
    "additional_matches": null,
  }
}

If both a parking spot and building entrance are available at the address, the returned POI type is naurt_destination. If only a parking spot is available it will be naurt_parking and if only a building entrance is available, it will be of type naurt_door.

Next up, reverse geocoding.