What Kind of Search Should I Use?

Explanation

In this section, we’ll discuss the different ways in which you can search the API, and which one best suits the use case.

When geocoding, there’s several different options of ways you could perform the search. Depending on your use case, needs, and data available, some methods are preferable to others. Here’s a table which quickly shows the different modes.

Search by Naurt ID

The fastest and most accurate method of calling our service is to use a Naurt ID. This can easily be achieved in the query structure with

{
  "id": Uuid
}

Remember, a search query that contains an id field can not contain any other fields at all.

But how to obtain Naurt IDs? Every response contains a Naurt ID, an example query response might be (with geojson condensed for readability)

{
  "address": "Flat 10, Milner House, 5 Rookery Lane, Barnet, EN4 0FB, United Kingdom",
  "geojson": {},
  "id": "4dfa1121-e6aa-35f3-8da7-7bc50c1cc4ee"
  }

The id in this query response is the Naurt ID.

While you aren’t allowed to cache either the address or geographic information from Naurt, you are allowed to cache Naurt IDs.

Search by Source ID

If you don’t have access to the Naurt ID, the next best option is to search by a source ID. The main limitation of this search mode is source ID coverage is not global - we currently only support

Ordnance Survey UPRN
Royal Mail UDPRN

Which are both UK based sources. You can only search by one at a time, and the query body looks like this

UPRN
UDPRN

{
  "source_id": {
    "os_uprn": "200001191298"
  }
}

{
  "source_id": {
    "os_udprn": "17594066"
  }
}

This use case works best if you already have UPRNs or UDPRNs integrated into your system - if this is the case, this is by far the best search method.

Forward Geocode with Location

If you know approximately where the address is, you can limit the search into that area. For example, if you have users on a map and you offer a “search in this area” feature, this is a useful way to exclude results from outside the current map view area.

This is a great way to search as the limiting area makes the search very fast, and also very accurate. However, do keep in mind that if the result you are looking for are outside of the specified area, they can’t be found. This is a hard filter.

Forward Geocode

The simple forward geocode is the most basic and common way to use the API. If all you have is an address, this will be the only way to call the API. A forward geocode is the slowest and least accurate way to call the API, but that doesn’t mean it can’t be more than suitable for any use case. There’s information here on how you can ensure great search.

Reverse Geocode

The reverse geocode is fundamentally different to the forward geocode in use case. While it is much faster than a forward geocode, it is not good for finding specific addresses. This is because you don’t know in advance where the address is going to be! It’s totally possible another address will be closer to the search location than you expect.

That being said, the reverse geocode shines when you have users exploring a map. In fact, this is the exact search Naurt itself uses on the demo map in our dashboard. Try logging in and clicking on the map to see this search in action - the five closest addresses will pop up.

The query form is very simple for the reverse geocode, for example

{
  "queries":[
    {
    "location": {
      "latitude": 51.5018,
      "longitude": -0.1406
      }
    }
  ]
}