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 the building's entrances, parking zones, and outline.

Requests

All requests should be sent to Naurt's final-destination endpoint.

POST
https://api.naurt.net/final-destination/v2

Addresses

The simplest way to request Naurt data is via an address.

A POST request should be sent to the final-destination endpoint containing a JSON with the address that is to be searched.

JSON
{
  "queries": [
    {
      "address_string": "The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE",
      "country": "UK"
    }
  ]
}
Currently supported country tags are
  • AU: Australia
  • BR: Brazil (BETA)
  • CA: Canada
  • DE: Germany (BETA)
  • FR: France (BETA) (Please note that Naurt currently only covers Metropolitan France)
  • HK: Hong Kong (Preview)
  • IT: Italy (BETA)
  • JP: Japan (Preview)
  • KR: South Korea (Preview)
  • NZ: New Zealand
  • PT: Portugal (BETA)
  • SG: Singapore
  • TW: Taiwan (Preview)
  • UK: United Kingdom
  • US: United States

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

curl
curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"queries": [{"address_string":"The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE", "country": "UK"}] }' \
'https://api.naurt.net/final-destination/v2'
Python
import requests

API_KEY = "<API-KEY-HERE>"

url = "https://api.naurt.net/final-destination/v2"

json_request = {
  "queries": [{"address_string": "The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE", "country": "UK"}]
}

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

print(response.text)

Address and Location

If there are multiple similar addresses to the one you are searching, it might be useful to limit your search to a smaller area. For this, Naurt also allows you to specify a latitude & longitude, and optionally a distance_filter which defaults to 5000 metres. When used, only results within that distance of the provided position will be returned.

The distance_filter should always be specified in metres. It has a maximum value of 25,000 metres, a minimum value of 0 metres, and a default value of 5000 metres which applies even if this parameter is not provided.

JSON
{
  "address_string": "The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE",
  "location": {
    "latitude": 50.8353,
    "longitude": -0.1277,
    "distance_filter": 100,
  },
  "country": "UK"
}
curl
curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"queries": [{"address_string":"The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE", "latitude": 50.8353, "longitude": -0.1277, "distance_filter": 100, "country": "UK"}]}' \
'https://api.naurt.net/final-destination/v2'
Python
import requests

API_KEY = "<API-KEY-HERE>"

url = "https://api.naurt.net/final-destination/v2"

json_request = {
  "queries": [
    {
      "address_string": "The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE",
      "location": {
        "latitude": 50.8353,
        "longitude": -0.1277,
        "distance_filter": 100,
        },
      "country": "UK"
    }
  ]
}

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

print(response.text)

Responses

Within each response, Naurt provides a best_match to the requested address. As you'd expect, this is what Naurt believes to be the most relevant address for your request. However, by setting additional_matches: true in the body of your request, you can receive up to 4 additional matches which are relevant.

For each match Naurt provides the address and a GeoJSON containing the building entrances, parking zone, and building outline. Building entrances are type MultiPoint, and parking zones and building outlines are type Polygon,

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

Request
curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"queries": [{"address_string":"The Martha Gunn, 100 Upper Lewes Road, Brighton & Hove, United Kingdom, BN2 3FE", "country": "UK"}]}' \
'https://api.naurt.net/final-destination/v2'
Response
{
  "request_id": "6c4d399e-9a80-407e-bbf0-03a0ceec9aa2",
  "responses": [
    {
      "additional_matches": [],
      "best_match": {
        "address": "The Martha Gunn, 100 Upper Lewes Road, Brighton, BN2 3FE, United Kingdom",
        "geojson": {
          "features": [
            {
              "geometry": {
                "coordinates": [
                  -0.127716,
                  50.83548999999999
                ],
                "type": "Point"
              },
              "properties": {
                "naurt_type": "basic_geocode"
              },
              "type": "Feature"
            },
            {
              "geometry": {
                "coordinates": [
                  [
                    -0.1276612005649132,
                    50.83551796633867
                  ]
                ],
                "type": "MultiPoint"
              },
              "properties": {
                "accuracy": {
                  "quality": "high"
                },
                "naurt_type": "naurt_door"
              },
              "type": "Feature"
            },
            {
              "geometry": {
                "coordinates": [
                  [
                    [
                      -0.12759710000000002,
                      50.83546610000002
                    ],
                    [
                      -0.12773020000000002,
                      50.83540049999999
                    ],
                    [
                      -0.12775720000000002,
                      50.8354224
                    ],
                    [
                      -0.1277753,
                      50.83541339999999
                    ],
                    [
                      -0.1278599,
                      50.83548189999999
                    ],
                    [
                      -0.1277087,
                      50.8355564
                    ],
                    [
                      -0.12759710000000002,
                      50.83546610000002
                    ]
                  ]
                ],
                "type": "Polygon"
              },
              "properties": {
                "contributors": [
                  "© OpenStreetMap contributors"
                ],
                "naurt_type": "naurt_building"
              },
              "type": "Feature"
            },
            {
              "geometry": {
                "coordinates": [
                  [
                    [
                      -0.12773832667236262,
                      50.8355788306379
                    ],
                    [
                      -0.12776047994262066,
                      50.83559706502552
                    ],
                    [
                      -0.12786823371294276,
                      50.83554485044337
                    ],
                    [
                      -0.1278460804426847,
                      50.83552661603537
                    ],
                    [
                      -0.12773832667236262,
                      50.8355788306379
                    ]
                  ]
                ],
                "type": "Polygon"
              },
              "properties": {
                "accuracy": {
                  "quality": "high"
                },
                "minimum_parking_to_door_distance": 8.67,
                "naurt_type": "naurt_parking"
              },
              "type": "Feature"
            }
          ],
          "type": "FeatureCollection"
        },
        "id": "581b56ed-28b3-3dd8-9fb5-f236334da161"
      },
      "status": "ok"
    }
  ],
  "version": "v2.1.2-hf.1"
}
Table of Contents