Geocoder API Developer's Guide

Additional Data Parameter

List of KeyValuePairType elements as generic container to attach additional information to requests.

Table 1. Key-value pairs for Additional Data
Key Value
CrossingStreets true/false, determines whether the response contains cross streets.
PreserveUnitDesignators

true/false, secondary address units as defined by the US Postal Service are recognized and returned if this switch is set to true. Recognized address units are returned in the Address.AdditionalData field, where the designator is the key and the unit value is the value of the entry.

Country2 true/false, determines whether ISO-3166 alpha-2 country codes are returned in the response address AddressType.additionalData[Country2] element. By default, two-letter codes are not returned.
IncludeChildPOIs true/false, determines whether child POIs are returned with their parent POI. Examples for POIs with a parent/child relationship are airports and their terminals or national parks and their entrances. By default, child POIs are not returned.
IncludeRoutingInformation true/false, determines whether additional information needed for precise routing instructions is returned with the request. The data is stored in additional data fields in returned Location elements. The keys for all of these entries are prefixed with the string routing, enabling filtering on client side.
AdditionalAddressProvider

List of Provider IDs (space separated) for address source that should be considered additionally in the search. Currently only provider ID 24 is supported. Provider 24 adds some addresses in Germany for which the map data does not have geometry yet. The addresses therefore only have a display coordinate.

If data from an additional address provider is returned, the corresponding Location element is flagged with an additionalData entry additionalAddressProvider identifying the provider.

HouseNumberMode

Defines how to geocode unknown house numbers. The following values are supported:

  • Extrapolation <MAX_HSN_DISTANCE> <MAX_DISTANCE>: Use extrapolation.

    Extrapolation is performed until a predefined maximum distance in house number and a maximum in meters. The system wide configured maximum values can be overwritten by passing values for MAX_HSN_DISTANCE and/or MAX_DISTANCE. If any of the maximum is exceeded the result falls back to the street level match.

  • Fallback <MAX_HSN_DISTANCE>: Use house number fallback. This is the default value.

    Fallback is performed until a predefined maximum distance in house number. This system-wide configured maximum value can be overwritten by passing a value for MAX_HSN_DISTANCE. If the maximum is exceeded, the result falls back to the street level match.

  • Streetlevel: Do not do extrapolation or fallback; instead return a streetlevel match (up-hierarchy).

FlexibleAdminValues

N (positive integer <= 1). Customizes flexibility in the input values for the admin hierarchy defined in LocationFilterType. The value is a bitmask defining which hierarchies might be swapped without impacting the match level:

  • 0: No swapping at all (default). Exact admin hierarchy values are expected as input.
  • 1: City and District swapping

Please note this option is for geocoding addresses and needs at least street level input to work as designed. It will not return expected results when the input is a named place only (e.g. city or district name).

IntersectionSnapTolerance N (float in [0, 1]). When reverse geocoding a coordinate, the value controls how strictly an address match is snapped to the next intersection. A value of 0 indicates that no points on a link are snapped to an intersection; a value of 1 indicates that most probably a street intersection is returned as a match. Default value is 0.
AddressRangeSqueezeOffset N (positive integer), offset in meters which moves the first and last locations of an address range on a link away from the center point of an intersection. If no value for the AddressRangeSqueezeOffset or the AddressRangeSqueezeFactor parameters is provided, a default constant offset is used.
AddressRangeSqueezeFactor N (float in [0, 1]). Similar to AddressRangeSqueezeOffset; the value is provided relatively to the link length as a percentage. 0.5 means 20% squeeze on both sides. 1 means range squeezed to point. 0 means no squeeze but also no default constant offset.
IncludeShapeLevel

Area level used to populate the shape information in the location results.

Supported levels are: country, state, county, city, district, postalCode, default. Only one level is supported per request. Level default returns the area shape corresponding to the match level.

RestrictLevel

Area level used to restrict address results. When reverse geocoding a coordinate, only address results within the enclosing admin area of the specified level are returned. The parameter can be used to restrict results to the country of the input coordinate. Only country is supported.

SuppressStreetType Controls if streets of a specific type should be suppressed in the result. Currently only the following type is supported:
  • Unnamed: Suppress streets where the map does not provide a name.
NormalizeNames

true/false, option to receive the same normalized admin and street names from forward and reverse geocoding results. By default, the preferred admin and street names for forward geocoding in the result are the names from the user input.

Normalized means name normalization for all Geocoder API components.

IncludeDistanceMarkers

true/false, option to integrate Distance Marker information in the results. The matched result will be of locationType distanceMarker and provide the offset to the reference Distance Marker. The reference Distance Marker as well as the next Distance Marker in the sequence (if available) are returned as related locations to the matched location.

The option is supported for the retrieveAddresses mode in the reversegeocode endpoint.

IncludeMicroPointAddresses
true/false, option to match and retrieve Micro Point Address information in the results. For recognized address units a micro point unit address is returned as related location. The following secondary units are supported when preceding a micro point unit address with a point address:
  • "Unit"
  • "Apartment" or "APT"
  • "Suite" or "STE"
  • "#"
  • "Building" or "BLDG"
  • "Office" or "OFC"
  • "Penthouse" or "PH"
  • "Room" or "RM"
  • "Space" or "SPC"

The option is supported for the geocode endpoint.