Introduction and Upgrade Guide

Welcome to the V2 documentation! This document will guide you through why we've made a V2 endpoint and how you can upgrade from V1 to V2.

The V1 endpoint will still be continued for some time, and currently there are no plans or end date. It is not considered deprecated yet, but it is considered legacy. There is currently no pressure to switch. If this time does come, Naurt will contact customers and add deprecation warnings to the V1 response.

Why add V2 Endpoint?

While expanding and growing the API and coverage, the design of the V1 endpoint started to limit development and future plans. The V2 endpoint also significantly cleans up and standardises the API. These changes include

  • No separation between single and bulk requests
  • A more consistent interface in all circumstances
  • Dedicated sections for options and logging
  • A more extensible API for future features

The Main Differences Summarised

  • Single and bulk API are no longer separate; all requests use the same interface and endpoint
  • The request has two objects - queries and options
  • queries is an array, whether a single or bulk request is made
  • latitude, longitude and distance_filter are no longer "loose" in the request but nested into a location object
  • The response format is always the same - best_match and additional_matches are always present, even if no additional matches are requested or if there is no match
  • A new enum status has been introduced to indicate a successful search or no matches found

Upgrade Instructions

There is now no separation between single and bulk APIs - the endpoint is

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

The request will now look like so

{
    "queries": [
        // See object format below
    ]
}

The queries list can take up to 200 objects. The object format is as follows

JSON
{
    "address_string": Option<String>,
    "address_structured": Option<StructuredAddress>,
    "location": Option<Location>,
    "id": Option<Uuid>,
    "country": Option<Country>,
    "additional_matches": Option<bool>
}

The StructuredAddress object is the same as from the V1 endpoint. Further rules still exist: address_string and address_structured are mutually exclusive. id is mutually exclusive with all other options.

Location is of the format

JSON
{
    "latitude": Float,
    "longitude": Float,
    "distance_filter": Option<Float>
}

The limitations on latitude, longitude and distance_filter are unchanged.

The response is of the format

JSON
{
    "responses": [
        // See object format below
    ],
    "logging": Option<Logging>,
    "version": String,
    "request_id": String
}

The responses list contains the following objects

JSON
{
    "best_match": Option<PoiResponse>,
    "additional_matches": [PoiResponses],
    "status": Status,
}

The PoiResponse format is unchanged from V1.

Logging is as follows

JSON
{
    "info": Option<[String]>,
    "warnings": Option<[String]>,
    "errors": Options<[String]>
}

If no info, warnings or errors are present the whole logging object will not be present.

best_match and additional_matches will always be present. If no match is found then best_match will be null and additional_matches will be an empty list.

Status is an enum which currently has exactly two varieties

  • ok
  • no_matches

ok indicates a successful request. no_matches also indicates a successful request, but that no addresses were found matching search parameters. Notice how with no errors it is entirely possible to have no matches (try this yourself

Should there be an error or a poor request which prevents a further search, the API will instead respond with 5XX or 4XX, as appropriate and following the HTTP specification. In these instances, Naurt will reply with plain text (not a JSON), explaining the issue.

Table of Contents