Make your first request

Tutorial

Welcome to Naurt, where geocoding meets last-mile delivery. Throughout this quickstart you’ll learn how to:

• Sign-up for your free Naurt API key.
• Geocode delivery addresses for precise instructions in the last 100m
• Reverse geocode to receive nearby addresses with delivery data.

So let’s get started, or skip to 60-second summary

Your free Naurt account

Before you start making requests, you’ll need to sign up for a free Naurt account on the Naurt dashboard. All we require is a verified email and you’ll be good to go.

On the homepage, your API key starting with nk_, will be found pre-loaded with 10,000 requests per calendar month so you can start using Naurt right away.

Final Destination endpoint

Naurt’s final destination data can be accessed through the following endpoint.

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

Authorization & Content-Type

Every request made to Naurt will need to contain a valid API key. Within a header of the request make sure to include,

Authorization: <API-KEY-HERE>

Naurt also requires every request to have a valid JSON body. In another header include,

Content-Type: application/json

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.

Request

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

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

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)

Response

A successful response is shown below with some content removed for brevity.

{
  "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": ["<geojson-features>"] }
      },
      "status": "ok"
    }
  ],
  "version": "v2.1.2"
}

Reverse Geocoding

Often you’ll find you need to look up data based on a location rather than a written address. This is reverse geocoding which is also supported by the final destination API.

Request

Again, a POST request should be sent to the final-destination endpoint with the following JSON body,

{
  "queries": [
    {
      "location":{
        "latitude": 50.835551,
        "longitude": -0.127613
      }
    }
  ]
}

curl

curl -X POST \
-H 'Content-type: application/json' \
-H 'Authorization: <API-KEY-HERE>' \
-d '{"queries":[{"location":{"latitude":50.835551,"longitude":-0.127613}}]}' \
'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":[{"location":{"latitude":50.835551,"longitude":-0.127613}}]}

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

print(response.text)

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": ["<geojson-features>"] }
      },
      "status": "ok"
    }
  ],
  "version": "v2.1.2"
}

Summary

1. Sign up on the Naurt Dashboard for your free API key. It will look like,

   nk_d774fa39-2570-4975-9126-___________-5954-4bad-beda-31a99c51d53b

2. Configure a POST request to the final-destination endpoint with the following headers,

   https://api.naurt.net/final-destination/v2
   Authorization: <API-KEY-HERE>
   Content-Type: application/json

3. Configure your JSON payload for geocoding or reverse geocoding.

   {
     "queries": [
       {
         "address_string": "The Martha Gunn, 100 Upper Lewes Road BN2 3FE",
         "country": "UK"
       }
     ]
   }

     {
       "queries": [
         {
           "location":{
             "latitude": 50.835551,
             "longitude": -0.127613
           }
         }
       ]
     }

4. Send your request and investigate the final destination data Naurt provides.