Skip to content
Naurt Docs

Geocoding

Tutorial

As discussed in the Quickstart, there are plenty of ways to access Naurt data. These examples will guide you through each way you can forward geocode with Naurt. Before continuing, make sure you have your free API key from the Naurt Dashboard.

Forward Geocode

Section titled “Forward Geocode”

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

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

  2. Configure your JSON payload with an address string.

    {
      "queries": [
        {
          "address_string": "32 Thames St, Windsor SL4 1PS"
        }
      ]
    }
     
{
  "queries": [
    {
      "address_string": "32 Thames St, Windsor SL4 1PS",
      "country": "UK"
    }
  ]
}

You can also request some additional matches (up to 5 total) by using the additional_matches field.

{
  "queries": [
    {
      "address_string": "32 Thames St, Windsor SL4 1PS",
      "country": "UK",
      "additional_matches": true


    }
  ]
}

Structured Forward Geocode

Section titled “Structured Forward Geocode”

A structured geocode allows you to search with already parsed and structured data. A structured geocode has a minimum set of fields required. At minimum you must include

  • street_name AND
  • postalcode AND
  • house_name OR street_number

i.e. three fields minimum.

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

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

  2. Configure your JSON payload with an address_structured.

    {
      "queries": [
        {
          "address_structured": {
            "postalcode": "10013",
            "street_name": "Broome Street",
            "street_number": "489",
            "city": "New York",
          }
        }
      ]
    }

Forward Geocode with Location

Section titled “Forward Geocode with Location”

If you know approximately where an address is, you can include a location to help narrow down the results. This can really improve speed and accuracy, but, if the provided location is very distant from the real location, you might not be able to find the right address.

A good use case for this is searching when the user is on a map, you could include the current view area, for example, for a “search in this area” feature.

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

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

  2. Configure your JSON payload with an address_string and location

    {
      "queries": [
        {
          "address_string": "32 Thames St, Windsor SL4 1PS",
          "location": {
            "latitude": 51.484,
            "longitude": -0.607
          }
        }
      ]
    }

You can also specify the distance filter yourself, for example, to make it larger. Note that in the above example, the default distance is 5000m. In the below request, we extend it to 10000m:

{
  "queries": [
    {
      "address_string": "32 Thames St, Windsor SL4 1PS",
      "location": {
        "latitude": 51.484,
        "longitude": -0.607,
        "distance_filter": 10000.0
      }
    }
  ]
}
{
  "queries": [
    {
      "address_string": "32 Thames St, Windsor SL4 1PS",
      "location": {
        "latitude": 51.484,
        "longitude": -0.607,
        "distance_filter": 10000.0
      },
      "additional_matches": true
    }
  ]
}

Structured Geocode with Location

Section titled “Structured Geocode with Location”

Analogous to a forward geocode with a location, we can also supply a location to a structured geocode which allows for narrowing of the search. While this is significantly faster and more accurate if the supplied location is accurate, if the address you are searching for is outside the specified location it can not be found!

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

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

  2. Configure your JSON payload with an address_structured and location.

    {
      "queries": [
        {
          "address_structured": {
            "postalcode": "10013",
            "street_name": "Broome Street",
            "street_number": "489",
            "city": "New York",
          },
          "additional_matches": true,
          "location": {
            "latitude": 40.72,
            "longitude": -74.0
          }
        }
      ]
    }