NFleet Address REST API (beta)

NFleet Address API offers geocoding based on OpenStreetMap data, and is available at https://address.nfleet.fi. The API version 2.0 supports the following use cases: unstructured geocoding, structured geocoding, reverse geocoding, robust structured geocoding, and partial geocoding. Apart from the partial geocoding operation, the API also provides batch endpoints for these operations for efficient processing of multiple entries with a single request.

Overview

NFleet Address API provides different options for geocoding and reverse geocoding depending on the requirements.

Structured and unstructured queries differ primarily in their input data format: Unstructured queries are easiest to use as they only take arbitrary address text, but structured queries can offer more accurate results when an exact match is not found. Both queries can return multiple matches, or incomplete¹ or inexact fuzzy² matches if an exact match is not found, and the match confidence score value of each match will reflect this.

Robust queries differ from regular queries primarily in their handling of non-existing or inexact matches. Whereas regular queries return can return multiple equal exact matches or a set of inexact or fuzzy matches, the robust queries attempt to locate a single best matching address as spatially close to the requested address as possible. For example, if a given street is not found from the given municipality, the robust query result does not include an incomplete match to the street in a different municipality, only a match to the input municipality name without the street, and with a low confidence score to reflect this. Similarly, if multiple exactly matching streets are found, only one is included in the result, but with a low confidence despite being an exact match. For usability, robust query results also contain an address resolution type describing the reason for the received confidence score.

Geocoding operations translate an input address into coordinates and reverse geocoding operations translate coordinates into their nearest address. In both cases, the results contain the full matching addresses and the coordinates of the addresses. The reverse geocoding does not return a match confidence score and the type of the resulting address depends on the distance between the coordinates of the match and the input coordinates of the reverse query: a house address is returned when located near the requested coordinates, a street address if no houses are found, and a municipality subdivision or a municipality if no street is found near the requested coordinates.

Batch operations allow sending multiple queries in one POST request in the request body and require a separate request to get the results, but otherwise work identically from their GET request counterparts.

The map data covers the countries listed in section Map coverage. Attempts to geocode addresses outside the covered countries result in addresses most closely matching in the covevered countries, if any. Reverse geocoding outside the covered area always results in an empty result.

When using curl or a custom client for making requests, note that batch operations respond with HTTP 303 See Other with a subsequent Location header to continue the query with, in order to facilitate long-running requests. The clients may use follow redirects option to handle this automatically. For example, in curl this is set with flag -L.

The use of NFleet Address API requires a subscription. Refer to Authorization section of this documentation to view example on how to include the access token with the request.

Available operations

NFleet Address can be used to geocode addresses into coordinates or reverse geocode coordinates into addresses. For the single entry operations, the result is received as a direct response to the query, and with batch queries, each consists of two operations: creating the query, and requesting the results of the query. The list of available operations is given in the table below.

Operation	Description
Unstructured geocoding query	Geocode an arbitrary address text into one or more matching address entries and coordinates.
Structured geocoding query	Geocode structured address elements into one or more matching address entries and coordinates.
Robust structured geocoding query	Geocode structured address elements into one most closely matching address entry and coordinates.
Reverse geocoding query	Reverse geocode coordinates into nearest address entry.
Partial geocoding query	Geocode a start of an arbitrary address text into a prediction of one or more matching address entries.
Unstructured batch geocoding query	Request the geocoding of a batch of arbitrary address texts into coordinates.
Get unstructured batch geocoding results	Get the results of a unstructured batch geocoding.
Structured batch geocoding query	Request the geocoding of a batch of structured address elements into coordinates.
Get structured batch geocoding results	Get the results of a structured batch geocoding.
Robust structured batch geocoding query	Request the robust structured geocoding of a batch of structured address elements into coordinates.
Get robust structured batch geocoding results	Get the results of a robust structured batch geocoding.
Reverse batch geocoding query	Request the reverse geocoding of coordinates into nearest address entry.
Get reverse batch geocoding results	Get the results of a reverse batch geocoding.

Unstructured geocoding query

