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.
|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.|
|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.|
The SearchResult contains the actual result as a Location object together with information on how good the result matches the search request.
|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 between the identified location object and the specified client position in meters. Only provided if a proximity was specified in the request (parameter
Note: With gen<6 the distance for admin area results is calculated from the given point to the center of the area.
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
The most detailed address field that matches the geocoding or reverse geocoding query.
|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. |
|MatchCode||Code indicating how well the result matches the request. Enumeration [ |
|ParsedRequest||Structured representation of the request which led to the current search result.|
|Location||The location that was found.|
Generic key/value container to keep additional attributes. The defined key/values are:
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.
|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 shows how the various components of the request were derived from search terms.
|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 |
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:
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.
|LocationId||A key uniquely identifying a physical location.|
|LocationType|| Indicates the type of the location. The following types are supported: |
|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: |
Generic key/value container to keep additional attributes. The defined key/values are:
Reference to a Map Object
|ReferenceId||PVID of the arrival link to represent the drive-to location.|
|MapVersion|| Version of the map schema. Format: |
|MapReleaseDate||Release date of the map data. Format: YYYY-MM-DD|
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>
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 [ |
|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 |
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.
|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.|
|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 |
|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 |
Generic key/value container to keep additional attributes. The defined key/values are:
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.
|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)|
|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.
|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.
|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.
|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 |
|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.
|FunctionalClass||The functional class is used to classify roads depending on the speed, importance and connectivity of the road.|
|TravelDirection||Cardinal ( |
|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 |
|AccessFlags||Flags that describe access characteristics of the link like |
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.
|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 |
|SystemOfMeasure||System of measure used in the country, either |
The Timezone type provides detailed time zone information including offsets and daylight savings.
|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 |
|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.|