Search for content

Locations by Address

Allows finding locations (i.e. localities, postal codes, streets or houses) matching an address given as separate input fields.

There is a corresponding suggestion endpoint Suggestions by Address which provides suggestions for the 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, a region or a province.
postal codeA postal code (or zip-code) that is used by a country's postal authority.
localityLocality of an address which may be a city, a district or a sub-district.
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 and setting country filters.

Country filters reduce the search space of geocoding, and can improve performance. Country codes should be ISO 3166-1 alpha-2 and separated by comma. In countries such as US, RU, AU, CA, and IN results can also be filtered by country subdivision specified as ISO 3166-2. In case the requested subdivision is not available, the results are filtered by the country and a warning is attached to the response.

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 a matching score and location type.

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.

  • country name
  • state
  • province
  • postal code
  • city
  • district
  • subdistrict
  • street
  • house number
"address": {
    "countryName": "Nederland",
    "state": "Zuid-Holland",
    "province": "",
    "postalCode": "2612 XZ",
    "city": "Delft",
    "district": "",
    "subdistrict": "",
    "street": "Aan 't Verlaat",
    "houseNumber": "33F"
},
"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 location 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"

 

Score:

The total score value ranges from 100 (a perfect match) down to 0 and helps to determine if a geocoding result is precise enough to use it in further processing steps. The total score is also used to sort the result list.

"quality": {
    "totalScore": 100
}

Some examples for total scores with explanations are given in the table below.

Input/ResultTotal ScoreExplanation
 Postal codeLocalityStreet  

Input:

Result:

76227

76227

Karlsruhe

Karlsruhe

 100Perfect match.

Input:

Result:

 

76227

Karlsruhe

Karlsruhe

Karl-Jäck-Weg

Karl-Jäck-Weg

100Perfect match. The postal code is added to the result to complete the data record.

Input:

Result:

76227

76227

Karlsruhe

Karlsruhe

Karl Weg

Karl-Jäck-Weg

93The total score is less than 100 because some street words are missing in the input.

Input:

Result:

76227

76227

Karlsruhe

Karlsruhe

Karl-Friedrich-Jäck-Weg

Karl-Jäck-Weg

87The total score is less than 100 because a word from the input is not in the result.

Input:

Result:

76227

76227

Kaslruhe

Karlsruhe

 88Kaslruhe is only a fuzzy match.

Input:

Result:

76227

76227

Karlsru

Karlsruhe

 93Karlsru is only a prefix match.

Input:

Result:

76227

76227

Karlsr uhe

Karlsruhe

 100Words were successfully merged.

 

To allow for improvements, the actual score values may be subject to change.

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