Search for content

Places by Address (OSM) - [EXPERIMENTAL]

This functionality is in an experimental state. Interface and behavior may change at any time.

Find places matching an address given as separate input fields.

 

Input

To match addresses to geographic positions with high quality, it is important to understand how the input fields of the Geocoding API are interpreted.

Input FieldDescription
countryCountries can be identified by name, ISO code or country code plate.
stateA subdivision of a country, for example a state or a region.
provinceThe province where an address is located.
postal codeA postal code (or zip-code) that is used by a country's postal authority.
localityThe name of the city or district where an address is located.
streetThe name of the road where an address is located.
house numberThe number of the house where an address is located.

 

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. 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"
}