The unstructured geocoding query geocodes an arbitrary address text into one or more matching address entries with coordinates and a match confidence score.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/geocode/unstructured`	HTTP/1.1

Query parameters

Parameter	Description
`address`	Required. The address text query. Maximum length: 128.
`api-version`	Required. The version of the API to use. Use value `2.0`.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Example request

https://address.nfleet.fi/geocode/unstructured?address=Straßburger Straße 42, 10405 Berlin&api-version=2.0

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.

Response codes

HTTP 200 OK. Indicates that the request completed successfully.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "query": {
    "address": "Straßburger Straße 42, 10405 Berlin"
  },
  "results": [
    {
      "address": {
        "country": "Germany",
        "countryCode": "DE",
        "region": "Berlin",
        "municipality": "Berlin",
        "subdivision": "Prenzlauer Berg",
        "postalCode": "10405",
        "street": "Straßburger Straße",
        "house": "42",
        "fullAddress": "Straßburger Straße 42, 10405 Prenzlauer Berg, Berlin"
      },
      "position": {
        "latitude": 52.53096,
        "longitude": 13.41459
      },
      "confidence": 100,
      "type": "House"
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`query`	Unstructured Query	The original query used to produce this result.
`results`	List of Geocoding Results	A list of results for this query.

Unstructured Query describes the original query used to produce this result. The elements of Unstructured Query are as follows.

Field	Type	Description
`address`	string	Unstructured address string to geocode.

Geocoding Result describes a single result for the query. See Geocoding Result.

Structured geocoding query

The structured geocoding query geocodes a structured address into one or more matching address entries with coordinates and a match confidence score.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/geocode/structured`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`country`	Optional. The country part of the address query. Maximum length: 64.
`region`	Optional. The region part of the address query. Maximum length: 64.
`municipality`	Optional. The municipality part of the address query. Maximum length: 64.
`subdivision`	Optional. The municipality subdivision part of the address query. Maximum length: 64.
`postalCode`	Optional. The postal code part of the address query. Maximum length: 32.
`street`	Optional. The street name part of the address query. Maximum length: 64.
`house`	Optional. The house number or name part of the address query. Maximum length: 32.
`place`	Optional. The place name part of the address query. Maximum length: 64.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Note that at least one element parameter of country, region, municipality, subdivision, postalCode, street, house or place is required as input.

Example request

https://address.nfleet.fi/geocode/structured?street=Straßburger Straße&house=42&postalCode=10405&municipality=Berlin&api-version=2.0

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.

Response codes

