Geocoder API Developer's Guide

Search Response

The SearchResponse structure is the top level element returned by geocode, reverse geocode and landmark geocode requests. It contains Meta Information and one or more View elements. Each view consists of a list of Results wrapping the actual Location object found for the request together with information about the Match Quality of the result.

The Location is the central entity of a search result. It provides information about the geographical position as well as the Address of the location. Address Details, Address Names, and Street Details expose detailed information on the address elements. The identifiers stored in the Map Reference enable cross referencing into other services or data applications based on HERE Map Content. The most common map attributes for a navigable link are integrated directly in the Geocoder response and are exposed in the Link Info element whereas the Admin Info element exposes country or state meta information for the administrative area of a location like the Timezone. A Location can be related to other Locations. This relationship is modeled by the Related Location element.

Response (SearchResponseType)

Table 1. Response elements
Type	Description
MetaInfo	Meta Information about the Request
View	Search Results are grouped in Views.

MetaInfo (SearchResponseMetaInfoType)

Table 2. MetaInfo elements
Type	Description
RequestId	Mirrored RequestId value from the request structure. Can be used to trace requests.
Timestamp	Time at which the search was performed.
NextPageInformation	Key which can be used in subsequent requests to acquire the next n results. This element is only provided if paging has been activated in the request.
PreviousPageInformation	Key which can be used in subsequent requests to acquire the previous n results. This element is only provided if paging has been activated in the request.
AdditionalData	List of KeyValuePairType elements as generic container to attach additional information to the request.

View (SearchResultsViewType)

Table 3. View elements
Type	Description
ViewId	A key to distinguish between different types of views. Always set to 0.
PerformedSearch	Search path which was performed for this search run. In case of free-form searches, this element holds structured information, which indicates how user input has been interpreted by Search. The Performed Search has the same structure as a search request and can thus be used to repeat the same search.
Results	The resulting items which have been found along with attributes indicating the quality of the search result.

Result (SearchResultType)

The SearchResult contains the actual result as a Location object together with information on how good the result matches the search request.

Table 4. Result elements
Type	Description
Relevance	Indicates the relevance of the results found; the higher the score the more relevant the alternative. The score is a normalized value between 0 and 1.
Distance	Distance between the identified location object and the specified client position in meters. Only provided if a proximity was specified in the request (parameter `prox`). For areas like admin or landmark areas the distance is defined as the distance between the input coordinate and the boundary of the area. If the area covers the input coordinate the distance will be negative. Note: With gen<6 the distance for admin area results is calculated from the given point to the center of the area.
Direction	Direction of the location object seen from the specified client position measured clockwise in degrees starting with 0 at true north. Currently only provided for Reverse Geocode `mode=retrieveAreas` results. It is the direction from the specified client position to the center of the area.
MatchLevel	The most detailed address field that matches the geocoding or reverse geocoding query. Enumeration [`country`, `state`, `county`, `city`, `district`, `street`, `intersection`, `houseNumber`, `postalCode`, `landmark`]. `intersection` is only supported with `gen >= 1`; for `gen<1` requests `street` is returned for intersection matches.
MatchQuality	Detailed information about the match quality on the attribute level. MatchQuality is always 1.0 for reverse geocode results.
MatchType	Quality of the location match. `pointAddress` Location matches exactly as Point Address. `interpolated` Location was interpolated. With `gen<3` address results from reverse geocoding always have MatchType `interpolated`; only with `gen>=3` reverse geocoding returns Point Address results with MatchType `pointAddress`.
MatchCode	Code indicating how well the result matches the request. Enumeration [`exact`, `ambiguous`, `upHierarchy`, `ambiguousUpHierarchy`].
ParsedRequest	Structured representation of the request which led to the current search result.
Location	The location that was found.
AdditionalData	Generic key/value container to keep additional attributes. The defined key/values are: houseNumberFallback true/false. This attribute is included, if MatchLevel is houseNumber. It is set to false, if Search could find the requested house number. If set to true, it indicates that the requested house number was corrected to match the nearest known house number houseNumberFallbackDifference Difference between the requested house number and the matched house number. This attribute is only included if houseNumberFallback is set to true. houseNumberExtrapolation true/false. An extrapolated address is marked true. House number extrapolation can be activated with an additional data parameter HouseNumberMode, Extrapolation. houseNumberExtrapolationDistance For an extrapolated address, this attribute provides the distance in meters from an existing point or range address houseNumberExtrapolationDifference For an extrapolated address, this attribute provides the difference in house numbers from an existing point or range address.

