Configuration

There are some optional configurations you can use to customise the response.

All configuration options can be specified under an options object in the request body, as discussed in the introduction

POST  https://api.naurt.net/final-destination/v2
Content-Type: application/json
Authorization: <API_KEY_HERE>
{
    "queries": List<RequestFormat>,
    "options": Option<Options>
}

Where the Options itself is

{
    "structured_response": Optional<Bool>
}

Structured Response

Structured response will return the address in a parsed format as well as the concatenated string. To make a request with this option, set structured_response in the options object to true. For example, the request could be

{
    "queries": [
        {
        "address_string": "99 Rue de Clignancourt, 75018 Paris"
        }
    ],
    "options": {
        "structured_response": true
    }
}

And the response would be (reply condensed for readability)

{
    "request_id": "a193694f-490f-4990-9f94-61e9e1160362",
    "responses": [
        {
        "additional_matches": [],
        "best_match": {
            "address": "99 Rue de Clignancourt, 75018 Paris 18e Arrondissement, France",
            "geojson": {},
            "id": "3eaab5ff-14c6-36c8-a61f-535598ee00e5",
            "structured_response": {
            "city": "Paris 18e Arrondissement",
            "country": "France",
            "postalcode": "75018",
            "street_name": "Rue de Clignancourt",
            "street_number": "99"
            }
        },
        "status": "ok"
        }
    ],
    "version": "v2.1.0"
}

We can see the format of the structured response actually mirrors the format of the structured request, which is

{
    "address_line": Option<String>,
    "unit": Option<String>,
    "house_name": Option<String>,
    "street_number": Option<String>,
    "street_name": Option<String>,
    "city": Option<String>,
    "county": Option<String>,
    "state": Option<String>,
    "country": Option<String>,
    "postalcode": Option<String>
}

GeoJson Type

There are two styles in which Naurt can display geographic information. Naurt will either use a GeoJson style (default) or a key-value style. You can read more about this feature here. These can be set with the geojson_type option. It has two values:

• geo_json (default)
• key_value

These can set like so

{
    "queries": [
        {
        "address_string": "99 Rue de Clignancourt, 75018 Paris"
        }
    ],
    "options": {
        "geojson_type": "key_value"
        }
}

Return original Request

It is possible to ask Naurt to return your original request back to you. You can do this with the return_original option in the options. For example

{
    "queries": [
        {
        "address_string": "Rua Joaquim Palhares, 585, Praca Da Bandeira - RJ, 20260-080, Brazil"
        }
    ],
    "options": {
        "return_original": true,
    }
}

will return (locations omitted for clarity)

{
    "request_id": "48045248-4313-4963-b2aa-8968cf8faa90",
    "responses": [
        {
        "additional_matches": [],
        "best_match": {
            "address": "Rua Joaquim Palhares, 585, apto. 202, Praca Da Bandeira - RJ, 20260-080, Brazil",
            "geojson": {},
            "id": "361426c9-632f-341d-96f6-de2d42b40b15"
        },
        "original_request": {
            "additional_matches": false,
            "address_string": "Rua Joaquim Palhares, 585, Praca Da Bandeira - RJ, 20260-080, Brazil"
        },
        "status": "ok"
        }
    ],
    "version": "v2.6.3"
}

Input Filtering

Naurt will filter inputs which it deems poor. For instance, searches like Australia, OX1 1ST or 5 Main Road don't have enough information to concretely identify a single address. These searches are rejected very in the processing step, to prevent accidental matching against address that do exist, but can not be certain to matched to this address. Recall that Naurt is a delivery destination geocoder and does not geocode to higher administrative levels like post code, street, city or country.

You are able to control how aggressive this matching is by using the input_filter in the options. There are currently three levels

• none: Does not input filter at all. All searches will attempt to match. If the searched address is not detailed enough, something irrelevant could be found
• loose (default): Some input filtering is applied
• strict: Aggressive input filtering is applied

loose is the default option, and will work for most use cases. If you find many requests get rejected with an E-003-014, then try none.

strict is a much more aggressive input filtering. This works for use cases where you do not have control over the address inputs. For example, a courier business which is provided delivery addresses by a third party e-commerce platform. It can be helpful to filter out any potentially poor addresses before handing them to drivers. Manually intervening before bad addresses get to drivers is usually much quicker than trying to re-route drivers when already dispatched, or risking a failed delivery.

Example:

{
    "queries": [
        {
        "address_string": "Rua Joaquim Palhares, 585, Praca Da Bandeira - RJ, 20260-080, Brazil"
        }
    ],
    "options": {
        "input_filter": "none",
    }
}