HTTP 200 OK. Indicates that the request completed successfully.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "query": {
    "municipality": "Berlin",
    "postalCode": "10405",
    "street": "Straßburger Straße",
    "house": "42"
  },
  "results": [
    {
      "address": {
        "country": "Germany",
        "countryCode": "DE",
        "region": "Berlin",
        "municipality": "Berlin",
        "subdivision": "Prenzlauer Berg",
        "postalCode": "10405",
        "street": "Straßburger Straße",
        "house": "42",
        "fullAddress": "Straßburger Straße 42, 10405 Prenzlauer Berg, Berlin"
      },
      "position": {
        "latitude": 52.53096,
        "longitude": 13.41459
      },
      "confidence": 100,
      "type": "House"
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`query`	Structured Query	The original query used to produce this result.
`results`	List of Geocoding Results	A list of results for this query.

Structured Query describes the original query used to produce this result. The elements of Structured Query are as follows.

Field	Type	Description
`country`	string	The country part of the original address query.
`region`	string	The region part of the original address query.
`municipality`	string	The municipality part of the original address query.
`subdivision`	string	The municipality subdivision part of the original address query.
`postalCode`	string	The postal code part of the original address query.
`street`	string	The street name part of the original address query.
`house`	string	The house number or name part of the original address query.
`place`	string	The place name part of the original address query.

A Geocoding Result describes a single result for the query. See Geocoding Result.

Robust structured geocoding query

The robust structured geocoding query attempts to locate a single best matching address as spatially close to the requested address as possible. The robust query always returns a result.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/geocode/structured/robust`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`country`	Required. The country part of the address query. Must be a valid country name or a contry code.
`municipality`	Optional. The municipality part of the address query. Maximum length: 64.
`postalCode`	Optional. The postal code part of the address query. Maximum length: 32.
`street`	Optional. The street name part of the address query. Maximum length: 64.
`house`	Optional. The house number or name part of the address query. Maximum length: 32.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.

Example request

https://address.nfleet.fi/geocode/structured/robust?street=Straßburger Straße&house=42&postalCode=10405&municipality=Berlin&country=de&api-version=2.0

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.

Response codes

HTTP 200 OK. Indicates that the request completed successfully.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "query": {
    "country": "de",
    "municipality": "Berlin",
    "postalCode": "10405",
    "street": "Straßburger Straße",
    "house": "42"
  },
  "result": {
    "address": {
      "country": "Germany",
      "countryCode": "DE",
      "region": "Berlin",
      "municipality": "Berlin",
      "subdivision": "Prenzlauer Berg",
      "postalCode": "10405",
      "street": "Straßburger Straße",
      "house": "42",
      "fullAddress": "Straßburger Straße 42, 10405 Prenzlauer Berg, Berlin"
    },
    "position": {
      "latitude": 52.53096,
      "longitude": 13.41459
    },
    "confidence": 100,
    "type": "House"
  },
  "resolution": {
    "municipality": "Exact",
    "postalCode": "Exact",
    "street": "Exact",
    "house": "Exact"
  }
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`query`	Robust Structured Query	The original query used to produce this result.
`result`	Geocoding Result	The single geocoding result for this query.
`resolution`	Address Resolution	Address resolution describing the reason for the received confidence score.

Robust Structured Query describes the original query used to produce this result. The elements of Structured Query are as follows.

Field	Type	Description
`country`	string	The country part of the original address query.
`municipality`	string	The municipality part of the original address query.
`postalCode`	string	The postal code part of the original address query.
`street`	string	The street name part of the original address query.
`house`	string	The house number or name part of the original address query.

A Geocoding Result describes a single result for the query. See Geocoding Result.

Address Resolution describes the reason for the received confidence score. The elements of Address Resolution are as follows.

Field	Type	Description
`municipality`	Address Resolution Type	The address resolution type of the municipality part of the result.
`postalCode`	Address Resolution Type	The address resolution type of the postal code part of the result.
`street`	Address Resolution Type	The address resolution type of the street part of the result.
`house`	Address Resolution Type	The address resolution type of the house part of the result.

Address Resolution Type describes the type of the match of the element in question. The possibe values are the following:

None: The element in question was not part of the input query and was not considered in the address resolution.
NotFound: No element of the given type was not found matching the name in the query.
Ambiguous: Multiple equal matches of the element were found and they could not be differentiated in the query result.
Inexact: A match was found with the name given in the query, but the match was only an inexact fuzzy match.
Exact: An exact element match was found to the name in the query.

Reverse geocoding query

The reverse geocoding query geocodes coordinates into their nearest address, or returns an empty results list if none found. Reverse geocoding results do not contain a match score.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/geocode/reverse`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`latitude`	Required. The latitude value of the reverse address query in WGS 84 coordinate system coordinates.
`longitude`	Required. The longitude value of the reverse address query in WGS 84 coordinate system coordinates.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.

Example request

https://address.nfleet.fi/geocode/reverse?latitude=52.48572&longitude=13.35582&api-version=2.0

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.

Response codes

HTTP 200 OK. Indicates that the request completed successfully.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "query": {
    "latitude": 52.48572,
    "longitude": 13.35582
  },
  "results": [
    {
      "address": {
        "country": "Germany",
        "countryCode": "DE",
        "region": "Berlin",
        "municipality": "Berlin",
        "postalCode": "10827",
        "street": "Hauptstraße",
        "house": "141-144",
        "fullAddress": "Hauptstraße 141-144, 10827 Berlin"
      },
      "position": {
        "latitude": 52.48564,
        "longitude": 13.35581
      },
      "type": "House"
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`query`	Reverse Query	The original query used to produce this result.
`results`	List of Geocoding Results	A list of results for this query.

Reverse Query describes the original query used to produce this result. The elements of Reverse Query are as follows.

Field	Type	Description
`latitude`	number	The latitude value of the original reverse address query in WGS 84 coordinate system coordinates.
`longitude`	number	The longitude value of the original reverse address query in WGS 84 coordinate system coordinates.

A Geocoding Result describes a single result for the query. See Geocoding Result.

Partial geocoding query

The partial geocoding query geocodes a start of an arbitrary address text into a prediction of one or more matching address entries. Partial query results do not contain a match score.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/geocode/partial`	HTTP/1.1

Query parameters

Parameter	Description
`address`	Required. The address text query. Maximum length: 128.
`api-version`	Required. The version of the API to use. Use value `2.0`.
`latitude`	Optional. Latitude hint for biasing the resulting suggestions by a location.
`longitude`	Optional. Longitude hint for biasing the resulting suggestions by a location.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 5.

Example request

https://address.nfleet.fi/geocode/partial?address=Straßburger Straße Be&api-version=2.0

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.

Response codes

HTTP 200 OK. Indicates that the request completed successfully.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "query": {
    "address": "Straßburger Straße Be"
  },
  "results": [
    {
      "address": {
        "country": "Germany",
        "countryCode": "DE",
        "region": "Berlin",
        "municipality": "Berlin",
        "postalCode": "10119",
        "street": "Straßburger Straße",
        "fullAddress": "Straßburger Straße 10119 Berlin"
      },
      "position": {
        "latitude": 52.53267,
        "longitude": 13.41702
      },
      "type": "Street"
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`query`	Partial Query	The original query used to produce this result.
`results`	List of Geocoding Results	A list of results for this query.

Partial Query describes the original query used to produce this result. The elements of Partial Query are as follows.

Field	Type	Description
`address`	string	Partial address string to geocode.

Geocoding Result describes a single result for the query. See Geocoding Result.

Unstructured batch geocoding query

The unstructured batch geocoding query allows making multiple Unstructured geocoding queries with a single request.

Method	URI	HTTP version
`POST`	`https://address.nfleet.fi/geocode/batch/unstructured`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.
`Content-Type`	Required. The content type of the request. Use `application/json`.

Request body

Example request in application/json

{
  "requests": [
    {
      "address": "Straßburger Straße 34 Berlin"
    },
    {
      "address": "Avenue Montaigne 30 Paris"
    }
  ]
}

The elements of the request body are as follows.

Field	Type	Description
`requests`	List of Unstructured Query Requests	Required. A List of unstructured query requests.

The elements of the Unstructured Query Request are as follows.

Field	Type	Description
`address`	string	Required. The address text query. Maximum length: 128.

Response codes

HTTP 302 Found. Indicates that the request completed successfully and that the results can be found at URI in the Location header. See Get unstructured batch geocoding results.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response headers

Header	Description
`Location`	The location of the results of this batch query. See Get unstructured batch geocoding results.
`NF-Batch-Operation-Progress`	The progress value between 0.0 and 1.0 of this batch query.
`NF-Batch-Operation-Progress-Message`	The progress message of this batch query.

Get unstructured batch geocoding results

The get unstructured batch geocoding results returns the results of a unstructured batch geocoding query.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/batch/unstructured/<query-guid>`	HTTP/1.1

URI parameters

Parameter	Description
`query-guid`	The GUID of the batch query. The GUID is returned as part of the `Location` response header of the batch query.

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`

Response codes

HTTP 200 OK. Indicates that the request succeeded and that the response contains the geocoding query results.

HTTP 303 See Other. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location response header for a URI to make a subsequent GET request to.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "responses": [
    {
      "query": {
        "address": "Straßburger Straße 34 Berlin"
      },
      "results": [
        {
          "address": {
            "country": "Germany",
            "countryCode": "DE",
            "region": "Berlin",
            "municipality": "Berlin",
            "subdivision": "Prenzlauer Berg",
            "postalCode": "10405",
            "street": "Straßburger Straße",
            "house": "34",
            "fullAddress": "Straßburger Straße 34, 10405 Prenzlauer Berg, Berlin"
          },
          "position": {
            "latitude": 52.53246,
            "longitude": 13.41606
          },
          "confidence": 100,
          "type": "House"
        }
      ]
    },
    {
      "query": {
        "address": "Avenue Montaigne 30 Paris"
      },
      "results": [
        {
          "address": {
            "country": "France",
            "countryCode": "FR",
            "region": "Ile-de-France",
            "municipality": "Paris",
            "postalCode": "75008",
            "street": "Avenue Montaigne",
            "house": "30",
            "fullAddress": "30 Avenue Montaigne, 75008 Paris"
          },
          "position": {
            "latitude": 48.86669,
            "longitude": 2.30612
          },
          "confidence": 100,
          "type": "House"
        }
      ]
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`responses`	List of Unstructured Query Responses	The list of Unstructured Query Responses to the batch request.

See the unstructured geocoding query response.

Structured batch geocoding query

The structured batch geocoding query allows making multiple Structured geocoding queries with a single request.

Method	URI	HTTP version
`POST`	`https://address.nfleet.fi/geocode/batch/structured`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.
`Content-Type`	Required. The content type of the request. Use `application/json`.

Request body

Example request in application/json

{
  "requests": [
    {
      "street": "Avenue Montaigne",
      "house": "30",
      "municipality": "paris"
    },
    {
      "street": "Straßburger Straße",
      "house": "34",
      "municipality": "berlin"
    }
  ]
}

The elements of the request body are as follows.

Field	Type	Description
`requests`	List of Structured Query Requests	Required. A List of Structured query requests.

The elements of the Structured Query Request are as follows.

Field	Type	Description
`country`	string	Optional. The country part of the address query. Maximum length: 64.
`region`	string	Optional. The region part of the address query. Maximum length: 64.
`municipality`	string	Optional. The municipality part of the address query. Maximum length: 64.
`subdivision`	string	Optional. The municipality subdivision part of the address query. Maximum length: 64.
`postalCode`	string	Optional. The postal code part of the address query. Maximum length: 32.
`street`	string	Optional. The street name part of the address query. Maximum length: 64.
`house`	string	Optional. The house number or name part of the address query. Maximum length: 32.
`place`	string	Optional. The place name part of the address query. Maximum length: 64.

Note that at least one element of country, region, municipality, subdivision, postalCode, street, house or place is required as input.

Response codes

HTTP 302 Found. Indicates that the request completed successfully and that the results can be found at URI in the Location header. See Get structured batch geocoding results.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response headers

Header	Description
`Location`	The location of the results of this batch query. See Get structured batch geocoding results.
`NF-Batch-Operation-Progress`	The progress value between 0.0 and 1.0 of this batch query.
`NF-Batch-Operation-Progress-Message`	The progress message of this batch query.

Get structured batch geocoding results

The get structured batch geocoding results returns the results of a structured batch geocoding query.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/batch/structured/<query-guid>`	HTTP/1.1

URI parameters

Parameter	Description
`query-guid`	The GUID of the batch query. The GUID is returned as part of the `Location` response header of the batch query.

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`

Response codes

HTTP 200 OK. Indicates that the request succeeded and that the response contains the geocoding query results.

HTTP 303 See Other. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location response header for a URI to make a subsequent GET request to.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "responses": [
    {
      "query": {
        "municipality": "paris",
        "street": "Avenue Montaigne",
        "house": "30"
      },
      "results": [
        {
          "address": {
            "country": "France",
            "countryCode": "FR",
            "region": "Ile-de-France",
            "municipality": "Paris",
            "postalCode": "75008",
            "street": "Avenue Montaigne",
            "house": "30",
            "fullAddress": "30 Avenue Montaigne, 75008 Paris"
          },
          "position": {
            "latitude": 48.86669,
            "longitude": 2.30612
          },
          "confidence": 100,
          "type": "House"
        }
      ]
    },
    {
      "query": {
        "municipality": "berlin",
        "street": "Straßburger Straße",
        "house": "34"
      },
      "results": [
        {
          "address": {
            "country": "Germany",
            "countryCode": "DE",
            "region": "Berlin",
            "municipality": "Berlin",
            "subdivision": "Prenzlauer Berg",
            "postalCode": "10405",
            "street": "Straßburger Straße",
            "house": "34",
            "fullAddress": "Straßburger Straße 34, 10405 Prenzlauer Berg, Berlin"
          },
          "position": {
            "latitude": 52.53246,
            "longitude": 13.41606
          },
          "confidence": 100,
          "type": "House"
        }
      ]
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`responses`	List of Structured Query Responses	The list of Structured Query Responses to the batch request.

See the structured geocoding query response.

Robust structured batch geocoding query

The robust structured batch geocoding query allows making multiple Robust structured geocoding queries with a single request.

Method	URI	HTTP version
`POST`	`https://address.nfleet.fi/geocode/batch/structured/robust`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.
`Content-Type`	Required. The content type of the request. Use `application/json`.

Request body

Example request in application/json

{
  "requests": [
    {
      "country": "fr",
      "street": "Avenue Montaigne",
      "house": "30"
    },
    {
      "country": "de",
      "street": "Straßburger Straße",
      "house": "34"         
    }
  ]
}

The elements of the request body are as follows.

Field	Type	Description
`requests`	List of Robust Structured Query Requests	Required. A List of robust structured query requests.

The elements of the Robust Structured Query Request are as follows.

Field	Type	Description
`country`	string	Required. The country part of the address query. Must be a valid country name or a contry code.
`municipality`	string	Optional. The municipality part of the address query. Maximum length: 64.
`postalCode`	string	Optional. The postal code part of the address query. Maximum length: 32.
`street`	string	Optional. The street name part of the address query. Maximum length: 64.
`house`	string	Optional. The house number or name part of the address query. Maximum length: 32.

Response codes

HTTP 302 Found. Indicates that the request completed successfully and that the results can be found at URI in the Location header. See Get robust structured batch geocoding results.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response headers

Header	Description
`Location`	The location of the results of this batch query. See Get robust structured batch geocoding results.
`NF-Batch-Operation-Progress`	The progress value between 0.0 and 1.0 of this batch query.
`NF-Batch-Operation-Progress-Message`	The progress message of this batch query.

Get robust structured batch geocoding results

The get robust structured batch geocoding results returns the results of a robust structured batch geocoding query.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/batch/structured/robust/<query-guid>`	HTTP/1.1

URI parameters

Parameter	Description
`query-guid`	The GUID of the batch query. The GUID is returned as part of the `Location` response header of the batch query.

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`

Response codes

HTTP 200 OK. Indicates that the request succeeded and that the response contains the geocoding query results.

HTTP 303 See Other. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location response header for a URI to make a subsequent GET request to.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "responses": [
    {
      "query": {
        "country": "fr",
        "street": "Avenue Montaigne",
        "house": "30"
      },
      "result": {
        "address": {
          "country": "France",
          "countryCode": "FR",
          "region": "Pays de la Loire",
          "municipality": "Angers",
          "postalCode": "49100",
          "street": "Avenue Montaigne",
          "house": "30",
          "fullAddress": "30 Avenue Montaigne, 49100 Angers"
        },
        "position": {
          "latitude": 47.47028,
          "longitude": -0.53636
        },
        "confidence": 20,
        "type": "House"
      },
      "resolution": {
        "municipality": "None",
        "postalCode": "None",
        "street": "Ambiguous",
        "house": "Exact"
      }
    },
    {
      "query": {
        "country": "de",
        "street": "Straßburger Straße",
        "house": "34"
      },
      "result": {
        "address": {
          "country": "Germany",
          "countryCode": "DE",
          "region": "Lower Saxony",
          "municipality": "Vechta",
          "postalCode": "49377",
          "street": "Straßburger Straße",
          "house": "34",
          "fullAddress": "Straßburger Straße 34, 49377 Vechta"
        },
        "position": {
          "latitude": 52.7256,
          "longitude": 8.26053
        },
        "confidence": 20,
        "type": "House"
      },
      "resolution": {
        "municipality": "None",
        "postalCode": "None",
        "street": "Ambiguous",
        "house": "Exact"
      }
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`responses`	List of Robust Structured Query Responses	The list of robust structured query responses to the batch request.

See the robust structured geocoding query response.

Reverse batch geocoding query

The reverse batch geocoding query allows making multiple Reverse geocoding queries with a single request.

Method	URI	HTTP version
`POST`	`https://address.nfleet.fi/geocode/batch/reverse`	HTTP/1.1

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`.
`language`	Optional. The localization language of the result. Allowed values: `en`, `de`, `sv`, `fi`. Default: `en`.
`results`	Optional. The maximum number of matching results to return. Default: 10.

Request headers

Header	Description
`Authorization`	Required. A unique access token that identifies the user of the API. The header format is `Bearer <access_token>`. Refer to the Authorization section for steps for obtaining a token.
`Content-Type`	Required. The content type of the request. Use `application/json`.

Request body

Example request in application/json

{
  "requests": [
    {
      "latitude": 59.325703,
      "longitude": 18.071732
    },
    {
      "latitude": 59.909642,
      "longitude": 10.745342
    }
  ]
}

The elements of the request body are as follows.

Field	Type	Description
`requests`	List of Reverse Query Requests	Required. A List of reverse query requests.

The elements of the Reverse Query Request are as follows.

Field	Type	Description
`latitude`	number	Required. The latitude value of the reverse address query in WGS 84 coordinate system coordinates.
`longitude`	number	Required. The longitude value of the reverse address query in WGS 84 coordinate system coordinates.

Response codes

HTTP 302 Found. Indicates that the request completed successfully and that the results can be found at URI in the Location header. See Get reverse batch geocoding results.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response headers

Header	Description
`Location`	The location of the results of this batch query. See Get reverse batch geocoding results.
`NF-Batch-Operation-Progress`	The progress value between 0.0 and 1.0 of this batch query.
`NF-Batch-Operation-Progress-Message`	The progress message of this batch query.

Get reverse batch geocoding results

The get reverse batch geocoding results returns the results of a reverse batch geocoding query.

Method	URI	HTTP version
`GET`	`https://address.nfleet.fi/batch/reverse/<query-guid>`	HTTP/1.1

URI parameters

Parameter	Description
`query-guid`	The GUID of the batch query. The GUID is returned as part of the `Location` response header of the batch query.

Query parameters

Parameter	Description
`api-version`	Required. The version of the API to use. Use value `2.0`

Response codes

HTTP 200 OK. Indicates that the request succeeded and that the response contains the geocoding query results.

HTTP 303 See Other. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location response header for a URI to make a subsequent GET request to.

For other response codes, refer to the section HTTP response codes. For response errors, refer to the section Request error codes.

Response body

Example response in application/json

{
  "responses": [
    {
      "query": {
        "latitude": 59.325703,
        "longitude": 18.071732
      },
      "results": [
        {
          "address": {
            "country": "Sweden",
            "countryCode": "SE",
            "region": "Stockholm County",
            "municipality": "Stockholm",
            "postalCode": "111 30",
            "street": "Slottsbacken",
            "house": "2",
            "fullAddress": "Slottsbacken 2, 111 30 Stockholm"
          },
          "position": {
            "latitude": 59.32571,
            "longitude": 18.07161
          },
          "type": "House"
        }
      ]
    },
    {
      "query": {
        "latitude": 59.90964,
        "longitude": 10.745342
      },
      "results": [
        {
          "address": {
            "country": "Norway",
            "countryCode": "NO",
            "region": "Oslo",
            "municipality": "Oslo",
            "postalCode": "0152",
            "street": "Dronningens gate",
            "house": "13",
            "fullAddress": "Dronningens gate 13, 0152 Oslo"
          },
          "position": {
            "latitude": 59.90948,
            "longitude": 10.74528
          },
          "type": "House"
        }
      ]
    }
  ]
}

The elements of the response body in application/json format are as follows.

Field	Type	Description
`responses`	List of Reverse Query Responses	The list of reverse query responses to the batch request.

See the reverse geocoding query response.

Common object types

The following object types are shared between different operations.

Geocoding Result

The elements of Geocoding Result are as follows.

Field	Type	Description
`address`	Address	The address of the result of the query.
`position`	Position	The coordinate position of the result for this query.
`confidence`	number	The confidence of the accuracy of the resulting address and coordinates. Value ranges from 100 to 0, with value 100 indicating an exact match found.
`type`	Result Type	The type of the address result. See Result Type

Address

Address describes the address of a geocoding result. The elements of Address are as follows.

Field	Type	Description
`country`	string	The country of the address result.
`countryCode`	string	The ISO 3166-1 alpha-2 country code of the address result.
`region`	string	The region of the address result.
`municipality`	string	The municipality of the address result.
`subdivision`	string	The municipality subdivision of the address result.
`postalCode`	string	The postal code of the address result.
`street`	string	The street name of the address result.
`house`	string	The house of the address result.
`place`	string	The local place name of the address result.
`fullAddress`	string	The full address string of the result.

Position

Position describes the coordinate position of a geocoding result. The elements of Position are as follows.

Field	Type	Description
`latitude`	number	Latitude value of the coordinate in WGS 84 coordinate system coordinates.
`longitude`	number	Longitude value of the coordinate in WGS 84 coordinate system coordinates.

Request error codes

If the request reasults in a 400 Bad Request, the following error codes in the response describe the error in more detail.

Geocoding query request errors

Code	Description
10001	Address data is missing.
10002	Coordinate data is missing.
10003	Geocoding query data is missing
10004	Coordinate latitude value is invalid.
10005	Coordinate longitude value is invalid.
10006	Country data is missing.
20001	Country data length exceeded.
20002	Region data length exceeded.
20003	Municipality data length exceeded.
20004	Subdivision data length exceeded.
20005	PostalCode data length exceeded.
20006	Street data length exceeded.
20007	House data length exceeded.
20008	Place data length exceeded.
20009	Address data length exceeded.
20050	Country not supported.

Generic request errors

Code	Description
30001	Api version not supported.
30002	Language not supported.

Example error response in application/json

{
  "errorCode": 10003,
  "errorMessage": "Query data missing."
}

Result Type

The result type describes the type of the found address result. The possibe values are the following:

House: A house address, typically at the location of the building with the given address, or if multiple buildings share the same address, a position near these buildings. The position can be different from the postal delivery location to the given address as these may not coincide with the building or its entrance. Positioning with respect to address identifiers beyond house number is country-specific. In some cases, the house addresses are differentiated by additional letters, if present.
Street: A street, typically near the center of a part of the street that matches the query. These locations do not correspond to a specific postal delivery address.
Place: A place with no clear boundary or administrative role, for example a suburb or a village when these names are not a part of the house addresses in the area.
PostalCode: A postal code area with a distinct postal code. The position is usually at the approximate center of the area.
Subdivision: A subdivision of a municipality in places where the subdivision is relevant to the addresses in the area, for example a post office spanning multiple postal codes, or a distinct village or a town used to differentiate adresses within a municipality.
Municipality: A municipality, usually the primary postal address city or a town name identifier in addresses. In some countries a municipality consists of multiple such cities and towns, necessatating the use of subdivision names.
Region: A region that subdivides a country, usually consists of multiple municipalities. Notable exceptions include capital regions in some countries where the region coincides with the capital municipality.
Country: A country for which there exists an ISO country code.

An incomplete match is one where a subset of the input is matched, but not all elements can be found, for example a street, house number and municipality name combination, where the given house number does not exist at the street in the given municipality. ↩
An inexact fuzzy match is one where an input element is matched closely by a element name, but with some deviation, such as missing or changed characters due to a typo. ↩