MatchQuality (LocationMatchQualityType)

MatchQuality provides detailed information about the match quality of a result at attribute level. Match quality is a value between 0.0 and 1.0. 1.0 represents a 100% match.

Table 5. MatchQuality elements
Type	Description
Country	Match quality of the result with respect to country information in the request.
State	Match quality of the result with respect to state information in the request.
County	Match quality of the result with respect to county information in the request.
City	Match quality of the result with respect to city information in the request.
District	Match quality of the result with respect to district information in the request.
Subdistrict	Match quality of the result with respect to sub-district information in the request.
Street	Match quality of the result with respect to street information in the request. There are two values of 'Street' when you specify an intersection.
HouseNumber	Match quality of the result with respect to house number information in the request.
PostalCode	Match quality of the result with respect to postal code information in the request.
Building	Match quality of the result with respect to building information in the request.

ParsedRequest (ParsedRequestType)

ParsedRequest shows how the various components of the request were derived from search terms.

Table 6. ParsedRequest elements
Type	Description
Name	Input token(s) the parser has categorized as the name of a landmark.
Label	Assembled address value built out of the parsed address components.
Country	Input token(s) the parser has categorized as the country part of an address.
State	Input token(s) the parser has categorized as the state part of an address.
County	Input token(s) the parser has categorized as the county part of an address.
City	Input token(s) the parser has categorized as the city part of an address.
District	Input token(s) the parser has categorized as the district part of an address.
Subdistrict	Input token(s) the parser has categorized as the sub-district part of an address.
Street	Input token(s) the parser has categorized as the street part of an address (including intersections which are defined by two streets).
HouseNumber	Input token(s) the parser has categorized as the house number part of an address.
PostalCode	Input token(s) the parser has categorized as the postal code part of an address.
Building	Input token(s) the parser has categorized as the building part of an address.
AddressLine	Formatted address lines built out of the parsed address components. The first line consists of street name, including prefix, directional and street type, and house number. The second line consists of the city name and postal code, plus in some countries the state name or abbreviation. These elements are only populated if the `MatchLevel` is street or better. A city match does not contain address lines.
AdditionalData	Secondary address units as defined by the US Postal Service can be recognized and returned if the PreserveUnitDesignators switch was set to true in the SearchRequest additionalData field. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry: `APT` recognized value of unit type Apartment `BLDG` recognized value of unit type Building `FL` recognized value of unit type Floor `STE` recognized value of unit type Suite `UNIT` recognized value of unit type Unit `DEPT` recognized value of unit type Department `UnknownUnit` unrecognized address unit value, which is usually printed with a pound (#) sign

Location (LocationType)

The location type refers to a physical location including the physical extent. A location can be referenced either by Location ID or by specifying the address.

Table 7. Location elements
Type	Description
LocationId	A key uniquely identifying a physical location.
LocationType	Indicates the type of the location. The following types are supported: `area` `address` `trail` `park` `lake` `mountainPeak` `volcano` `river` `golfCourse` `industrialComplex` `island` `woodland` `cemetery` `canalWaterChannel` `bayHarbor` `airport` `hospital` `sportsComplex` `shoppingCentre` `universityCollege` `nativeAmericanReservation` `railroad` `militaryBase` `parkingLot` `parkingGarage` `animalPark` `beach` `distanceMarker` For `gen<5` the location type is set to `point`.
Name	The name of a location. This is relevant for landmarks like parks and lakes.
DisplayPosition	The display position contains the coordinates at which to place a marker indicating the given location on the map.
NavigationPosition	A navigation position contains the coordinates of a potential route waypoint. It is used for routes that pass through the given location.
MapView	Bounding box of the location optimized for display
Shape	Shape of the location. This is only relevant for areas.
Address	Address record of a Location. Attributes are normalized to US feature names and can be mapped to the local feature levels (for example, State matches "Bundesland" in Germany) using mapping tables.
AddressDetails	Additional information about the address. The names for address elements are listed together with the language information for this name.
AddressNames	Additional information about the address. Address information in all primary languages for bi-lingual regions. Currently limited to Spain. In Spain, some regions have multiple primary languages such as Spanish, Catalan, Basque, or Galician.
MapReference	References to a network link and admin areas of the location object.
LinkInfo	The most common map attributes of a navigable link. Only available for link based locations like streets and buildings.
Related	List of related locations. The following types of related locations are supported: nearByDistanceMarker Location of a nearby distance marker on the highway. Retrieving distance markers is supported for the Reverse Geocoding mode `retrieveAddresses` and is enabled by the flag `&additionaldata=IncludeDistanceMarkers,true` microPointAddress Location of a secondary address for a point address. Retrieving micro point unit addresses is supported for the Forward Geocoding mode and is enabled by the flag `&additionaldata=IncludeMicroPointAddresses,true`
AdditionalData	Generic key/value container to keep additional attributes. The defined key/values are: ExtendedTopLeftLatitude Latitude of the top-left coordinate of the extended bounding box which completely encloses the physical extent of the location. ExtendedTopLeftLongitude Latitude of the top-left coordinate of the extended bounding box ExtendedBottomRightLatitude Latitude of the bottom-left coordinate of the extended bounding box ExtendedBottomRightLongitude Longitude of the bottom-right coordinate of the extended bounding box "additionalAddressProvider" ProviderId if Location data is provided by an external address provider. The use of external address providers has to be activated through an additional data field "AdditionalAddressProvider" in the request.

Note: Depending on the search scenario, some sub elements might be omitted.

MapReference (MapReferenceType)

Reference to a Map Object

Table 8. MapReference elements
Type	Description
ReferenceId	PVID of the arrival link to represent the drive-to location.
MapVersion	Version of the map schema. Format: `QQ/YYYY`, e.g. `Q1/2015`
MapReleaseDate	Release date of the map data. Format: YYYY-MM-DD
MapId	Map version details (DVN) containing the base line for the map schema and an identifier for the weekly or quarterly update. Format: <4-letter region>`YYQ`<weekly update> Example: NAAM15135 (region: North America (NAAM), map schema: Q1/2015 (151), weekly update 35)
Spot	Relative position of the location along the link. Spot is defined as the fractional distance from the link's reference-node to the non-reference node, i.e. the value range is between 0 and 1. This attribute is only relevant if a link is referenced.
SideOfStreet	Indicates whether the referenced location is on the left or right side of the link (if heading from the reference node to the non-reference node). Enumeration [`left`, `right`, `neither`].
CountryId	PVID of the country admin area.
StateId	PVID of the state admin area.
CountyId	PVID of the county admin area.
CityId	PVID of the city admin area.
DistrictId	PVID of the district admin area.
RoadLinkId	PVID for the relationship between the road link and it's naming/point address information. Only available for results with matchLevel houseNumber and matchType pointAddress. Not available for interpolated results, except for Interpolated/Estimated Point Addresses. The Road Link is used to retrieve the Street Name, Administrative, Postal, and Zone coding for the Point Address.
BuildingId	External reference to additional building information (currently for internal use only)
AddressId	PVID of the Point Address. Only available for results with `matchLevel` `houseNumber` and `matchType` `pointAddress`. Not available for `interpolated` results, except for Interpolated/Estimated Point Addresses.

Address (AddressType)

Address record of a Location. Attributes are normalized to US feature names and can be mapped to the local feature levels (for example, State matches "Bundesland" in Germany) using mapping tables.

Table 9. Address elements
Element	Definition
Label	Assembled address value for displaying purposes.
Country	ISO 3166-alpha-3 country code
State	Includes the first subdivision level below the country. Where commonly used, this is a state code such as CA for California.
County	Includes the second subdivision level below the country. Use of this field is optional if a second subdivision level is not available.
City	Refers to the locality of the address.
District	Includes the subdivision level below the city. Use of this field is optional if a second subdivision level is not available.
Subdistrict	Includes the subdivision level below the district. This field is currently only used for India results. In India, it is typical to use the names of areas below district level in addressing.
Street	Refers to the street name.
HouseNumber	House number. Depending on regional characteristics, can also be house name.
PostalCode	Postal code
Building	Building name. Building names are currently only supported for Hong Kong addresses.
DistanceMarker	Distance marker information for this location. Only populated when explicitly requested with `additionaldata=IncludeDistanceMarkers,true`.
AddressLine	Formatted address lines. The first line consists of street name (including pre-fix, directional, street type) and house number. The second line consists of the city name and postal code plus in some countries the state name or abbreviation. These elements are only populated if `MatchLevel` is street or better.
AdditionalData	Generic key/value container to keep additional attributes. The defined key/values are: "CrossingStreet0" First cross street near matched address "CrossingStreet1" Second cross street near matched address. This value is omitted by the search module, if the location's distance to CrossingStreet0 is less than half of the distance to CrossingStreet1. "CountryName" Non-abbreviated, full name of the country. "StateName" Non-abbreviated, full name of the state. "CountyName" Non-abbreviated, full name of the county. "Country2" If requested by passing `&additionaldata=Country2,true`, this field provides the ISO-3166 alpha-2 country code. By default, two-letter codes are not returned. Secondary address units as defined by the US Postal Service can be recognized and returned if the PreserveUnitDesignators switch was set to true in SearchRequest.additionalData. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry: "APT" - recognized value of unit type "Apartment" "BLDG" - recognized value of unit type "Building" "FL" - recognized value of unit type "Floor" "STE" - recognized value of unit type "Suite" "UNIT" - recognized value of unit type "Unit" "RM" - recognized value of unit type "Room" "DEPT" - recognized value of unit type "Department" "UnknownUnit" - unrecognized address unit value, which is usually printed with a pound ("#") sign. "PostalCodeType" For the USA, the Geocoder result shows supplementary information that describes the type of the 5-Digit ZIP, as according to the USPS. The values are as follows: "N" = Non-Unique "M" = Military "P" = PO Box "U" = Unique Zip

Address Details (AddressDetailsType)

The address details type provides additional information about the address. The names for address elements are listed together with the language information for this name.

Table 10. Address Details elements
Element	Definition
CountryCode	ISO 3166-alpha-3 country code
Country	Country name together with the language information
State	State name together with the language information
County	County name together with the language information
City	City name together with the language information
District	District name together with the language information
Street	Street name together with the language information
StreetDetails	Street name decomposed into the different name parts
HouseNumber	House number together with the language information (if available)
PostalCode	Postal code
Building	Building name together with the language information

Address Names (AddressNamesType)

Additional information about the address. Address information in all primary languages for bi-lingual regions. Currently limited to Spain. In Spain, some regions have multiple primary languages such as Spanish, Catalan, Basque, or Galician.

Table 11. Address Names elements
Element	Definition
Country	List of key/value pairs with country name together with the language information
State	List of key/value pairs with state name together with the language information
County	List of key/value pairs with county name together with the language information
City	List of key/value pairs with city name together with the language information
District	List of key/value pairs with district name together with the language information
Subdistrict	List of key/value pairs with sub-district name together with the language information
Street	List of key/value pairs with street name together with the language information

Street Details (StreetDetailsType)

The Street Details type decomposes the street name into its name parts like the base name, the street type, etc.

Table 12. Street Details elements
Type	Description
BaseName	Base name part of the street name. The base name is a numbered route, local name, or commonly accepted name for a street.
StreetType	Street type part of the street name. Street type is the local municipality designator of each road, such as "street", "road", "strasse", "straat", "via", or "rue de la". Street types are defined as either "preceding" or "following" the base name and "attached" or "unattached" to the base name.
StreetTypeBefore	Defines if the street type is before or after the base name.
StreetTypeAttached	Defines if the street type is attached or unattached to the base name.
Prefix	A prefix is a directional identifier that precedes, but is not included in, the base name of a road.
Suffix	A suffix is a directional identifier that follows, but is not included in, the base name of a road.
Direction	Indicates the official directional identifiers assigned to highways, typically either "North/South" or "East/West"

Distance Marker (DistanceMarkerType)

Distance Markers are sequentially numbered markers placed along roads at regular intervals that serve as reference location signs.

Table 13. Distance Marker elements
Type	Description
Value	Distance Marker value
Offset	Distance in the local units along the highway from the lowest Distance Marker nearest to the matched position on the road.
Unit	Local unit of measure used for the offset, either `mi` or `km`.
DirectionOnSign	The direction given on the highway signs (if available).

Link Info (LinkInfoType)

The Link Info type provides additional information about the link in a road network.

Note: All link info attributes are subject to additional licensing. We reserve the right to require authorization on API level for all or individual attributes with future releases.

Table 14. Link Info elements
Type	Description
FunctionalClass	The functional class is used to classify roads depending on the speed, importance and connectivity of the road.
TravelDirection	Cardinal (`N`, `E`, `S`, `W`) or ordinal direction (`NE`, `SE`, `SW`, `NW`) for the navigable link following the direction of traffic on the street. If traffic is allowed in both directions two values will be returned. If the request contained a bearing parameter, then the first entry will match the returned direction.
SpeedCategory	Classifies the general speed trend of a navigable link based on posted or legal speed. (see SpeedCategoryType enumeration for possible values)
Traffic	A structure that lists all TMC codes and the free flow speed. If the request contained a bearing parameter, then the TMC codes will match the directions in the "TravelDirection" response field. A Free-flow speed is the speed at which traffic would be traveling at on a road segment when conditions are good (e.g., no rain or snow) and when traffic is not congested.
LinkFlags	Flags that describe special characteristics of the link like `Motorway`, `Tollroad`, `Paved`, etc. (see LinkFlagType enumeration for possible values).
AccessFlags	Flags that describe access characteristics of the link like `Automobiles`, `Buses`, `Pedestrians`, etc. (see LinkAccessFlagType enumeration for possible values).

Admin Info (AdminInfoType)

The Admin Info type provides additional information about an administrative area covering country or state meta information like the timezone or the currency used.

Table 15. Admin Info elements
Type	Description
TimeZoneOffset	UTC Timezone offset applicable for the area.
LocalTime	Local wall clock date and time in UTC format (ISO 8601).
Currency	ISO 4217 currency code used in the country.
DrivingSide	Driving side for road traffic used in the country, either `left` or `right`.
SystemOfMeasure	System of measure used in the country, either `imperial` or `metric`.

Timezone (TimezoneType)

The Timezone type provides detailed time zone information including offsets and daylight savings.

Table 16. Timezone elements
Type	Description
Id	Identifier for the timezone taken from the Java 8 platform.
Offset	Time zone offset in seconds, for current date, modified in case of daylight savings. This is the offset to add to UTC to get local time.
RawOffset	The amount of time in seconds to add to UTC to get standard time in this time zone. The current UTC offset is equal to `rawOffset` + `dstSavings`.
NameShort	A short standard time name of this time zone.
NameLong	A long standard time name of this time zone.
NameDstShort	A short Daylight Saving Time name of this time zone.
NameDstLong	A long Daylight Saving Time name of this time zone.
InDaylightTime	True, if the time zone is currently in Daylight Saving Time.
DstSavings	The amount of time to be added to local standard time to get local wall clock time during daylight saving time. Time in seconds saved during Daylight Saving Time.

Related Location (RelatedLocationType)

A related location object defines and classifies an association between two related locations.

Table 17. Related Location elements
Type	Description
Type	The type of the relationship to the associated location. The following types of related locations are supported: nearByDistanceMarker Location of a nearby distance marker on the highway. Retrieving distance markers is supported for the Reverse Geocoding mode `retrieveAddresses` and is enabled by the flag `&additionaldata=IncludeDistanceMarkers,true` nearByAddress Location of a nearby address on the same link. Retrieving nearby addresses is supported for the Reverse Geocoding mode `trackPosition` and is enabled by the flag `&locationattributes=related.nearByAddress` microPointAddress Location of a secondary address for a point address. Retrieving micro point unit addresses is supported for the Forward Geocoding mode and is enabled by the flag `&additionaldata=IncludeMicroPointAddresses,true`
MatchType	Relevant for `nearByAddress` relations. Information about the quality of the related location match. `pointAddress` Related location is based on a Point Address. `interpolated` Related location was interpolated.
RouteDistance	Distance to the associated location. The distance is calculated based on the underlying road geometry.
Direction	Relevant for `nearByAddress` relations. Bearing (measured clockwise from true north) from the projected coordinate on the street to the display position of the related location.
Location	Associated location. For a `nearByDistanceMarker` relation this is the location of the reference Distance Marker(s). For a `nearByAddress` relation this is the location of the closest house on the link. For a `microPointAddress` this contains details about the micro point unit.