Search for content

Locations by Position

Allows finding locations (i.e. localities, postal codes, streets or houses) near a given position.

Input

The input parameters of the Locations by position endpoint are latitude and longitude (WGS84) of a geographical position, given as path parameters.

This endpoint also supports requesting a different language.

Output

If the request succeeds, the response is a list of records. The list is empty if no matching record is found. Each record contains the actual address and its geographical position, along with the location type and the distance to the requested position.

Geographical Positions:

Each returned record has one or two geographical positions:

  • reference position: the roof top position of the house, the center of the city or the postal code area.

  • road access position (optional): the position where you would start driving.

     

"referencePosition": {
    "latitude": 52.02085876464844,
    "longitude": 4.363800048828125
},
"roadAccessPosition": {
    "latitude": 52.020320892333984,
    "longitude": 4.364419937133789
},

 

Address Fields:

An address has the following fields. Depending on data availability and result type (e.g. city, address), some fields may be empty.

"address": {
    "countryName": "Nederland",
    "state": "Zuid-Holland",
    "province": "",
    "postalCode": "2612 XZ",
    "city": "Delft",
    "district": "",
    "subdistrict": "",
    "street": "Aan 't Verlaat",
    "houseNumber": "33F",
    "countryCodeIsoAlpha2": "NL",
    "countryCodeIsoAlpha3": "NLD",
    "countryCode": "NL"
},
"formattedAddress": "Aan 't Verlaat 33F, 2612 XZ Delft"

 

The returned address fields will be in the language spoken in that country or region, unless otherwise requested by the language parameter.

Location Type:

Each record has a location type, common record types are:

  • locality (e.g. Boston)
  • postal code (e.g. 10557 Berlin)
  • street section (e.g. Avenue des Champs-Élysées, 75008 Paris)
  • address (e.g. 10 Downing St, London SW1A 2AA) 
     
"locationType": "EXACT_ADDRESS"

 

Distance:

The value is given in meters from the requested position to either the reference position or the road access position (whichever is closer). The distance is also used to sort the result list.

"quality": {
    "distance": 1
}

 

Errors:

The search is limited by an internal timeout. If a request takes very long, it will be aborted. This may typically happen if the server is very busy. When that happens, an error response will be returned:

{
    "description": "The request could not be processed due to an internal error.",
    "errorCode": "GENERAL_INTERNAL_SERVER_ERROR",
    "traceId": "e0f3b45a721e4f2d8b3f0ca5ebfb2166",
    "errorId": "fdf1e24b-e180-4205-8a22-21e5d5336187"
}

 

If a parameter in the request has an unacceptable value, the error response will specify the erroneous parameter and its expected range.

{
    "description": "The validation of the request failed. Details can be found in the property 'causes'.",
    "errorCode": "GENERAL_VALIDATION_ERROR",
    "traceId": "332abf3834c94effa4ec86eb07c6da6f",
    "causes": [
        {
            "description": "The minimum value restriction is violated.",
            "errorCode": "GENERAL_MINIMUM_VALUE_VIOLATED",
            "parameter": "longitude",
            "details": {
                "minimumValue": "-180"
            }
        }
    ]
}