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.

Figure 2. Overview Location Type

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 link (for address level results).
MapVersion Version of the map schema. Format: QQ/YYYY, e.g. Q1/2015
MapId

Map version details containing the base line for the map schema and an identifier for the weekly 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.
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.

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. Currently, only the SpeedLimit attribute requires authorization and the attribute is not included in LinkInfo if the client application is not authorized to receive this information.

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.