Places by Position (OSM)

Find places near a given position.

Input

The places by position endpoint considers the following input fields:

Input Field	Description
latitude and longitude	Latitude and longitude values of the requested position (WGS84), given as path parameters.
detailLevel	Required detail level of the resulting addresses, given as query parameter.

This endpoint also supports requesting a different language by providing one or more language codes.

Output

If the request succeeds, the response is a list with only one record. The record contains name and address of the location or place which is closest to the given position. The list is empty if no matching record is found.

Geographical Position:

Each returned record has a reference position which is the actual geographic position of the place or address.

"referencePosition": {
   "latitude": 52.0206272,
   "longitude": 4.3637008
}

Bounding Box:

The bounding box encloses the area where the found place is located.

"boundingBox": {
   "left": 4.3636508,
   "bottom": 52.0205772,
   "right": 4.3637508,
   "top": 52.0206772
 }

Formatted Address:

"formattedAddress": "33F, Aan 't Verlaat, Bomenwijk, Vrijenban, Delft, Zuid-Holland, Nederland, 2612 XW, Nederland"

The formatted address is a single string containing the name and all address elements of a place. It is suitable to display the record, e.g. in a list.

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

Category and type:

"category": "place",
"type": "house"

Each returned record is described by a category and a type giving a hint about which kind of a place it is. Category and type refer to the OSM map features.

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. In that case, 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"
            }
        }
    ]
}