Search for content

Places by Text (OSM)

Find places matching a name or address given by a single text field.

Input

All input data of an address (e.g. postal code, city or street) or a place (name of the place) can be combined into one single field. This is especially useful for interactive searches.

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 of records. Each record contains name and address of a location or place as well as its geographical position. The list is limited to a maximum of 10 records. 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 languages 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": "5ac06ecdbdb45321e4644b970a505fe8",
    "causes": [
        {
            "description": "A parameter is set to an invalid value.",
            "errorCode": "GENERAL_INVALID_VALUE",
            "parameter": "languages[1]",
            "details": {
                "value": ""
            }
        }
    ]
}