Geocoder API Developer's Guidedocumentation.developer.here.com/pdf/geocoding_hlp/6.2... ·...

Geocoder APIDeveloper's Guide

Version 6.2.117

Geocoder API Developer's Guide 2► Notices

Important Information

NoticesTopics:

• Legal Notices

• Document Information

This section contains document notices.


Legal Notices© 2016 HERE Global B.V. and its Affiliate(s). All rights reserved.

This material, including documentation and any related computer programs, is protected by

copyright controlled by HERE. All rights are reserved. Copying, including reproducing, storing,

adapting or translating, any or all of this material requires the prior written consent of HERE. This

material also contains confidential information, which may not be disclosed to others without the

prior written consent of HERE.

Trademark Acknowledgements

HERE is trademark or registered trademark of HERE Global B.V.

Other product and company names mentioned herein may be trademarks or trade names of their

respective owners.

Disclaimer

This content is provided "as-is" and without warranties of any kind, either express or implied,

including, but not limited to, the implied warranties of merchantability, fitness for a particular

purpose, satisfactory quality and non-infringement. HERE does not warrant that the content is error

free and HERE does not warrant or make any representations regarding the quality, correctness,

accuracy, or reliability of the content. You should therefore verify any information contained in the

content before acting on it.

To the furthest extent permitted by law, under no circumstances, including without limitation the

negligence of HERE, shall HERE be liable for any damages, including, without limitation, direct, special,

indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or

application of this content, even if HERE or an authorized representative has been advised of the

possibility of such damages.


Document Information

Product

Name: Geocoder API

Version: Version 6.2.117

Document

Name: Geocoder API Developer's Guide

ID: 22b4d37-1467126025

Status: FINAL

Date: 2016-Jun-28, 15:04 (GMT)

Digital Signature

Signatory: O=HERE, CN=here.com, ST=Berlin, C=DE

Issuer-Certificate: O=HERE, CN=here.com, ST=Berlin, C=DE

Serial-Number.: 17391143833054135595

Method: urn:adobe.com:Adobe.PPKLite:adbe.pkcs7.sha1 (Adobe

Signature)

Geocoder API Developer's Guide 5► Contents

Contents

Notices....................................................................................................................................................................2Legal Notices............................................................................................................................................................ 3

Document Information........................................................................................................................................... 4

Chapter 1: Overview................................................................................................................................. 9What is the Geocoder API?................................................................................................................................. 10

Why use the Geocoder API?............................................................................................................................... 10

Chapter 2: Quick Start........................................................................................................................12Making Your First Requests................................................................................................................................13

Geocoding................................................................................................................................................................13

Reverse Geocoding............................................................................................................................................... 15

Multi Reverse Geocoding.....................................................................................................................................23

Landmark Geocoding............................................................................................................................................26

Chapter 3: User Guide......................................................................................................................... 28Acquiring Credentials............................................................................................................................................29

Constructing a Request....................................................................................................................................... 29

Customer Integration Testing.........................................................................................................................30

Request Encoding.............................................................................................................................................. 30

Key Concepts..........................................................................................................................................................31

Using Backwards Incompatible Features......................................................................................................31

Backwards Compatibility............................................................................................................................... 31

Different Generations of the Same API.................................................................................................... 32

Generation History......................................................................................................................................... 32

Customizing the Response with Attribute Switches..................................................................................35

Examples..................................................................................................................................................................37


Geocoding............................................................................................................................................................ 37

Find Address Based on Complete or Partial Address Information using Freeform Input............... 37

Find Address Based on Complete or Partial Address Information using Qualified Input................39

Find Address within a Geospatial Area...................................................................................................... 41

Find Street Intersections.............................................................................................................................. 42

Find a Specific Location by Identity...........................................................................................................43

Retrieval of Area Shapes.............................................................................................................................. 43

Reverse Geocoding............................................................................................................................................44

Find Addresses Near a Position.................................................................................................................. 44

Retrieve Area Information at a Position....................................................................................................45

Retrieve Nearby Area Information around a Position............................................................................ 45

Retrieve Area and Landmark Information at a Position........................................................................ 45

Retrieve Landmarks Around a Position..................................................................................................... 46

Retrieve Address Information at a Position using Search.................................................................... 47

Track Position Using Bearing Information................................................................................................48

Landmark Geocoding........................................................................................................................................ 49

Find Well Known Landmarks.........................................................................................................................49

Service Support..................................................................................................................................................... 51

Chapter 4: API Reference................................................................................................................. 52Resources and Parameters................................................................................................................................. 53

Geocode Resource.............................................................................................................................................53

Reverse Geocode Resource.............................................................................................................................58

Multi Reverse Geocode Resource.................................................................................................................. 62

Landmark Geocode Resource......................................................................................................................... 66

Additional Data Parameter...............................................................................................................................71

Response Data Types...........................................................................................................................................74

Search Response................................................................................................................................................74

Response (SearchResponseType)............................................................................................................... 76

MetaInfo (SearchResponseMetaInfoType)................................................................................................ 77

View (SearchResultsViewType).....................................................................................................................77

Result (SearchResultType)............................................................................................................................ 77


MatchQuality (LocationMatchQualityType)............................................................................................... 79

ParsedRequest (ParsedRequestType)........................................................................................................ 79

Location (LocationType)................................................................................................................................80

MapReference (MapReferenceType).......................................................................................................... 83

Address (AddressType).................................................................................................................................. 83

Address Details (AddressDetailsType)....................................................................................................... 85

Address Names (AddressNamesType)....................................................................................................... 86

Street Details (StreetDetailsType)..............................................................................................................86

Distance Marker (DistanceMarkerType).................................................................................................... 87

Link Info (LinkInfoType).................................................................................................................................87

Admin Info (AdminInfoType).........................................................................................................................88

Timezone (TimezoneType)............................................................................................................................88

Related Location (RelatedLocationType)...................................................................................................89

Multi Reverse Geocode Response..................................................................................................................90

Response (MultiSearchResponseType)...................................................................................................... 90

MetaInfo (MultiSearchResponseMetaInfoType).......................................................................................91

Item (MultiSearchResponseItemType)....................................................................................................... 91

Base Data Types................................................................................................................................................ 91

LatitudeType.................................................................................................................................................... 91

LongitudeType.................................................................................................................................................92

DistanceType................................................................................................................................................... 92

DistanceUnitType............................................................................................................................................92

HeadingType.................................................................................................................................................... 93

CardinalDirectionType....................................................................................................................................93

CountryCodeType........................................................................................................................................... 93

SideOfStreetType........................................................................................................................................... 94

ShapeFormatType...........................................................................................................................................94

ReverseGeocodeModeType.......................................................................................................................... 94

GeoCoordinateType........................................................................................................................................94

GeoBoundingBoxType....................................................................................................................................95

GeoProximityType...........................................................................................................................................96

GeoPositionType............................................................................................................................................. 97

GeoShapeType.................................................................................................................................................97


WKTShapeType................................................................................................................................................ 98

KeyValuePairType............................................................................................................................................98

LocalizedNameType........................................................................................................................................98

FunctionalClassType.......................................................................................................................................99

SpeedCategoryType....................................................................................................................................... 99

SpeedLimitType............................................................................................................................................ 100

LinkFlagType.................................................................................................................................................. 100

LinkAccessFlagType..................................................................................................................................... 101

RelationshipEnumType................................................................................................................................ 102

UTCTimeOffsetType.................................................................................................................................... 102

CurrencyType.................................................................................................................................................102

DrivingSideType............................................................................................................................................ 102

SystemOfMeasurementType..................................................................................................................... 103

Response Schemas and Examples..................................................................................................................103

XML Schemas....................................................................................................................................................103

Response Examples.........................................................................................................................................103

Chapter 5: Coverage Information.........................................................................................109Geocoder Coverage............................................................................................................................................110

Coverage Categories.......................................................................................................................................125

Political Views.......................................................................................................................................................127

Geocoder API Developer's Guide 9► Overview

Chapter

1

OverviewTopics:

• What is the Geocoder API?

• Why use the Geocoder API?

This section introduces the Geocoder API and describes its

common use cases.


What is the Geocoder API?Geocoder API is a web API that offers geocoding, reverse geocoding and landmark geocoding

services.

Geocoding

Geocoding matches an address to its correct location on the map. Applications submit addresses

or a search string containing partial address information. The result is either a single record exactly

matching the input, or a set of records ranked by relevance when the input is ambiguous or the input

cannot be found on the map in the requested detail.

Reverse Geocoding

Reverse geocoding retrieves a street address or administrative area information corresponding to a

given geo-coordinate.

Landmark Geocoding

Landmark geocoding is a combination of geocoding, landmark search, and reverse geocoding.

It supports search for airports, well known landmarks such as the Eiffel Tower or landmarks

classified as nationally important. The result is a list of ranked locations including street addresses,

administrative areas, or landmarks.

Why use the Geocoder API?

Use Cases

The Geocoder API returns lists of results ranked by relevance for the following use cases:

• Find geo-location based on complete or partial address information. Address information canbe in structured (qualified) or unstructured (single-line entry, un-qualified) form (for example,"street=425 W Randolph&city=Chicago" or "searchtext=425 W Randolph, Chicago").

• Find street intersection (for example, "Market @ Fell, San Francisco")

• Find address within geospatial area (for example, "searchtext=1 MarketSt&mapview=37.84491,-122.5040;37.7267,-122.3598").

• Find areas such as cities, states, counties, countries and postal codes (for example, "Springfield,IL", "London", "California").


• Find landmarks of national importance (for example, "Eiffel Tower").

• Get addresses or area information for a coordinate (for example, "41.8838 -87.6389")

Geocoder API Developer's Guide 12► Quick Start

Chapter

2

Quick StartTopics:

• Making Your First Requests

• Geocode Request

• Reverse Geocode Request

• Multi Reverse Geocode Requ...

• Landmark Geocode Request

The Geocoder API is a web API that you access using a REST

interface. This article contains example requests that you can run

to see how the service works.


Making Your First RequestsSometimes the easiest way to start using new software is to run simple working examples.

app_id and app_code are authentication credentials. This document uses {YOUR_APP_CODE} and

{YOUR_APP_ID} as placeholders for access and authorization credentials. Please replace these

placeholders with your own unique application-specific credentials to access the API resources.

For more information about the access and authorization credentials credentials, see Acquiring

Credentials on page 29.

The examples in this guide use the Customer Integration Testing (CIT) environment. This environment

allows you to test your software. For production please use the production environment. See

Constructing a Request on page 29 for the base URLs of both environments.

Note that most example URLs in this guide are broken up into multiple lines for better readability.

Remove these line breaks and spaces when copying and pasting the examples to make sure URLs are

still well formed.

Prerequisites

The only thing you need to start using the Geocoder API is an HTTP client. Choose any HTTP client

application you are familiar with. A command line tool like curl will do the job, as will any modern web

browser.

Geocode Request

Gecoding an Address

Send a request to the geocode endpoint to find an address using a combination of country, state,

county, city, postal code, district, street and house number.

Search for an address by setting the searchtext parameter to 425 W Randolph St, Chicago.

https://geocoder.cit.api.here.com/6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=425+W+Randolph+Chicago


Alternatively, specify individual parts of the address, such as housenumber, street, etc.

https://geocoder.cit.api.here.com/6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&housenumber=425&street=W+Randolph+St&city=Chicago

These requests return information about the location, including latitude and longitude, position

within the navigable road network and information about the quality of the match of your input to the

address or addresses it found.

<Relevance>1.0</Relevance><MatchLevel>houseNumber</MatchLevel><MatchQuality> <City>1.0</City> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber></MatchQuality><MatchType>pointAddress</MatchType>

MatchLevel shows that the most specific part of the match was house number. The match quality

(which goes from 0 to 1) indicates a good match. A MatchType of pointAddress indicates that

the exact address exists on the map. Other addresses are approximate and interpolated based on

address ranges on the street segment they are on. The MatchType in those cases is interpolated

and the result is usually less accurate than a pointAddress.

The Geocoder API also finds locations such as countries, states, counties, cities, districts, and postal

codes. The following example is a search for the city Berlin.

https://geocoder.cit.api.here.com/6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=Berlin

The response has only one result, Berlin in Germany, because Berlin is considered to be a prominent

city. If you are looking for a city in a specific country then you can add the country name or country

code to the searchtext. This gives a hint to the Geocoder. Or you can provide a strict country filter.

This strictly limits the responses to that country. The following examples show both options in a

search for the city Berlin in the USA.

https://geocoder.cit.api.here.com/6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=Berlin,+USA

https://geocoder.cit.api.here.com/6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}


&gen=9&searchtext=Berlin&country=USA

Reverse Geocode RequestThe reversegeocode endpoint allows client applications to either retrieve street address

information corresponding to a given coordinate and radius or to retrieve area information for a

given coordinate.

Retrieve Addresses

The following example is a request for addresses (mode=retrieveAddresses) within 100 meters of

latitude 50.111 and longitude 8.680.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&prox=50.112,8.683,100&mode=retrieveAddresses

The results are sorted by distance from the search center. Each result in the response contains the

following information:

• Relevance is always 1.0 for reverse geocode retrieveAddresses results.

• Distance in meters from the search center.

• MatchLevel shows the level of the most precise area information for the match.

• MatchQuality is always 1.0 for reverse geocode results.

• Location information:

◦ LocationType which is one of point, area or line.

◦ Latitude and longitude of the address.

◦ Latitude and longitude of the area to display the address on a map (MapView).

◦ Actual street address of the location.

◦ MapReference, containing the unique id of the location.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-09-15T06:34:14.645Z</Timestamp> <NextPageInformation>2</NextPageInformation> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>1.0</Relevance> <Distance>0.7</Distance>


<MatchLevel>houseNumber</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber> <PostalCode>1.0</PostalCode> </MatchQuality> <MatchType>pointAddress</MatchType> <Location> <LocationId>NT_OV3A4F7PVZMW36XQixpFiB_zAD</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>50.1123</Latitude> <Longitude>8.68285</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>50.112</Latitude> <Longitude>8.68301</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>50.1134242</Latitude> <Longitude>8.681097</Longitude> </TopLeft> <BottomRight> <Latitude>50.1111758</Latitude> <Longitude>8.684603</Longitude> </BottomRight> </MapView> <Address> <Label>Berliner Straße 30, 60311 Frankfurt am Main, Deutschland</Label> <Country>DEU</Country> <State>Hessen</State> <County>Frankfurt am Main</County> <City>Frankfurt am Main</City> <District>Altstadt</District> <Street>Berliner Straße</Street> <HouseNumber>30</HouseNumber> <PostalCode>60311</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Hessen</AdditionalData> <AdditionalData key="CountyName">Frankfurt am Main</AdditionalData> </Address> <MapReference> <ReferenceId>52308768</ReferenceId> <MapId>UWAM15124</MapId> <MapVersion>Q1/2015</MapVersion> <Spot>0.86</Spot> <SideOfStreet>left</SideOfStreet> <CountryId>20147700</CountryId> <StateId>20160993</StateId> <CountyId>20161002</CountyId> <CityId>20161003</CityId> <DistrictId>20299860</DistrictId> <AddressId>168611036</AddressId> </MapReference> </Location> </Result> </View> </Response></ns2:Search>


Retrieve Areas Information

The second example is a request for information (mode=retrieveAreas) about the area at the

point 50.111, 8.680. The radius is optional. With gen<7 the radius is ignored. With gen=7 or higher

the radius is not ignored and areas whose polygon boundaries lie within the radius are returned as

well. The mode can then be used to retrieve nearby areas.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&prox=50.112,8.683,100&mode=retrieveAreas

The response includes

• Relevance is always 1.0 for reverse geocode retrieveAreas results.

• Distance from the specified client position to the edge of the location area.

• Direction of the location seen from the specified client position.

• MatchLevel shows the level of the most precise area information available for the match,district, city or a higher administrative level.

• Location information in terms of:

◦ LocationType which is one of point, area or line.

◦ Latitude and longitude of the area.

◦ Latitude and longitude of the area to display the area on a map (MapView).

◦ Address (only the area information, no street or house number).

• MapReference information with Map version and IDs

<Result> <Relevance>1.0</Relevance> <Distance>-208.7</Distance> <Direction>165.2</Direction> <MatchLevel>district</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <PostalCode>1.0</PostalCode> </MatchQuality> <Location> <LocationId>NT_xG5rpFd6qDwqrPmW-sF-QA</LocationId> <LocationType>area</LocationType> <DisplayPosition> <Latitude>50.11132</Latitude> <Longitude>8.68328</Longitude> </DisplayPosition> <MapView> <TopLeft> <Latitude>50.11482</Latitude> <Longitude>8.67477</Longitude> </TopLeft> <BottomRight>


<Latitude>50.10693</Latitude> <Longitude>8.68821</Longitude> </BottomRight> </MapView> <Address> <Label> Altstadt, Frankfurt am Main, Hessen, Deutschland </Label> <Country>DEU</Country> <State>Hessen</State> <County>Frankfurt am Main</County> <City>Frankfurt am Main</City> <District>Altstadt</District> <PostalCode>60311</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Hessen</AdditionalData> <AdditionalData key="CountyName">Frankfurt am Main</AdditionalData> </Address> <MapReference> <ReferenceId>755686533</ReferenceId> <MapId>UWAM15124</MapId> <MapVersion>Q1/2015</MapVersion> <SideOfStreet>neither</SideOfStreet> <CountryId>20147700</CountryId> <StateId>20160993</StateId> <CountyId>20161002</CountyId> <CityId>20161003</CityId> <DistrictId>20299860</DistrictId> </MapReference> </Location></Result>

Track Position

Client applications can track vehicle positions more accurately by providing bearing information

to the Reverse Geocoder. Without any additional information the Reverse Geocoder might falsely

snap to a crossing street, to an over- or underpass, or to a nearby street - whatever is closer to the

provided coordinate. The example below tracks the position mode=trackPosition by providing the

bearing together with the position in the pos parameter. Bearing expresses the direction in which the

vehicle is heading in degrees starting at true North and continuing clockwise around the compass.

North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. The position in the

example is close to an intersection (Königsteiner Straße and Allee Strasse in Bad Soden, Germany). In

the request a north heading (350 degrees) is provided.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&pos=50.1417995,8.5034505,350&mode=trackPosition

The first result is Königsteiner Straße (1 in the left image) even though Allee Strasse (2) is closer to

the given position. The arrow in the image shows the bearing. The result flips around when changing

to an east heading (30 degrees). The first result is then Allee Strasse (right image).


reversegeocode.xml?mode=trackPosition&pos=50.1417995,8.5034505,350

reversegeocode.xml?mode=trackPosition&pos=50.1417995,8.5034505,30

The response includes

• Relevance expressing the confidence in the match. Values between 0 an 1.0.

• Distance from the specified position to the link match.

• MatchLevel always street for trackPosition results.

• Location information in terms of:

◦ LocationType is always address for gen=5 and higher, point otherwise.

◦ Latitude and longitude of the address.

◦ Latitude and longitude of the area to display the address on a map (MapView).

◦ Address (only the area information, no street or house number).

• MapReference information with Map version and IDs

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-09-15T06:34:14.645Z</Timestamp> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>0.68</Relevance> <Distance>20.2</Distance> <MatchLevel>street</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <Street>1.0</Street> <PostalCode>1.0</PostalCode> </MatchQuality> <Location> <LocationId>NT_VTZCRAxyPhgdwOX01.5y8A_l_52361527_L</LocationId> <LocationType>address</LocationType> <DisplayPosition>


<Latitude>50.1419495</Latitude> <Longitude>8.5036109</Longitude> </DisplayPosition> <MapView> <TopLeft> <Latitude>50.14287</Latitude> <Longitude>8.50275</Longitude> </TopLeft> <BottomRight> <Latitude>50.14136</Latitude> <Longitude>8.50419</Longitude> </BottomRight> </MapView> <Address> <Label>Königsteiner Straße, 65812 Bad Soden am Taunus, Deutschland</Label> <Country>DEU</Country> <State>Hessen</State> <County>Main-Taunus-Kreis</County> <City>Bad Soden am Taunus</City> <Street>Königsteiner Straße</Street> <PostalCode>65812</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Hessen</AdditionalData> <AdditionalData key="CountyName">Main-Taunus-Kreis</AdditionalData> </Address> <MapReference> <ReferenceId>52361527</ReferenceId> <MapId>UWAM15124</MapId> <MapVersion>Q1/2015</MapVersion> <Spot>0.15</Spot> <SideOfStreet>left</SideOfStreet> <CountryId>20147700</CountryId> <StateId>20160993</StateId> <CountyId>20161614</CountyId> <CityId>20161615</CityId> </MapReference> </Location> </Result> <Result> <Relevance>0.49</Relevance> <Distance>12.9</Distance> <MatchLevel>street</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <Street>1.0</Street> <PostalCode>1.0</PostalCode> </MatchQuality> <Location> <LocationId>NT_--A.v.nVr3c4vxvbu9swDA_l_52361473_L</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>50.1416867</Latitude> <Longitude>8.5034944</Longitude> </DisplayPosition> <MapView> <TopLeft> <Latitude>50.14179</Latitude> <Longitude>8.50196</Longitude> </TopLeft> <BottomRight> <Latitude>50.14109</Latitude> <Longitude>8.50376</Longitude> </BottomRight> </MapView> <Address> <Label>Alleestraße, 65812 Bad Soden am Taunus, Deutschland</Label>


<Country>DEU</Country> <State>Hessen</State> <County>Main-Taunus-Kreis</County> <City>Bad Soden am Taunus</City> <Street>Alleestraße</Street> <PostalCode>65812</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Hessen</AdditionalData> <AdditionalData key="CountyName">Main-Taunus-Kreis</AdditionalData> </Address> <MapReference> <ReferenceId>52361473</ReferenceId> <MapId>UWAM15124</MapId> <MapVersion>Q1/2015</MapVersion> <Spot>0.85</Spot> <SideOfStreet>left</SideOfStreet> <CountryId>20147700</CountryId> <StateId>20160993</StateId> <CountyId>20161614</CountyId> <CityId>20161615</CityId> </MapReference> </Location> </Result> </View> </Response></ns2:Search>

Track Position including Nearest Address Information

The track position feature, which uses coordinates and a bearing to correctly identify the correct

street being travelled upon, also adds the nearest address information to results, if requested.

The house number returned is based upon the nearest address on the road being travelled along.

Preference is for house numbers that are on the driving side, relative to the bearing, in that country.

For example, in Germany cars drive on the right-hand side, so travelling south on a road will choose a

house number right of the bearing.

This feature can be activated by using either of the following parameters:

locationattributes=(one of related.nearByAddress, rn, all)

The result provides the house number precision in a complete address in a separate Related

block. Track position provides the nearest address but does not snap to this address like

retrieveAddresses does.

The Related block contains the following additional details:

• Type is always nearByAddress for trackPosition results.

• MatchType is one of interpolated or pointAddress.

• RouteDistance refers to the distance in meters from the snapped position on the link to thenavigation position of the address. A user needs to travel this distance following the road toreach the entry of the house.

• Direction refers to the bearing of the display position of the address relative to a 0 bearingpoint to true north. A user needs to turn her view clockwise into this direction to see the house.


Below is an example that retrieves the track position for a point and requests that the nearest

address is added to the result:

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&pos=52.4662230,13.3282346,180&mode=trackPosition&locationattributes=rn

The result contains the street that is closest to the provided position and fits to the travel direction

and it contains the nearest address information in the Related block.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-11-27T14:28:53.717Z</Timestamp> <NextPageInformation>2</NextPageInformation> </MetaInfo> <View xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>0.99</Relevance> <Distance>0.4</Distance> <MatchLevel>street</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <Street>1.0</Street> <PostalCode>1.0</PostalCode> </MatchQuality> <Location> <LocationId>NT_9rsoB5zwTm8gcUzZatY7mC_l_821537980_L</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>52.466223</Latitude> <Longitude>13.32824</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>52.466223</Latitude> <Longitude>13.32824</Longitude> </NavigationPosition> <MapView> ... </MapView> <Address> <Label>Bundesallee, 12161 Berlin, Deutschland</Label> <Country>DEU</Country> <State>Berlin</State> <County>Berlin</County> <City>Berlin</City> <District>Friedenau</District> <Street>Bundesallee</Street> <PostalCode>12161</PostalCode> <AdditionalData...</AdditionalData> </Address> <MapReference> ... </MapReference>


<Related> <Type>nearByAddress</Type> <MatchType>pointAddress</MatchType> <RouteDistance>15.0</RouteDistance> <Direction>228.0</Direction> <Location> <LocationId>NT_9rsoB5zwTm8gcUzZatY7mC_5YD</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>52.46609</Latitude> <Longitude>13.328</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>52.46609</Latitude> <Longitude>13.32824</Longitude> </NavigationPosition> <Address> <Label>Bundesallee 96, 12161 Berlin, Germany</Label> <Country>DEU</Country> <State>Berlin</State> <County>Berlin</County> <City>Berlin</City> <District>Friedenau</District> <Street>Bundesallee</Street> <HouseNumber>96</HouseNumber> <PostalCode>12161</PostalCode> <AdditionalData...</AdditionalData> </Address> <MapReference> ... </MapReference> </Location> </Related> </Location> </Result> </View> </Response></ns2:Search>

Multi Reverse Geocode Request

Multi Reverse Geocoding Example

Retrieve street address or area information for up to one hundred coordinates with one multi reverse

geocoding HTTP POST request. The method is synchronous which means that the reverse geocoding

results are contained in the response.

The body of the HTTP POST request contains the coordinates and optional radius in the prox

parameter and an optional numeric identifier in the id parameter as plain text, one line per pair of

coordinates. The identifier associates each result with the corresponding input. If no id is provided

the system creates one starting with 0.

The number of coordinate pairs per request is limited to 100. Requests with more than 100

coordinate pairs result in an error response.

All further reverse geocoding parameters except prox and id can be specified in the URL as usual.


Retrieve Multiple Addresses with One Request

This example shows a request for one address (maxresults=1, mode=retrieveAddresses) for

ten sets of latitude, longitude and radius.

Set the body of the POST request to the file containing the ten sets of coordinates and ids,

id=0001&prox=52.5309792,13.3845797,50id=0002&prox=50.1618996,8.5334997,50id=0003&prox=40.72962607104243,-73.98685008095087,50id=0004&prox=47.609877297128094,-122.34250277090143,50id=0005&prox=-22.98040197212022,-43.189731399601726,50id=0006&prox=-8.494347821639211,115.25337974172669id=0007&prox=28.63383758137441,77.21917444061432,50id=0008&prox=-33.92046215720197,18.42085660357364,50id=0009&prox=21.00272769618338,-89.62247149160008,50id=0010&prox=24.660771905240175,46.71228298253175,50

and the URL of the post request to:

https://reverse.geocoder.cit.api.here.com/6.2/multi-reversegeocode.xml?mode=retrieveAddresses&maxresults=1&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

The following example shows a complete request using curl. The coordinates are in the text file

postfile.txt and the response is written to response.txt.

curl -X POST -H "Content-Type: text/plain" --data-binary @postfile.txt -o response.txt"https://reverse.geocoder.cit.api.here.com /6.2/multi-reversegeocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&mode=retrieveAddresses&maxresults=1"

Make sure to add the content type header Content-Type: text/plain and the --data-binary

parameter.

The following code shows part of the response. The <ItemId> element links the output <Item> with

the input id.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:MultiSearch> <Response> <MetaInfo> <Timestamp>2015-09-15T06:34:14.645Z</Timestamp> </MetaInfo> <Item> <ItemId>1</ItemId> <Result> <Relevance>1.0</Relevance> <Distance>0.1</Distance> <MatchLevel>houseNumber</MatchLevel> <MatchQuality> <Country>1.0</Country>


<State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber> <PostalCode>1.0</PostalCode> </MatchQuality> <MatchType>pointAddress</MatchType> <Location> <LocationId>NT_5v-U9-t5AZa5VsRdV06lLB_xEjN</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>52.53086</Latitude> <Longitude>13.38469</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>52.53098</Latitude> <Longitude>13.38458</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>52.5319842</Latitude> <Longitude>13.3828421</Longitude> </TopLeft> <BottomRight> <Latitude>52.5297358</Latitude> <Longitude>13.3865379</Longitude> </BottomRight> </MapView> <Address> <Label>Invalidenstraße 116, 10115 Berlin, Deutschland</Label> <Country>DEU</Country> <State>Berlin</State> <County>Berlin</County> <City>Berlin</City> <District>Mitte</District> <Street>Invalidenstraße</Street> <HouseNumber>116</HouseNumber> <PostalCode>10115</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Berlin</AdditionalData> <AdditionalData key="CountyName">Berlin</AdditionalData> </Address> </Location> </Result> </Item> <Item> <ItemId>2</ItemId> <Result> ... </Result> </Item> ... </Response></ns2:MultiSearch>


Landmark Geocode Request

Landmark Geocode Example

Landmark geocoding using the search endpoint is a combination of geocoding, search and

reverse geocoding. It is search for addresses, areas, landmarks, airports, and locations of national

importance. This includes internationally known landmarks such as the Eiffel Tower and airports such

as Chicago O'Hare, Heathrow and JFK.

Landmark Geocode Example

Landmark geocoding works exactly like geocoding. Provide the query with the searchtext

parameter. In the following example we search for the Ferry Building in San Francisco:

https://geocoder.cit.api.here.com/6.2/search.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=Ferry+Building,+San+Francisco

The result is a match to a landmark and contains Location information including position, Name

and Address.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-09-15T06:21:10.580Z</Timestamp> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>1.0</Relevance> <MatchLevel>landmark</MatchLevel> <MatchQuality> <City>1.0</City> <Name>1.0</Name> </MatchQuality> <Location> <LocationId>NT_hQVr4DptslhN54bxzBLoDB</LocationId> <LocationType>touristAttraction</LocationType> <Name>Ferry Building</Name> <DisplayPosition> <Latitude>37.79502</Latitude> <Longitude>-122.39365</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>37.79502</Latitude> <Longitude>-122.39365</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>37.80851</Latitude>


<Longitude>-122.41072</Longitude> </TopLeft> <BottomRight> <Latitude>37.78153</Latitude> <Longitude>-122.37658</Longitude> </BottomRight> </MapView> <Address> <Label>The Embarcadero, San Francisco, CA 94111, United States</Label> <Country>USA</Country> <State>CA</State> <County>San Francisco</County> <City>San Francisco</City> <District>Financial District</District> <Street>The Embarcadero</Street> <PostalCode>94111</PostalCode> <AdditionalData key="CountryName">United States</AdditionalData> <AdditionalData key="StateName">California</AdditionalData> <AdditionalData key="CountyName">San Francisco</AdditionalData> <AdditionalData key="PostalCodeType">N</AdditionalData> </Address> </Location> </Result> </View> </Response></ns2:Search>

In the previous example San Francisco was included in the query input. This is how an end user

typically enters a search term. Without the city name the query is ambiguous and the result is a list

of ferry buildings around the World. You can also restrict query results to a location or country. In the

example below the result is restricted to the country United States:

https://geocoder.cit.api.here.com/6.2/search.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=Ferry+Building&country=USA

Geocoder API Developer's Guide 28► User Guide

Chapter

3

User GuideTopics:

• Acquiring Credentials

• Constructing a Request

• Key Concepts

• Examples

• Service Support

The articles in this section provide a guide to using the Geocoder

API.


Acquiring CredentialsAll users of HERE APIs must obtain authentication and authorization credentials and provide them as

values for the parameters app_id and app_code. The credentials are assigned per application.

This document uses the placeholder text {YOUR_APP_CODE} and {YOUR_APP_ID} as placeholders

for access and authorization credentials. Please replace these placeholders with your own unique

application-specific credentials to access the API resources.

To obtain the credentials for an application, please visit http://developer.here.com/plans to register

with HERE.

If you wish to explore the API, use the API Explorer at https://developer.here.com/api-explorer.

Constructing a RequestA request to the Geocoder API includes the basic elements shown in the following table and, in

addition, it may contain resource-specific parameters.

Table 1: Basic request elements

Element Value/Example Description

Base URL https://geocoder.api.here.com

https://reverse.geocoder.api.here.com

https://geocoder.cit.api.here.com

https://reverse.geocoder.cit.api.here.com

Production environment

CIT environment: see Customer

Integration Testing on page 30

Path /6.2

Resource /geocode.json

/geocode.xml

/reversegeocode.json

/reversegeocode.xml

GET only except for multi-

reversegeocode (POST), specify

request details via query parameters

http://developer.here.com/plans

https://developer.here.com/api-explorer


Element Value/Example Description

/multi-reversegeocode.json

/multi-reversegeocode.xml

/search.json

/search.xml

Application Code &app_code={YOUR_APP_CODE} Substitute your own unique

app_code

Application Id &app_id={YOUR_APP_ID} Substitute your own unique app_id

Customer Integration TestingHERE is committed to maintain the best possible production service for all customers. Given that the

production environment is live and common to all API users, we request that you use the alternative

Customer Integration Testing (CIT) environment when evaluating our products, running tests, making

changes in your code and altering the way you access our APIs.

The CIT environment also allows you to test your software against a newer version of the service

before HERE brings that version into production. CIT offers a fully functional environment for

customers to use for development and testing, but it does not support high loads or performance

testing in general.

Note that the same application id can be used in both environments, but CIT may require a dedicated

application code. If this is the case, please contact us as described under Service Support.

The CIT environment is not intended for general production use.

Request EncodingEncode all query parameters in UTF-8, defining all special characters using a %FF hexadecimal

representation. For example, "K%C3%B6ln" for "Köln".

White spaces can be replaced by the + sign or %20. In this guide we use + for simplicity.

An example request for Köln, Germany:

https://geocoder.cit.api.here.com /6.2/geocode.xml?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9&searchtext=K%C3%B6ln,+Germany


When using HTML forms to post queries to the service interface, use the accept-charset attribute

to specify UTF-8 encoding instead of relying on the browser settings for parameter encoding.

<form action="https://geocoder.cit.api.here.com/6.2 /geocode.xml" method="GET" accept-charset="UTF-8"> <!—- etc. --></form>

Key ConceptsThis section provides information on key concepts used in the Geocoder API.

Using Backwards Incompatible FeaturesAll minor API updates and bugfixes are implemented in a way that does not break compatibility with

existing applications. Major updates that significantly change the API behavior are released on a

different URL.

Backwards CompatibilityThe following request interface changes are considered backward compatible:

• Adding new endpoints.

• Adding new optional parameters.

• Adding new enumeration values.

• Changing a parameter from mandatory to optional.

• Softening a parameter constraint.

The following changes in response structures are considered backward compatible:

• Adding new optional elements.

• Adding new enumeration values.

• Switching from mandatory to optional for an element but still ensuring that the element will bepopulated for existing requests.

• Adding new error subtypes.

• Hardening constraint for an element value.

Adding new endpoints or optional parameters is not backwards compatible according to the classic

definition of backwards compatibility, which states that the response from a more recent version

of the API should still be valid according to the XML schema of an older version. For these reasons

applications should be able to handle unknown elements and enumeration values while parsing a

response.


Different Generations of the Same APITo enable backwards incompatible functionality within the same major version of an API without

impacting existing applications use the gen parameter. Examples of these kinds of changes are:

• Changing the semantics of a filter criteria from a strict to a weak filter

• Changing the number of results in the response, for example, by introducing a fallback strategyto provide results even if the request cannot be fulfilled completely

• Changing the order of results

Evolutions of the API functionality are tagged using a monotonically increasing generation number. A

higher generation number includes all previous generations unless functionality is overridden by the

latest generation.

Any changes to functionality that need a particular generation number are labeled in the

documentation.

If you do not specify the generation parameter no backwards incompatible functionality is enabled.

Specifying the generation parameter allows the software to consider the application implementation

assumptions.

Generation HistoryThese are the supported generations together with the functionality that is available using only the

corresponding generation parameter value.

• gen=0 default behavior

• gen=1

◦ If a reverse geocoding request for an address does not find an address or street within the

set radius the area information is returned instead. If gen=0 the results with a 10,000 meter

radius are returned.

◦ Result MatchLevel for intersection matches is intersection. With gen=0 the

MatchLevel for intersection matches is street.

• gen=2

◦ Includes gen=1 functionality.

◦ Return the area display point (e.g. the center of the area) for reverse geocode area

responses. With gen<2 the DisplayPoint simply mirrors the point from the request.

◦ Return map version in element MapReference if requested via

locationattributes=(one of mr, mapReference, all)


• gen=3


◦ Reverse geocoding address results have display and navigation positions. With gen<3

address results from reverse geocoding only have a display position which in actuality is the

navigation position. With gen=3 this bug is fixed.

◦ MatchType pointAddress for reverse geocoding Point Address results. Otherwise

interpolated. With gen<3 address results from reverse geocoding always have

MatchType interpolated.

• gen=4


◦ Forward geocoding: Avoid ambiguous street level results that are near to each other and/or

can only be disambiguated based on one or a combination of district name/postal code. With

gen<4 forward geocoding responses have one result per postal code or district.

• gen=5


◦ Reverse geocoding: Enforce country filter. Reverse geocoder results are constrained to

the set country. This is a bug fix. With gen<5 reverse geocoder ignores the country filter.

Forward geocoder behavior does not change. The country filter has always been enforced.

◦ Reverse geocoding: Reverse Geocoder tries to aggregate links to a single street match

instead providing one street match per link where only coordinates are different.

◦ LocationType (element of Location) is specific to the result and not just point for any

result. LocationType is

▪ address: for MatchLevel houseNumber, street, intersection

▪ area: for MatchLevel country, state, county, city, district,

postalCode

▪ specific to the landmark for MatchLevel landmark. E.g. park, river,

golfCourse, industrialComplex, island etc.

This change impacts forward and reverse geocoder results.

• gen=6


◦ Landmarks found by the search endpoint are exposed as Location. Before they were

exposed as Place. This simplifies the response structure and removes some redundant

information. See example response for Eiffel Tower search below.


▪ placeId was only derived from locationId and was never a reference to any external

system

▪ category.categoryId is replaced by a locationType that is specific to the result

since gen=5 (before locationType was always "point")

▪ category.categorySystemId was always "facility"

▪ suppliers was always empty

search.json?searchtext=Eiffel+Tower&gen=5&language=en

search.json?searchtext=Eiffel+Tower&gen=6&language=en

relevance: 1,matchLevel: "landmark",matchQuality: { name: 1},place: { placeId: "801890088", name: "Eiffel Tower", category: [ { categoryId: "5999", categorySystemId: "facility" }], suppliers: [ {} ], locations: [ { locationId: "NT_AIzytxewh0cMjfGkhX4O.B", locationType: "historicalMonument", name: "Eiffel Tower", displayPosition: { latitude: 48.85824, longitude: 2.2945 },...

relevance: 1,matchLevel: "landmark",matchQuality: { name: 1},location: { locationId: "NT_AIzytxewh0cMjfGkhX4O.B", locationType: "historicalMonument", name: "Eiffel Tower", displayPosition: { latitude: 48.85824, longitude: 2.2945 },...

This change impacts forward and reverse geocoder results.

◦ The distance for Reverse Geocoder admin area results is calculated from the given point to

the polygon boundary. The distance is therefore negative in cases where the given point is

inside the area. This is now aligned with landmark results. With gen<6 the distance for admin

area results is calculated from the given point to the center of the area.

• gen=7


◦ The radius value for Reverse Geocoder mode=retrieveAreas requests is no longer

ignored. If the proximity value is provided and greater 0 then areas that lie within the radius

are contained in the response. Example: Request area information for a coordinate in

Potsdam, a city near Berlin:

mode=retrieveAreas&prox=52.39702,13.04811,10000&level=city&gen=7.


Besides Potsdam the response contains results Berlin and other nearby cities that lie within

10,000 meters from the given coordinate.

• gen=8


◦ Prefer street match (point on link) close to reference point instead of house number match

far away

This applies to reverse geocoding mode=retrieveAddresses. If a house number location

is outside of the provided radius do not snap to it. Instead, return the street level result. With

gen<8 the service snaps to house number locations if the closest link position is within the

provided radius and the house number location is not further away than 150 from that point.

• gen=9 (recommended)


◦ Location.AdminInfo.TimeZoneOffset moved to

Location.AdminInfo.TimeZone.Offset together with the other time zone information.

See Timezone for details.

&gen=8&locationattributes=tz

&gen=9&locationattributes=tz

Location.AdminInfo.TimeZoneOffsetLocation.AdminInfo.LocalTimeLocation.AdminInfo.CurrencyLocation.AdminInfo.DrivingSideLocation.AdminInfo.SystemOfMeasure

Location.AdminInfo.LocalTimeLocation.AdminInfo.CurrencyLocation.AdminInfo.DrivingSideLocation.AdminInfo.SystemOfMeasureLocation.AdminInfo.TimeZone.IdLocation.AdminInfo.TimeZone.OffsetLocation.AdminInfo.TimeZone.RawOffsetLocation.AdminInfo.TimeZone.NameShortLocation.AdminInfo.TimeZone.NameLongLocation.AdminInfo.TimeZone.NameDstShortLocation.AdminInfo.TimeZone.NameDstLongLocation.AdminInfo.TimeZone.InDaylightTimeLocation.AdminInfo.TimeZone.DstSavings

Please note that the previous list of changes are not the only changes introduced between two

generations. Only changes that might cause conflicts with existing client implementations are tagged

with a specific generation number.

Customizing the Response with Attribute SwitchesResponses always contain a default set of elements. You can increase or reduce the amount of

information in the response using attribute switch parameters to specify which elements are

returned.


For example, to add matchCode and parsedRequest add the following to the request:

&responseattributes=matchCode,parsedRequest

or use abbreviated forms

&responseattributes=mc,pr

The following example removes mapView and returns only address and mapReference.

&locationattributes=-mapView

To add additionalData to the previous example, returning address, mapReference and

additionalData use:

&locationattributes=-mapView,additionalData

If all attributes except mapView are required, use the all value and remove unnecessary attributes.

The following example returns the whole attribute set except mapView.

&locationattributes=all,-mapView

If you only want to specify a small set of attributes, use the none value and add required attributes.

The following example returns only address.

&locationattributes=none,address

Table 2: Attribute switches and values

Attribute switch Values

addressattributes Comma separated list of which elements are present in the response data.

Enumeration [country, state, county, city, district, subdistrict, street,

houseNumber, postalCode, addressLines, additionalData]

Abbreviated forms: [ctr, sta, cty, cit, dis, sdi, str, hnr, pst, aln, add]

On by default: All except addressLines.

Note: The value names are case-sensitive.

locationattributes Comma separated list of which elements are present in the response data.

Enumeration [address, mapReference, mapView, addressDetails,

streetDetails, additionalData, adminIds, linkInfo, adminInfo, timeZone,

addressNamesBilingual, related.nearByAddress]

Abbreviated forms: [ar, mr, mv, dt, sd, ad, ai, li, in, tz, nb, rn]

The adminIds switch is available with forward geocoding only.


Attribute switch Values

For reverse geocoding results adminIds are always present unless turned off via

locationattributes=none. locationattributes=-adminIds has no effect on

reverse geocoding results.

The related.nearByAddress switch is available with the trackPosition mode of

reverse geocoding only.

On by default for reverse geocoding: address, mapView, additionalData,

mapReference, adminIds.

For forward geocoding: address, mapView, additionalData.

With mapReference link PVID, side of street, and admin area PVIDs are present in the

response data. With adminIds only admin area PVIDs are present.


responseattributes Comma separated list of which elements are present in the response data.

Enumeration [performedSearch, matchQuality, matchType, matchCode,

parsedRequest]

Abbreviated forms: [ps, mq, mt, mc, pr]

On by default: matchQuality, matchType


ExamplesThis section provides examples of Geocoder API requests.

Geocoding ExamplesThis section provides examples of geocode requests.

Find Address Based on Complete or Partial AddressInformation using Freeform InputThe simplest use of the API is to search for an address using complete or partial address information

in a single-line input field, the searchtext parameter. Any address information can be provided in

the single input field, country, state, county, city, street, house number, or postal code.


Freeform Example with Complete Address Input

The following example is a search for 425 W Randolph Street in Chicago using a fairly complete

address as input.

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=425+W+Randolph+Street,+Chicago&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

There is only one result for this query. Here is the label portion and the display position of the result:

<Label>425 W Randolph St, Chicago, IL 60606, United States</Label>...<DisplayPosition> <Latitude>41.8838692</Latitude> <Longitude>-87.6389008</Longitude></DisplayPosition>

Setting the gen parameter to the highest available value makes the API return the latest features.

Freeform Example with Partial Address Input

The following example is a search for 425 W Randolph Street in Chicago omitting the street type. The

address is still found and there is still only a single result:

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=425+W+Randolph,+Chicago&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

Example with Ambiguous Address Input

Partial input can be ambiguous. In the following example the street direction is omitted:

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=200+Randolph+Street,+Chicago&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

There are now two results because the address exists on both East and on West Randolph Street.

Both results are equally good and the order is arbitrary:

<Label>200 E Randolph St, Chicago, IL 60601, United States</Label><Label>200 W Randolph St, Chicago, IL 60606, United States</Label>


Find Address Based on Complete or Partial AddressInformation using Qualified InputIf the address input is available in parsed form you can remove ambiguity by using specific fields

for the address information. For example, a house number will never be mistaken for a postal code

or a city name will not be interpreted as street name (San Antonio Rd in Palo Alto vs. the Palo Alto

Rd in San Antonio). The following fields are available: country, state, county, city, district,

postalcode, street, housenumber

An address search requires the street field, and either one or more of the locality type fields city

and district or postalcode. The locality and postal code can be omitted if a user context such as

a mapview is present.

Qualified input is aimed at geocoding business addresses where locality information is typically

provided.

The house number can be provided in field housenumber or can also be attached to the street

field. In the example below it is provided in its own field:

Qualified Input Example

The following example is a search for 425 W Randolph Street in Chicago and provides a fairly

complete address as input.

https://geocoder.cit.api.here.com/6.2/geocode.xml?state=IL&city=Chicago&street=W+Randolph+Street&housenumber=425&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

The result is the same as the previous freeform input.

<Label>425 W Randolph St, Chicago, IL 60606, United States</Label>...<DisplayPosition> <Latitude>41.8838692</Latitude> <Longitude>-87.6389008</Longitude></DisplayPosition>


City vs. District Match in Qualified Geocoding

If you are uncertain whether part of your address information is a city name or a district

name you can specify that the service should return matches for both cases with the

&additionaldata=FlexibleAdminValues,1 parameter.

The following example is a search for Friedrichstrasse in the city Mitte. But Mitte is actually a district

of Berlin.

https://geocoder.cit.api.here.com/6.2/geocode.xml?city=Mitte&street=Friedrichstr+100&additionaldata=FlexibleAdminValues,1&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

When you add the &additionaldata=FlexibleAdminValues,1 parameter the query returns the

correct address.

<Address> <Label>Friedrichstraße 100, 10117 Berlin, Deutschland</Label> <Country>DEU</Country> <State>Berlin</State> <County>Berlin</County> <City>Berlin</City> <District>Mitte</District> <Street>Friedrichstraße</Street> <HouseNumber>100</HouseNumber> <PostalCode>10117</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Berlin</AdditionalData></Address>

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).

Combining Freeform with Qualified Input

Freeform and qualified input can also be combined. For example, a freeform search can be qualified

with state or country information. The following example limits the search for Main St in Springfield

to the state of Missouri. Without the state information a large number of matches in various states of

the USA is returned.

https://geocoder.cit.api.here.com/6.2/geocode.xml?state=MO&searchtext=Main+St+Springfield&gen=9&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}


Restricting the search to Missouri returns only one address.

<Label>Main St, Springfield, MO 65802, United States</Label>

state can be either a state code or name, and is not a strict filter, if no match is found in the

specified state the response contains matches from other states.

Find Address within a Geospatial AreaAdditional context in form of geospatial area information can replace precise address information

in the input. This is especially important for queries without city, district or postal code information.

Geospatial context can be added to a request in three ways:

• mapview: Matches from within the set map view plus an extended area are ranked highest.

Relevant global results are also returned.

• bbox: The bbox search is currently similar to mapview but it is not extended.

• prox: Position plus radius. Search is similar to mapview. Matches from inside set area are ranked

higher. Relevant global results are also returned.

Addressline-only Example

Providing additional context is especially important for queries without city, district or postal code

information. The following example is a search for Market St and a map view over San Francisco:

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=Market+St&mapview=37.7983366,-122.4006509;37.7904096,-122.3916387&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Depending on the map view center and size the results will be different. The results are sorted by

distance from the map view center.

<Distance>191.8</Distance>...<DisplayPosition> <Latitude>37.7927742</Latitude> <Longitude>-122.396965</Longitude></DisplayPosition>...<Label>Market St, San Francisco, CA 94111, United States</Label>...<Distance>719.7</Distance>...<DisplayPosition> <Latitude>37.7893333</Latitude> <Longitude>-122.4012833</Longitude></DisplayPosition>...


<Label>Market St, San Francisco, CA 94104, United States</Label>

Find Street IntersectionsStreet intersections can be searched for using either freeform or qualified input. Either combine both

street names in the single street field or as separate street names in fields street0 and street1.

If two street names are provided in one text either within searchtext or street then separate the

two names with one of and, at, & or @.

Intersection Search Example

The following requests show the three ways to search for street intersections.

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=Pine+St+@+Market+St+San+Francisco&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

https://geocoder.cit.api.here.com/6.2/geocode.xml?city=San+Francisco&street=Pine+St+@+Market+St&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

https://geocoder.cit.api.here.com/6.2/geocode.xml?city=San+Francisco&street0=Pine+St&street1=Market+St&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

The response for each of the requests is identical.

<MatchLevel>intersection</MatchLevel>...<DisplayPosition> <Latitude>37.7924881</Latitude> <Longitude>-122.3973389</Longitude></DisplayPosition>...<Address> <Label> Pine St & Market St, San Francisco, CA 94105, United States </Label> <Country>USA</Country> <State>CA</State> <County>San Francisco</County> <City>San Francisco</City> <District>South Beach</District> <Street>Pine St & Market St</Street> <PostalCode>94105</PostalCode> <AdditionalData key="CountryName">United States</AdditionalData> <AdditionalData key="StateName">California</AdditionalData>


</Address>

Note that for intersection matches the chosen gen makes a difference. If gen>=1 the MatchLevel

is intersection. If gen=0 the MatchLevel is street.

Find a Specific Location by IdentityEvery Geocoder response contains a LocationID that can be used to look up an address again at a

later time. It can also be used to look up additional information like an admin shape for the location

or to retrieve a different representation of the location like the address in a different language.

The LocationID is a hash code generated from address components. The LocationID is not

guaranteed to be permanent across map versions. The following example uses the LocationID to

retrieve the city shape together with location information:

https://geocoder.cit.api.here.com/6.2/geocode.xml?locationid=NT_NVpegjQLOBQa8ORYk3jV7A_xA&additionaldata=IncludeShapeLevel,city&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Retrieval of Area ShapesLocation information of geocoding requests can include area or postal code shape information.

These shapes can be used as map overlays, for example. To get shape information add

additionaldata=IncludeShapeLevel,<level> to the request.

Valid shape levels are: country, state, county, city, district, postalCode, default

Level default returns the area shape corresponding to the match level.

The following example adds the postal code shape information to the response:

https://geocoder.cit.api.here.com/6.2/geocode.xml?searchtext=94301+USA&additionaldata=IncludeShapeLevel,postalCode&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

The shape information is in Well Known Text (WKT) format, in the element Shape in x y format where x

is longitude and y latitude.

<Location> <Address> ... <PostalCode>94301</PostalCode> ... </Address> <Shape>


<Value>POLYGON ((-122.13053 37.43417, -122.13080 37.43374, -122.13085 37.43369, -122.13119 37.43349, -122.13158 37.43326, -122.13181 37.43319, -122.132 37.43319, -122.13251 37.4333, -122.13275 37.4334 ... -122.13053 37.43417)) </Value> </Shape><Location>

Shapes can consist of multiple polygons. Example:

<Location> <Address> ... <PostalCode>94304</PostalCode> ... </Address> <Shape> <Value>MULTIPOLYGON (((-122.14427 37.42147, -122.14158 37.42004, -122.14067 37.42117, ... -122.14427 37.42147)), ((-122.17107 37.44626, ... -122.17107 37.44626))) </Value> </Shape><Location>

Reverse Geocoding ExamplesThis section provides examples of reverse geocoding requests.

Find Addresses Near a PositionThe mode parameter specifies that the service should snap to closest address or street. In this

request the radius is limited to 100 meters. If no address or street is found within that radius the

service falls back to retrieval of area information. The gen parameter with value >=1 is essential for

limiting the results to locations within the set radius. See also Generation History on page 32

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?prox=50.112,8.683,100&mode=retrieveAddresses&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9


Retrieve Area Information at a PositionExample request to retrieve area information at the set position. The mode parameter is set to

retrieveAreas which instructs the service to retrieve the area information at the set position.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?prox=50.112,8.683&mode=retrieveAreas&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Retrieve Nearby Area Information around a PositionExample request to retrieve area information nearby the set position. The mode parameter is set to

retrieveAreas. The radius of the prox parameter is set to 10,000. level limits results to match

level city. By default any admin level is returned. sortby instructs the service to sort the results by

population count. Results can also be sorted by size (approximate area size) and by distance

(default). Retrieval of nearby area information requires gen=7 or higher. With gen<7 the function

falls back to retrieval of the area information at the specified position only.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?prox=50.112,8.683,10000&mode=retrieveAreas&level=city&sortby=population&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Retrieve Area and Landmark Information at a PositionThe example below retrieves area and landmark information from a point close to the Presido in San

Francisco. The mode parameter is set to retrieveAll. No radius is provided because we just want

to know what is at that point. For example, we are not interested in streets or addresses near-by.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?prox=37.80358,-122.44832&mode=retrieveAll&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Two areas are intersecting with the given point: The landmark "Palace of Fine Arts" and the district

"Presidio". Below are details for both results. The complete admin and address information is also


part of the results. The information is just omitted below for space reasons. The distance is negative

for both results because the given point is inside the polygon.

Note: Since gen=6 the distance for admin area results is calculated from the given point to

the polygon boundary. This allows client applications to tell whether the given point is inside

the polygon or not. With gen<6 the distance is calculated from the given point to the area

centroid.

distance: -117.2direction: 254.5matchLevel: "district",...location: { locationId: "NT_3k-9bTamuJdmfGCuY9h3wB", locationType: "area", ... address: { label: "Presidio, San Francisco, CA, United States", ...

distance: -73.7matchLevel: "landmark",...location: { locationId: "NT_uQxRsUDYq4Gf3gjb2bKrEB_p_wcyTPTwD08nAzfdHIKshSB", locationType: "park", name: "Palace of Fine Arts", ... address: { label: "Palace Dr, San Francisco, CA 94123, United States", ...

Retrieve Landmarks Around a PositionThis example looks at landmarks in the proximity of Sand Hill Rd in Palo Alto. For this example we are

not interested in admin information and also not in streets or addresses. The mode parameter is set

to retrieveLandmarks and the radius is set to 1000 meters.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?prox=37.43823,-122.17796,1000&mode=retrieveLandmarks&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

There are five landmarks found within this proximity including a shopping center, a university, a

hospital and two parks. The matchLevel for all is "landmark". Here are details from the first result:

distance: 171.7matchLevel: "landmark",...location: { locationId: "NT_5WFfaH0.F5ZFwve3Ns3w3A_p_mafrT7LahvODUZjOMtdtaC", locationType: "hospital", name: "Stanford Hospital & Clinics", ...


address: { label: "300 Pasteur Dr, Stanford, CA 94305, United States", ...

Retrieve Address Information at a Position using SearchA simple way to make reverse geocoding requests is to pass the coordinates as searchtext to the

search endpoint.

The following coordinate formats are supported, where D= degree, M= minute and S= second.

• DD.MMMMM

• DD.MMMMM°

• DD MM SS

• DD MM SS.SS

• DD°MM'SS"

• DD°MM'SS.SS"

• DD°MM.SS'

Each with +/- pre- and N/S/E/W post-fixes. Spaces are ignored. If latitude (first) coordinate is less

than -90 or greater than 90 then latitude and longitudes are switched. Examples:

• 37,121

• 37, 121

• 121.0 37.0

• 37N, 121W

• 37N,121W

• 37N 121W

• 37N, -121W (Latitude 37 Longitude 121: negative West equals East: a location in China)

• 37° 121°

• 37°0'0" 121°0'0"

• 50° 9' 43" N 8° 32' 1" E

Invalid formats due to potential conflicts with postal codes.

• 37 121

• 121 37

An example using searchtext containing coordinates.

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=50.1115118%208.6805059&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9


Track Position Using Bearing InformationClient applications can track vehicle positions more accurately by providing the travel direction in

form of bearing information to the Reverse Geocoder. Without the bearing, the Reverse Geocoder

might falsely snap to a crossing street, to an over- or underpass, or to a nearby street - if it is closer

to the provided coordinate. This can happen easily because of the inaccuracy of the GPS.

Use mode=trackPosition and pos with coordinate and bearing for this use case. In the example

below a client application passes on a position near the intersection of O'Farrell St (going east) and

Van Ness Ave (going north) in San Francisco. In this case, the position is on Van Ness and a few meters

north of O'Farrell. The bearing is 80 degrees. This means the vehicle most likely travels east and then

O'Farrell is the better match. Without bearing information or with mode=retrieveAddresses the

first result would be on Van Ness Ave, which is most likely not the street that the vehicle is on.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml?pos=37.7849507,-122.4211569,80&mode=trackPosition&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

The results are sorted by Relevance, which for mode=trackPosition expresses the confidence

of the Reverse Geocoder into this match. The first three results are shown below. The third result

Van Ness Ave is only 0.3 meters away from the provided position. But because of the bearing the

confidence is lower than for the other two matches.

relevance: 0.78distance: 21.5matchLevel: "street",...location: { locationId: "NT_nr8HVxV.kOEiHXKlHoIE0A_l_815826134_L", locationType: "address", ... address: { label: "O'Farrell St, San Francisco, CA 94109, United States", ...

relevance: 0.68distance: 31.6matchLevel: "street",...location: { locationId: "NT_5V25cCF0wAAoQ4CqmCMt8C_l_815826136_R", locationType: "address", ... address: { label: "Myrtle St, San Francisco, CA 94109, United States", ...

relevance: 0.62distance: 0.3matchLevel: "street",...


location: { locationId: "NT_5DmLoeLNDKXxFIbZ44QhfA_l_815826149_L", locationType: "address", ... address: { label: "Van Ness Ave, San Francisco, CA 94109, United States", ...

Landmark Geocoding ExamplesThis section provides examples of landmark geocoding requests.

Find Well Known LandmarksYou can find various types of well known landmarks using location search:

• Major airports - using the IATA airport code or the airport name.

• Landmarks of national importance - defined as landmarks whose names are recognizable without

a city name. For example, Eiffel Tower is recognizable without the city name of Paris. These

include:

◦ Historical monuments

◦ National parks

◦ Tourist attractions

Table 3: Find Well Known Landmarks

Required Optional (area qualifiers and spatial filters)

• searchtext (text or name to search for) • country

• state

• county

• city

• district

• postalcode

• mapview

• bbox

• prox

• categoryids

• name


Example landmark request:

This example shows a global search for "Eiffel Tower".

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=Eiffel+Tower&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&gen=9

Example Highway Exit Search

The examples below show different ways to search for highway exits. To avoid ambiguity with other

landmarks or address results the search can be limited to a category using categoryids parameter.

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=A67+4&categoryids=116&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=A67&name=4&categoryids=116&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=A67&name=4&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=A67+4&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

https://geocoder.cit.api.here.com/6.2/search.xml?searchtext=A67+4+Gross-Gerau&categoryids=116&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

The table below shows the category Ids for the most relevant landmark categories.


Table 4: Landmark Category Ids

Category Name Category Id

Highway Exit 116

Ferry Terminal 4482

Airport 4581

Historical Monument 5999

Sports Complex 7940

Park/Recreation Area 7947

Amusement Park 7996

Tourist Attraction 7999

Museum 8410

Border Crossing 9999

Service SupportIf you need assistance with this or other HERE products, please contact your HERE representative or

Technical Customer Support.

If you have technical questions about the HERE APIs, go to the HERE Stack Overflow page.

http://stackoverflow.com/questions/tagged/here-api

Geocoder API Developer's Guide 52► API Reference

Chapter

4

API ReferenceTopics:

• Resources and Parameters

• Response Data Types

• Response Schemas and Examp...

This part of the guide provides a comprehensive reference to

Geocoder API.


Resources and ParametersThis section provides a comprehensive reference to the query parameters supported by the

Geocoder API.

The Geocoder API service defines one unified request structure for all scenarios. Depending on the

usage scenario, different parameter subsets are supported. Please refer to the chapter Examples on

page 37 for supported parameter combinations.

Name URL

Geocoding https://geocoder.api.here.com/6.2/geocode.{format}

Reverse geocoding https://reverse.geocoder.api.here.com/6.2/reversegeocode.{format}

Multi reverse geocoding https://reverse.geocoder.api.here.com/6.2/multi-reversegeocode.

{format}

Landmark geocoding https://geocoder.api.here.com/6.2/search.{format}

Where {format} is either JSON or XML.

Geocode ResourceThis section contains a list of all Geocode request parameters.

.../6.2/geocode.{format}?<parameter>=<value>...

Table 5: Request Parameters

Parameter Description

additionaldata Key-value pairs that provide additional input to requests. See Additional Data Parameter on

page 71 for a full list. Key and value are separated using a ,. Multiple key-value pairs are

separated using a ;:

additionaldata=<Key1>,<Value1>;<Key2>,<Value2>;...

Example:

additionaldata=PreserveUnitDesignators,true; IncludeZipAddon,true









app_id xs:string

A 20 byte Base64 URL-safe encoded string used for the authentication of the client

application.

You must include an app_id and app_code with every request. To get an app_id assigned

to you, please see Acquiring Credentials on page 29.

app_code xs:string


application.



bbox see also GeoBoundingBoxType on page 95

A type of Spatial Filter. A spatial filter limits the search for any other attributes in the

request. A bounding box bbox is specified by two latitude / longitude pairs; the first pair

defines the top left corner of the bounding box, the second set the lower right. The bbox

search is currently similar to mapview but it is not extended. Relevant global results are also

returned.

bbox=<TopLeft.Latitude>,<TopLeft.Longitude>; <BottomRight.Latitude>,<BottomRight.Longitude>

Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965

city xs:string, fuzzy match

A country specific mapping is required. Example,

• USA: City

• Germany: Gemeinde

country xs:string, exact match

Specify the country or list of countries using the country code (3 bytes, ISO 3166-1-alpha-3)

or the country name. This is a strict filter. Results are restricted to the specified country or

countries.

Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO code

and not with the spelled out country name. With names there is a higher risk of misspells and

also not all language translations for all countries are supported.

countryfocus xs:string, exact match, single ISO 3166-1-alpha-3 country code

Results from the specified country are preferred. This is a soft filter. Spelled out country

names are not supported for country focus.



• If both hard country filter and soft country focus parameter are set in the request

the country filter takes precedence over the focus. This means results are limited to

countries specified with country filter.

• bbox or mapview filter take precedence over the country focus if there is a conflict.

county xs:string, fuzzy match

Second subdivision level below the country. Depending on the admin hierarchy in a country

this level might not be applicable. Example,

• USA: County

• Germany: Kreis

district xs:string, fuzzy match

Subdivision level below the city. Depending on the admin hierarchy in a country this level

might not be applicable. Example,

• USA: n/a

• Germany: Ortsteil

gen xs:int

The gen parameter enables or disables backward incompatible behavior in the API. Please

see details and the generation history in chapter Different Generations of the Same API. The

latest generation is always recommended. This is currently gen=9.

housenumber xs:string, exact match

The house number or house name.

jsonattributes xs:int

If set to 1, the first character of each JSON response attribute name is set to lower case.

Default value is 0.

jsoncallback xs:string

Specifies the name of a user-defined function used to wrap the JSON response.

language LanguageCodeType

The preferred language of address elements in the result. Language code must be provided

according to RFC 4647 standard. Note that the plural form of the parameter (languages)

is supported as well. But only the last specified language in the list is used. All preceding

language preferences are ignored at this time.




















locationid xs:string, exact match

A key uniquely identifying a physical location. Each record in a geocode response contains

a location Id. Use the Id to retrieve the exact same location information. For example, the

location Id for "1 Market Street, 94105 San Francisco" is NT_NVpegjQLOBQa8ORYk3jV7A_xA.

mapview See GeoBoundingBoxType on page 95

Specify the map coordinates of the app's viewport. The mapview is specified by two

latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the

second set the lower right. Matches from within the set map view plus an extended area are

ranked highest. Relevant global results are also returned.

mapview=<TopLeft.Latitude>,<TopLeft.Longitude>; <BottomRight.Latitude>,<BottomRight.Longitude>

Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965

maxresults xs:int

The number of items in the response structure can be limited. By specifying maxresults,

the number of results per response are limited. When more results than the defined

maximum are available, then these are returned on additional, separate pages. Each response

contains a handle to the next page. For example, maxresults=5 returns a maximum of 5

results per page. If there were 8 results in total, the first page of five results indicates that

there is a second page with more results.

"metaInfo: { timestamp: 2012-05-10T15:10:06.227+0000 nextPageInformation: 2}"

pageinformation xs:string



A key which identifies the page to be returned when the response is separated into multiple

pages. Only relevant, if maxresults has been specified in a previous request and the

response to the request includes the information that there is another page, for example:


politicalview xs:string (3 bytes, ISO 3166-1-alpha-3)

Specify the political view. Available territories will be seen through the point of view of this

country. If this parameter is not specified the neutral international view is made available,

where territories may have unresolved claims.

For a complete list of supported views please see the appendix Political View.

For any political view that is unsupported the Geocoder falls back to the default view. For

example, politicalview=USA or politicalview=FRA does not impact a response in any

way.

postalcode xs:string, exact match

Postal code defined by the government of the country.

prox GeoProximityType, see also GeoProximityType on page 96

prox=lat,lon,radius

A type of SpatialFilter. A spatial filter limits the search for any other attributes on the

request. Proximity specifies a circle to search using a latitude, a longitude, and a radius

in meters. Search is similar to mapview. Matches from inside set area are ranked higher.




parsedRequest]




searchtext xs:string

searchtext contains free-form text containing address elements. You can specify the

searchtext parameter by itself, or you can specify it with other parameters to narrow your

search. For example, you can specify the state or country parameters along with a free-

form address in the searchtext field.

state xs:string, exact match

First subdivision level below the country. Specify state using full or abbreviated notation. A

country specific mapping is required, for example



• US: State

• Germany: Bundesland

street xs:string, fuzzy match

The street name can include suite, apt and floor information. When searching for a street

intersection two formats are supported:

• either using two parameters street0, street1, for example:

street0=McAllister+St&street1=Market+St

• or concatenating the two streets using one of the predefined separators ("and", "at",

"&", or "@"), for example:

street=McAllister+St+@+Market+St

strictlanguagemode xs:boolean

True - if the value is available in the first language specified in the language parameter

the attribute value is set directly in Address, Place, Location, and Category

elements. Values in alternative languages are returned in the AlternativeValues

element.

False - the best available attribute value based on the language priorities given in

language parameter is returned directly in Address, Place, Location, and Category

elements. No alternatives are returned.

token xs:string

An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token

is generated based on the user's app_id and received after the registration process of the

application.

Parameter token is deprecated, use app_code instead.

Reverse Geocode ResourceThis section contains a list of all Reverse Geocode request parameters.

.../6.2/reversegeocode.{format}?<parameter>=<value>...


Parameter Element






Parameter Element

Example:








app_id xs:string


application.



app_code xs:string


application.



gen xs:int






Default value is 0.








level xs:string


Parameter Element

Target match level of the search result. One of [country, state, county, city, district,

postalCode]. Only valid in combination with gen=2 or higher.


















maxresults xs:int








minresults xs:int

Ignore the specified radius until minResults results are found. Default is 0. Currently only

supported for Reverse Geocode mode=retrieveAreas.

mode One of five values:

retrieveAddresses - Search for the closest street address or addresses

retrieveAreas - Retrieve the administrative area information for the position provided

in the request


Parameter Element

retrieveLandmarks - Search for landmarks like parks and lakes in the proximity

provided in the request

retrieveAll - Search for streets, administrative areas and landmarks. This mode

aggregates the results of the three different modes in one call

trackPosition - Retrieve street and address information based on a position and

bearing













way.

pos pos=lat,lon,bearing

A position with latitude, longitude, and bearing. Bearing expresses the direction in which

an asset is heading in degrees starting at true north and continuing clockwise around the

compass. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees.


prox=lat,lon,radius


request. Proximity specifies a circle to search using a latitude, a longitude, and a radius in

meters.



parsedRequest]





Parameter Element

sortby xs:string

Sort results by distance (default), population count, or size (approximate area size). One of

[distance, population, size].

Currently only supported for Reverse Geocode mode=retrieveAreas. If population count is

not available for an entity the service falls back to sort by area size.





element.




token xs:string



application.


Multi Reverse Geocode ResourceThis section contains a list of all Multi Reverse Geocode request parameters. Multi Reverse Geocode

requests are POST requests.

.../6.2/multi-reversegeocode.{format}?<parameter>=<value>...


Parameter Element





Example:




Parameter Element






app_id xs:string


application.



app_code xs:string


application.



gen xs:int






Default value is 0.








level xs:string

Target match level of the search result. One of [country, state, county, city, district,

postalCode]. Only valid in combination with gen=2 or higher.



Parameter Element

















maxresults xs:int








minresults xs:int

Ignore the specified radius until minResults results are found. Default is 0. Currently only

supported for Reverse Geocode mode=retrieveAreas.

mode One of five values:

retrieveAddresses - Search for the closest street address or addresses

retrieveAreas - Retrieve the administrative area information for the position provided

in the request

retrieveLandmarks - Search for landmarks like parks and lakes in the proximity

provided in the request

retrieveAll - Search for streets, administrative areas and landmarks. This mode

aggregates the results of the three different modes in one call


Parameter Element

trackPosition - Retrieve street and address information based on a position and

bearing













way.



parsedRequest]




sortby xs:string

Sort results by distance (default), population count, or size (approximate area size). One of

[distance, population, size].

Currently only supported for Reverse Geocode mode=retrieveAreas. If population count is

not available for an entity the service falls back to sort by area size.





element.





Parameter Element

token xs:string



application.


Request Body

The HTTP Body in the POST request is used to specify the multiple reverse geocode request items.

Each line in the HTTP body represents one reverse geocode request. The parameters passed in the

query string serve as default values for any of those requests and can be overridden in the HTTP

body. The format for every line follows the same syntax as the URL query string:

name1=value1&name2=value2

Landmark Geocode ResourceThis section contains a list of all Landmark Geocode request parameters.

.../6.2/search.{format}?<parameter>=<value>...







Example:








app_id xs:string




application.



app_code xs:string


application.



bbox see also GeoBoundingBoxType on page 95

A type of Spatial Filter. A spatial filter limits the search for any other attributes in the

request. A bounding box bbox is specified by two latitude / longitude pairs; the first pair

defines the top left corner of the bounding box, the second set the lower right. The bbox

search is currently similar to mapview but it is not extended. Relevant global results are also

returned.

bbox=<TopLeft.Latitude>,<TopLeft.Longitude>; <BottomRight.Latitude>,<BottomRight.Longitude>

Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965

categoryids xs:integer

Limit landmark results to one or more categories. Examples:

• Highway exits: 116

• Airports: 4581

• Tourist attractions: 7999

city xs:string, fuzzy match

A country specific mapping is required. Example,

• USA: City

• Germany: Gemeinde

country xs:string, exact match

Specify the country or list of countries using the country code (3 bytes, ISO 3166-1-alpha-3)

or the country name. This is a strict filter. Results are restricted to the specified country or

countries.

Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO code

and not with the spelled out country name. With names there is a higher risk of misspells and

also not all language translations for all countries are supported.

countryfocus xs:string, exact match, single ISO 3166-1-alpha-3 country code

Results from the specified country are preferred. This is a soft filter. Spelled out country

names are not supported for country focus.



• If both hard country filter and soft country focus parameter are set in the request

the country filter takes precedence over the focus. This means results are limited to

countries specified with country filter.

• bbox or mapview filter take precedence over the country focus if there is a conflict.

county xs:string, fuzzy match

Second subdivision level below the country. Depending on the admin hierarchy in a country

this level might not be applicable. Example,

• USA: County

• Germany: Kreis

district xs:string, fuzzy match

Subdivision level below the city. Depending on the admin hierarchy in a country this level

might not be applicable. Example,

• USA: n/a

• Germany: Ortsteil

gen xs:int




housenumber xs:string, exact match

The house number or house name.



Default value is 0.



























locationid xs:string, exact match

A key uniquely identifying a physical location. Each record in a geocode response contains

a location Id. Use the Id to retrieve the exact same location information. For example, the

location Id for "1 Market Street, 94105 San Francisco" is NT_NVpegjQLOBQa8ORYk3jV7A_xA.

mapview See GeoBoundingBoxType on page 95

Specify the map coordinates of the app's viewport. The mapview is specified by two

latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the

second set the lower right. Matches from within the set map view plus an extended area are

ranked highest. Relevant global results are also returned.

mapview=<TopLeft.Latitude>,<TopLeft.Longitude>; <BottomRight.Latitude>,<BottomRight.Longitude>

Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965

maxresults xs:int








name xs:string

Name of the landmark. The landmark name can also be provided within the searchtext. Use

name instead of searchtext to avoid ambiguity for example with addresses.



Highway exits also fall into the landmark category but note that those consist of a highway

name and an exit name. Only the exit name should be provided in the name parameter. Below

are two ways how to search for exit 4 on highway A67:

• search.xml?searchtext=A67&name=4

• search.xml?searchtext=A67+4













way.

postalcode xs:string, exact match

Postal code defined by the government of the country.


prox=lat,lon,radius


request. Proximity specifies a circle to search using a latitude, a longitude, and a radius

in meters. Search is similar to mapview. Matches from inside set area are ranked higher.




parsedRequest]




searchtext xs:string



searchtext contains free-form text containing address elements. You can specify the

searchtext parameter by itself, or you can specify it with other parameters to narrow your

search. For example, you can specify the state or country parameters along with a free-

form address in the searchtext field.

state xs:string, exact match

First subdivision level below the country. Specify state using full or abbreviated notation. A

country specific mapping is required, for example

• US: State

• Germany: Bundesland

street xs:string, fuzzy match

The street name can include suite, apt and floor information. When searching for a street

intersection two formats are supported:

• either using two parameters street0, street1, for example:

street0=McAllister+St&street1=Market+St

• or concatenating the two streets using one of the predefined separators ("and", "at",

"&", or "@"), for example:

street=McAllister+St+@+Market+St





element.




token xs:string



application.


Additional Data ParameterList of KeyValuePairType elements as generic container to attach additional information to requests.


Table 9: 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.


Key Value

• 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.


Key Value

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.

Response Data TypesThis section provides reference to the data structures used throughout the Geocoder API.

Search ResponseThe 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.

Figure 1: Overview Response Types

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 10: Response elements

Type Description

MetaInfo Meta Information about the Request

View Search Results are grouped in Views.


MetaInfo (SearchResponseMetaInfoType)Table 11: 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 12: 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 13: 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.


Type Description

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


Type Description

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 14: 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 15: 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 16: 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.


Type Description

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


• 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 17: 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 18: Address elements

Element Definition

Label Assembled address value for displaying purposes.


Element Definition

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.


• "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.


Element Definition

• 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 19: 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


Element Definition

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 20: 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 21: 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.


Type Description

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 22: 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 requireauthorization on API level for all or individual attributes with future releases. Currently,only the SpeedLimit attribute requires authorization and the attribute is not included inLinkInfo if the client application is not authorized to receive this information.

Table 23: 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.


Type Description

SpeedCategory Classifies the general speed trend of a navigable link based on posted or legal speed. (see

SpeedCategoryType enumeration for possible values)

SpeedLimit Speed limit indicating the legal speed for a vehicle in each travel direction. If traffic is allowed in both

directions two speed limit values might be returned. Depending on the country the value is returned in

kph or mph. Speed limit is subject to additional licensing and the attribute is not included in the result if

the client application is not authorized to receive this information.

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 24: 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 25: 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.


Type Description

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 26: Related Location elements

Type Description

Type The type of the relationship to the associated location. The following types of related locations are

supported:



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

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.


Multi Reverse Geocode ResponseThe MultiSearchResponseType structure is the top level element returned by multi reverse geocode

requests. It contains Meta Information and one or more Items. Each item corresponds to one of the

items in the request, correlated by an ItemId. A response Item contains a list of Search Results,

which wrap the Location objects found for the request.

Figure 3: Overview Multi Search Response Types

Response (MultiSearchResponseType)Table 27: Response elements

Type Description

MetaInfo Meta Information about the Request

Item List of response items, each element wrapping the result of a corresponding input

item in the request.


MetaInfo (MultiSearchResponseMetaInfoType)Table 28: MetaInfo elements

Type Description

RequestId Mirrored RequestId value from the request structure.Used to trace requests.

Timestamp Time at which the search was performed.

AdditionalData List of KeyValuePairType elements as generic container to attach additional information to the

request.

Item (MultiSearchResponseItemType)Table 29: Item elements

Type Description

ItemId This element contains the key which was specified in the corresponding request item. If no ItemId

has been specified in the request the ItemId is constructed as the counter of the input items

starting with 0.

Result The resulting alternative items which have been found along with attributes indicating the quality

of the search result.

Base Data TypesBase Data Types used in the Search Response Structure.

LatitudeTypeLocation of a place on Earth north or south of the equator.

LatitudeType is an xs:double type with the following restrictions:

• Must satisfy: -90 ≤ value ≤ 90

• Unit: decimal degrees

• Reference System: WGS 84

• Precision: 7 positions after decimal point, additional positions are ignored

Examples

45.1234567


-12.3456789

45.123

LongitudeTypeLocation of a place on Earth east or west of the prime meridian.

LongitudeType is an xs:double type with the following restrictions:

• Must satisfy: -180 ≤ value ≤ 180

• Unit decimal degrees

• Reference System: WGS 84


Query Parameter Representation

Valid examples:

90.1234567

-120.3456789

90.123

DistanceTypeThis type can be used whenever distances need to be represented.

DistanceType is an xs:double type with the following restrictions:

• Unit: meters


Examples

45.1234

899344

DistanceUnitTypeUnit of measure used to describe distance values.

The following enumeration values are supported:


• mi: Miles

• km: Kilometers

HeadingTypeHeading in degrees starting at true North and continuing clockwise around the compass.

North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. This type can be

used whenever directions need to be represented.

HeadingType is a xs:double type with the following restrictions:

• Must satisfy: 0 ≤ value < 360

• Unit: decimal degrees

• Measured: clockwise starting at 0 degrees at true North


CardinalDirectionTypeEnumeration type representing the four cardinal (north, east, south, west) and the four ordinal (NE,

SE, SW, NW) directions.


• N: north

• E: east

• S: south

• W: west

• NE: northeast

• SE: southeast

• SW: southwest

• NW: northwest

CountryCodeTypeThis type is used whenever a country needs to be referenced.

CountryCodeParameterType is a xs:string type with the following restrictions:

• Format: Country code according to ISO 3166-1-alpha-3


Examples

DEU

GBR

SideOfStreetTypeValues to indicate on which side of a link an object is placed.

The following enumeration values are available for SideOfStreetType:

• left

• right

• neither

ShapeFormatTypeDefines identifiers for the supported shape representations.

The following enumeration values are available for ShapeFormatType:

• WKT

Identifier for Well-known text (WKT)

ReverseGeocodeModeTypeThe following enumeration values are available for ReverseGeocodeModeType:

• retrieveAddresses Search for the closest street address or addresses.

• retrieveAreas Retrieve the administrative area information for the position provided in therequest.

• retrieveLandmarks Search for landmarks like parks and lakes in the proximity provided in therequest.

• retrieveAll Search for streets, administrative areas and landmarks. This mode aggregates theresults of the three different modes in one call.

• trackPosition Retrieve street information based on a position and bearing.

If gen>=1 and a Reverse Geocode request with mode=retrieveAddresses does not find any

addresses, area information is returned instead. If gen=0, the empty result set is returned.

GeoCoordinateTypeThe GeoCoordinateType represents a geographical position.


The following attributes are defined:

• Latitude

WGS-84 / degrees with (-90 <= Latitude <= 90), precision is limited to 7 positions after the

decimal point

• Longitude

WGS-84 / degrees with (-180 <= Longitude <= 180) precision is limited to 7 positions after the

decimal point

• Altitude

Altitude in meters. Optional.

GeoBoundingBoxTypeA GeoBoundingBoxType defines a rectangular area in a geographic coordinate system. This type is

derived from the abstract base type GeoAreaType.

As the bounding box is specified by its top-left and bottom-right corner of the box, it is not

necessarily the smallest rectangle spanned by these two points; it is possible to define bounding

boxes that are wider than 180° or higher than 90° (for example, by setting the longitude of top-left

corner to a bigger value than the longitude of the bottom-right corner).

A bounding box with longitude of -180° for the top-left corner and a longitude of 180° for the

bottom-right corner constructs an area that encircles the globe whereas a bounding box with the

same longitude values for both corners constructs a bounding box of width 0°.

The GeoBoundingBoxType has the following attributes:

• TopLeft

Top-left corner of the rectangular area.

◦ Latitude

WGS-84 / degrees with (-90 <= Latitude <=90)

◦ Longitude

WGS-84 / degrees with (-180 <= Longitude <=180)

◦ Altitude

Altitude in meters (optional)

• BottomRight

Bottom-right corner of the rectangular area.

◦ Latitude



◦ Longitude


◦ Altitude

Altitude in meters (optional)


A BoundingBoxType is represented in a compact format if used as query parameter:

<TopLeft.Latitude> + "," + <TopLeft.Longitude> + ";" + <BottomRight.Latitude> + "," + <BottomRight.Longitude>

Example:

bbox=37.7902858,-122.4027371;37.7890649,-122.3993039

GeoProximityTypeA GeoProximityType represents a circular area. This type is derived from the abstract base type

GeoAreaType.

The ProximityType has the following attributes:

• Center

Center of the circular area.

◦ Latitude


◦ Longitude


◦ Altitude

Currently unused

• Radius

Radius in meters



The GeoProximityType can be represented in query strings as follows:

<Latitude> + "," + <Longitude> (+ "," + <Radius>)?

If possible, i.e. if there is no risk of name clashes, the preferred name for the parameter of a

ProximityType element is "prox".

Example: prox=37.7890649,-122.4027371,1000

GeoPositionTypeA GeoPositionType represents a snapshot of positioning information. This information is usually

provided by a GPS device.

The GeoPositionType has the following attributes:

• Coordinate

Position in WGS-84 coordinate system

• Heading

Direction of travel in degrees starting at true North and continuing clockwise around the

compass. The heading information is optional.


The GeoPositionType can be represented in query strings as follows:

<Latitude> + "," + <Longitude> (+ "," + <Heading>)?

Example: pos=37.7890649,-122.4027371,271.4

GeoShapeTypeAbstract base class for different shape representations. A shape is a vector geometry object which

resides on a map. Please check the enumeration type ShapeFormatType for a list of supported

representations.


WKTShapeTypeWKTShapeType is an extension of the abstract type GeoShapeType supporting a shape

representation based on Well-known text (WKT) as markup language. See http://en.wikipedia.org/wiki/

Well-known_text for more details.

WKTShapeType defines the following attributes:

Value String value containing the WKT representation.

Example:

POLYGON ((8.694859999000073 50.11352, 8.69483557600006 50.11347330600006, 8.694840580000061 50.11346496600004, 8.694919999000092 50.11342, 8.694895537000093 50.11337503400006, 8.694817765000039 50.11337503400006, 8.694719999000085 50.11342, 8.69470104000004 50.113373025000044, 8.694515205000073 50.11335532600003, 8.694226143000037 50.113315456000066, 8.694224789000089 50.11331529000006, 8.694107760000065 50.11330275100005, 8.693939999000065 50.113329999000086, 8.694859999000073 50.11352))

KeyValuePairTypeThis type is a generic container for arbitrary information. Key/value pairs are supported to transport

non-typed generic information which has not currently been defined in API data structures.

The following attributes are defined:

• Key

Name of the property

The value is included directly in the body of the element.


A KeyValuePair can be represented in query strings as follows:

<Key> + "," + <Value>

Note: Representation formats: Special characters need to be URL-encoded.

LocalizedNameTypeA LocalizedNameType enriches a name with the corresponding language information. It defines the

following attributes:

• Value

http://en.wikipedia.org/wiki/Well-known_text

http://en.wikipedia.org/wiki/Well-known_text


Text representation of the name

• Language

Language information for the name (RFC 5646 Language Tag)

FunctionalClassTypeThe functional class is used to classify roads depending on the speed, importance and connectivity of

the road. It is an xs:byte type with the following restrictions:

• Must satisfy: 1 ≤ value < 5

The value represents one of the five levels:

• 1: allowing for high volume, maximum speed traffic movement

• 2: allowing for high volume, high speed traffic movement

• 3: providing a high volume of traffic movement

• 4: providing for a high volume of traffic movement at moderate speeds between neighbourhoods

• 5: roads whose volume and traffic movement are below the level of any functional class

SpeedCategoryTypeSpeed Category classifies the general speed trend of a road based on posted or implied speed limit.

Speed Category values represent the combination of several factors besides legal speed limit (e.g.

physical restriction or access characteristics). Therefore, Speed Category values can differ from

Speed Limit values, which represent the legal speed limits only.

The enumeration values SC1 - SC8 represent the following speed ranges:

Table 30: Speed Categories

Speed Category Speed range in km/h Speed range in MPH

SC1 >130 km/h >80 MPH

SC2 101-130 km/h 65-80 MPH

SC3 91-100 km/h 55-64 MPH

SC4 71-90 km/h 41-54 MPH

SC5 51-70 km/h 31-40 MPH

SC6 31-50 km/h 21-30 MPH

SC7 11-30 km/h 6-20 MPH

SC8 <11 km/h <6 MPH


SpeedLimitTypeSpeed limits indicate the legal speed for a vehicle. Depending on the country the values are given in

mph or kph.

A speed limit has the following attributes:

• Value

Value of the speed limit. Range: 1 - 999

For roads that allow an unlimited speed, the speed limit value is 999.

A value of 998 is applied to ramps if there is neither a posted speed limit nor a legal speed limit.

• Unit

Unit for the speed limit. The following enum values are supported:

◦ mph

miles per hour (mi/h)

◦ kph

kilometers per hour (km/h)

LinkFlagTypeValues to describe special characteristics of a link.

The following enumeration values are available for LinkFlagType:

• ControlledAccess

Identifies roads with limited entrances and exits that allow uninterrupted high speed traffic flow.

• MultiDigitized

Indicates if the navigable link is part of a road network where each driving direction is separately

digitized.

• Frontage

Indication if the navigable link is a frontage road. Frontage roads are local roads that run parallel

to and usually contain the name(s) and addresses of a road with a higher traffic flow.

• Paved

Indication if the navigable link is paved.

• Ramp


Indication if the navigable link represents a Ramp. Ramps are connectors that provide access

between roads that do not cross at grade.

• Private

Identifies roads not maintained by an organization responsible for maintenance of public roads.

• Tollway

Identifies a navigable link for which a fee must be paid to use the road.

• PoiAccess

Indication if a navigable link is a POI Access Road. POI Access Roads connect Points of Interest

(POIs) to the road network. These roads provide the only means of entrance or exit from a POI to

a public road.

• FourWheelDrive

Indicates roads which are only suitable for vehicles with four-wheel drive.

• ParkingLotRoad

Indication if a Link is internal to a parking lot area.

• CarpoolRoad

Identifies a Link where, at specific times, all lanes serve as Carpool lane.

• Reversible

Indicates that a Link is fully reversible, which implies that traffic changes direction for a specific

time frame.

• ExpressLane

Indication if the link serves as an Express Lane.

LinkAccessFlagTypeDefines a list of access characteristics for a link.

The following enumeration values are available for LinkAccessFlagType:

• Automobiles

• Buses

• Taxis

• Carpools

• Pedestrians

• Trucks

• Deliveries

• EmergencyVehicle

• ThroughTraffic


• Motorcycles

RelationshipEnumTypeEnumeration type for the relationship roles that a related location can assume.




• nearByAddress

Location of a nearby address on the same link.

UTCTimeOffsetTypeUTC time offset showing the difference in hours and minutes from Coordinated Universal Time (UTC),

from the westernmost (UTC-12:00) to the easternmost (UTC+14:00).

Examples

UTC-12:00UTC-06:00UTC±00:00UTC+01:00UTC+04:30

CurrencyType3-letter code abbreviation for a currency according to ISO 4217

Examples

EURUSDRUB

DrivingSideTypeDriving side for road traffic

• left: left-hand traffic

• right: right-hand traffic


SystemOfMeasurementTypeA system of measurement represents a set of units of measurement used to specify distance, speed,

volume, etc. information

• imperial: System using imperial units like miles, gallons, etc.

• metric: System using metric units like meters, liters, etc.

Response Schemas and ExamplesThis chapter provides references to the XML schema locations for all endpoints and examples of

complete service responses in XML format.

XML Schemas

XML Schema for geocode, reversegeocode, and search results

Schema location https://geocoder.api.here.com/6.2/xsd/LBSP-Search-Search.xsd

XSD Version 4.3

XML Schema for endpoint multi-reversegeocode results

Schema location https://geocoder.api.here.com/6.2/xsd/LBSP-Search-MultiSearch.xsd

XSD Version 1.0

Response Examples

Example Geocode Response

For explanations of each element in the XML response, see Search Response on page 74

<Response> <MetaInfo> <Timestamp>2015-09-15T06:10:48.562Z</Timestamp> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>1.0</Relevance> <MatchLevel>houseNumber</MatchLevel>


<MatchQuality> <City>1.0</City> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber> </MatchQuality> <MatchType>pointAddress</MatchType> <Location> <LocationId>NT_Opil2LPZVRLZjlWNLJQuWB_0ITN</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>41.8843193</Latitude> <Longitude>-87.6387711</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>41.884491</Latitude> <Longitude>-87.6387711</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>41.8854435</Latitude> <Longitude>-87.640281</Longitude> </TopLeft> <BottomRight> <Latitude>41.8831952</Latitude> <Longitude>-87.6372611</Longitude> </BottomRight> </MapView> <Address> <Label> 425 W Randolph St, Chicago, IL 60606, United States </Label> <Country>USA</Country> <State>IL</State> <County>Cook</County> <City>Chicago</City> <District>West Loop</District> <Street>W Randolph St</Street> <HouseNumber>425</HouseNumber> <PostalCode>60606</PostalCode> <AdditionalData key="CountryName">United States</AdditionalData> <AdditionalData key="StateName">Illinois</AdditionalData> <AdditionalData key="CountyName">Cook</AdditionalData> <AdditionalData key="PostalCodeType">N</AdditionalData> </Address> </Location> </Result> </View></Response>

Example Reverse Geocode Response


<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-09-15T06:34:14.645Z</Timestamp> <NextPageInformation>2</NextPageInformation> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>1.0</Relevance> <Distance>0.7</Distance>


<MatchLevel>houseNumber</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber> <PostalCode>1.0</PostalCode> </MatchQuality> <MatchType>pointAddress</MatchType> <Location> <LocationId>NT_OV3A4F7PVZMW36XQixpFiB_zAD</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>50.1123</Latitude> <Longitude>8.68285</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>50.112</Latitude> <Longitude>8.68301</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>50.1134242</Latitude> <Longitude>8.681097</Longitude> </TopLeft> <BottomRight> <Latitude>50.1111758</Latitude> <Longitude>8.684603</Longitude> </BottomRight> </MapView> <Address> <Label>Berliner Straße 30, 60311 Frankfurt am Main, Deutschland</Label> <Country>DEU</Country> <State>Hessen</State> <County>Frankfurt am Main</County> <City>Frankfurt am Main</City> <District>Altstadt</District> <Street>Berliner Straße</Street> <HouseNumber>30</HouseNumber> <PostalCode>60311</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Hessen</AdditionalData> <AdditionalData key="CountyName">Frankfurt am Main</AdditionalData> </Address> <MapReference> <ReferenceId>52308768</ReferenceId> <MapId>UWAM15124</MapId> <MapVersion>Q1/2015</MapVersion> <Spot>0.86</Spot> <SideOfStreet>left</SideOfStreet> <CountryId>20147700</CountryId> <StateId>20160993</StateId> <CountyId>20161002</CountyId> <CityId>20161003</CityId> <DistrictId>20299860</DistrictId> <AddressId>168611036</AddressId> </MapReference> </Location> </Result> </View> </Response></ns2:Search>


Example Multi Reverse Response

For explanations of each element in the XML response, see Multi Reverse Geocode Response on

page 90

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:MultiSearch> <Response> <MetaInfo> <Timestamp>2015-09-15T06:34:14.645Z</Timestamp> </MetaInfo> <Item> <ItemId>1</ItemId> <Result> <Relevance>1.0</Relevance> <Distance>0.1</Distance> <MatchLevel>houseNumber</MatchLevel> <MatchQuality> <Country>1.0</Country> <State>1.0</State> <County>1.0</County> <City>1.0</City> <District>1.0</District> <Street>1.0</Street> <HouseNumber>1.0</HouseNumber> <PostalCode>1.0</PostalCode> </MatchQuality> <MatchType>pointAddress</MatchType> <Location> <LocationId>NT_5v-U9-t5AZa5VsRdV06lLB_xEjN</LocationId> <LocationType>address</LocationType> <DisplayPosition> <Latitude>52.53086</Latitude> <Longitude>13.38469</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>52.53098</Latitude> <Longitude>13.38458</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>52.5319842</Latitude> <Longitude>13.3828421</Longitude> </TopLeft> <BottomRight> <Latitude>52.5297358</Latitude> <Longitude>13.3865379</Longitude> </BottomRight> </MapView> <Address> <Label>Invalidenstraße 116, 10115 Berlin, Deutschland</Label> <Country>DEU</Country> <State>Berlin</State> <County>Berlin</County> <City>Berlin</City> <District>Mitte</District> <Street>Invalidenstraße</Street> <HouseNumber>116</HouseNumber> <PostalCode>10115</PostalCode> <AdditionalData key="CountryName">Deutschland</AdditionalData> <AdditionalData key="StateName">Berlin</AdditionalData> <AdditionalData key="CountyName">Berlin</AdditionalData> </Address> </Location> </Result> </Item> <Item>


<ItemId>2</ItemId> <Result> ... </Result> </Item> ... </Response></ns2:MultiSearch>

Example Landmark Geocode Response


<?xml version="1.0" encoding="utf-8" standalone="yes"?><ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4"> <Response> <MetaInfo> <Timestamp>2015-09-15T06:31:18.202Z</Timestamp> </MetaInfo> <View xsi:type="ns2:SearchResultsViewType"> <ViewId>0</ViewId> <Result> <Relevance>1.0</Relevance> <MatchLevel>landmark</MatchLevel> <MatchQuality> <Name>1.0</Name> </MatchQuality> <Location> <LocationId>NT_AIzytxewh0cMjfGkhX4O.B</LocationId> <LocationType>historicalMonument</LocationType> <Name>Tour Eiffel</Name> <DisplayPosition> <Latitude>48.85824</Latitude> <Longitude>2.2945</Longitude> </DisplayPosition> <NavigationPosition> <Latitude>48.85863</Latitude> <Longitude>2.29397</Longitude> </NavigationPosition> <MapView> <TopLeft> <Latitude>48.87173</Latitude> <Longitude>2.274</Longitude> </TopLeft> <BottomRight> <Latitude>48.84475</Latitude> <Longitude>2.315</Longitude> </BottomRight> </MapView> <Address> <Label>75007 Paris, France</Label> <Country>FRA</Country> <State>Île-de-France</State> <County>Paris</County> <City>Paris</City> <District>7e Arrondissement</District> <PostalCode>75007</PostalCode> <AdditionalData key="CountryName">France</AdditionalData> <AdditionalData key="StateName">Île-de-France</AdditionalData> <AdditionalData key="CountyName">Paris</AdditionalData> </Address> </Location> </Result> </View> </Response>


</ns2:Search>

Geocoder API Developer's Guide 109► Coverage Information

Chapter

5

Coverage InformationTopics:

• Geocoder Coverage

• Political Views

This appendix contains additional information about Geocoder API.


Geocoder CoverageThe table below lists the types of coverage available for the Geocoder API by administrative area.

To see the differences between different coverage levels, try entering geocoordinates for different

countries in the API Explorer. For example, a GET request with a location on the Åland Islands, an area

which has full coverage, retrieves a more elaborate response than the same kind of request based on

a location in Jelalabad, Afghanistan, which has only entry map coverage.

For more information about some of the columns in the table below, see Coverage Categories on

page 125.

The Geocoder API provides weekly map updates based on the map data releases specified per

country in the table below.

Table 31: API Coverage

Country/Area ISOA3

ISOA2

Coverage Level Map Release Map DataClassification

Local-izedAddressLabels

PointAd-dresses

PostalCodeBound-aries

PostalCodes

PostalCodeFormat

Afghanistan AFG AF major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NNNN

Albania ALB AL full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNN

Algeria DZA DZ selected streets,

cities, country

2015 Q1 Intermediate

Map Content

n/a n/a n/a n/a NNNNN

American

Samoa

ASM AS major cities,

country

2016 Q2 Entry Map

Content


(optionally

NNNNN-

NNNN or

NNNNN-

NNNNNN)

Andorra AND AD full: house no,

street level

2016 Q2 HERE Map

Content

(Included in

France map

product)

Y n/a Y Y ADNNN

Angola AGO AO selected streets,

cities, country


Map Content

n/a n/a n/a no codes

are used

Anguilla AIA AI major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a AI-2640

https://developer.here.com/api-explorer


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Antarctica ATA AQ major cities,

country

2016 Q1 Entry Map

Content


are used

Antigua and

Barbuda

ATG AG major cities,

country

2016 Q2 Entry Map

Content


are used

Argentina ARG AR full: premium house

no., street level

2016 Q2 HERE Map

Content

Y n/a n/a Y NNNN

Armenia ARM AM major cities,

country

2016 Q2 Entry Map

Content

Y n/a n/a n/a NNNN

Aruba ABW AW selected streets,

cities, country


Map Content


are used

Australia AUS AU full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Austria AUT AT full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Azerbaijan AZE AZ full: premium house

no., street level


Map Content

Y Y n/a n/a CCNNNN

Bahamas BHS BS full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a no codes

are used

Bahrain BHR BH full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNN or

NNNN

Bangladesh BGD BD selected streets,

cities, country


Map Content


Barbados BRB BB selected streets,

cities, country


Map Content

n/a n/a n/a n/a CCNNNNN

Belarus BLR BY selected streets,

cities, country

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNNNN

Belgium BEL BE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Belize BLZ BZ selected streets,

cities, country


Map Content


are used

Benin BEN BJ major cities,

country

2016 Q2 Entry Map

Content


are used

Bermuda BMU BM selected streets,

cities, country


Map Content

n/a n/a n/a n/a AA

Bhutan BTN BT major cities,

country

2016 Q2 Entry Map

Content


Bolivia BOL BO selected streets,

cities, country


Map Content



Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Bonaire, Sint

Eustatius and

Saba

BES BQ major cities,

country

2016 Q2 Entry Map

Content


are used

Bosnia and

Herzegovina

BIH BA full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Botswana BWA BW full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a no codes

are used

Brazil BRA BR full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNN

(NNNNN-

NNN)

Brunei

Darussalam

BRN BN full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a AANNNN

Bulgaria BGR BG full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Burkina Faso BFA BF major cities,

country

2016 Q2 Entry Map

Content


are used

Burundi BDI BI selected streets,

cities, country


Map Content


are used

Cambodia KHM KH selected streets,

cities, country

2016 Q2 HERE Map

Content


Cameroon CMR CM major cities,

country

2016 Q2 Entry Map

Content


are used

Canada CAN CA full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y ANA NAN

Cape Verde CPV CV major cities,

country

2016 Q2 Entry Map

Content


Cayman

Islands

CYM KY full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a Y CCN-

NNNN

Central

African

Republic

CAF CF major cities,

country

2016 Q2 Entry Map

Content


are used

Chad TCD TD major cities,

country

2016 Q2 Entry Map

Content


Chile CHL CL full: premium house

no., street level

2016 Q2 HERE Map

Content

Y n/a n/a Y NNNNNNN

(NNN-

NNNN)

China (China

spec, only

CHN CN full: premium house

no., street level

2014 Q4 HERE Map

Content

(China Nav2)

Y Y n/a Y NNNNNN


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

available

inside China)

China

(Outside

China and

self-hosting

spec)

CHN CN major cities,

country

2014 Q4 Entry Map

Content

n/a n/a n/a Y NNNNNN

Colombia COL CO full: house no,

street level

2016 Q2 HERE Map

Content

Y Y n/a n/a NNNNNN

Comoros COM KM major cities,

country

2016 Q2 Entry Map

Content


are used

Congo COG CG major cities,

country

2016 Q2 Entry Map

Content


are used

Congo, The

Democratic

Republic of

The

COD CD major cities,

country

2016 Q2 Entry Map

Content


are used

Cook Islands COK CK major cities,

country

2016 Q2 Entry Map

Content


are used

Costa Rica CRI CR full: house no,

street level

2016 Q2 HERE Map

Content

n/a n/a n/a Y NNNNN

(NNNN

until

2007)

Cote D'Ivoire CIV CI full: house no,

street level

2016 Q2 HERE Map

Content


are used

Croatia HRV HR full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Cuba CUB CU selected streets,

cities, country


Map Content


Curacao CUW CW major cities,

country

2016 Q2 Entry Map

Content


are used

Cyprus CYP CY major cities,

country

2016 Q2 Entry Map

Content


Czech

Republic

CZE CZ full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

(NNN

NN)

Denmark DNK DK full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Djibouti DJI DJ major cities,

country

2016 Q2 Entry Map

Content


are used


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Dominica DMA DM major cities,

country

2016 Q2 Entry Map

Content


are used

Dominican

Republic

DOM DO selected streets,

cities, country


Map Content

n/a n/a n/a Y NNNNN

Ecuador ECU EC selected streets,

cities, country


Map Content

n/a n/a n/a n/a NNNNNN

Egypt EGY EG full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a n/a NNNNN

El Salvador SLV SV selected streets,

cities, country


Map Content

n/a n/a n/a n/a 1101

Equatorial

Guinea

GNQ GQ major cities,

country

2016 Q2 Entry Map

Content


are used

Eritrea ERI ER major cities,

country

2016 Q2 Entry Map

Content


are used

Estonia EST EE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Ethiopia ETH ET major cities,

country

2016 Q2 Entry Map

Content


Falkland

Islands

(Malvinas)

FLK FK major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a AAAANAA

one

code:

FIQQ

1ZZ

Faroe Islands FRO FO major cities,

country

2016 Q2 Entry Map

Content

Y Y n/a n/a NNN

Fiji FJI FJ major cities,

country

2016 Q2 Entry Map

Content


are used

Finland FIN FI full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

France FRA FR full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

French Guiana GUF GF full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a Y 973NN

French

Polynesia

PYF PF major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a 987NN

Gabon GAB GA major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NN [city

name]

NN


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Gambia GMB GM major cities,

country

2016 Q2 Entry Map

Content


are used

Georgia GEO GE major cities,

country

2016 Q2 Entry Map

Content

Y n/a n/a n/a NNNN

Germany DEU DE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Ghana GHA GH selected streets,

cities, country


Map Content


are used

Gibraltar GIB GI full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a n/a GX11

1AA

Greece GRC GR full: house no,

street level

2016 Q2 HERE Map

Content

Y Y Y Y NNN NN

Greenland GRL GL major cities,

country

2016 Q2 Entry Map

Content


Grenada GRD GD major cities,

country

2016 Q2 Entry Map

Content


are used

Guadeloupe GLP GP full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a Y 971NN

Guam GUM GU major cities,

country

2016 Q2 Entry Map

Content


Guatemala GTM GT selected streets,

cities, country


Map Content


Guernsey GGY GG full: house no,

street level

2016 Q2 HERE Map

Content

(Included

in UK map

product)

Y n/a n/a Y AAN

NAA,

AANN

NAA

Guinea GIN GN major cities,

country

2016 Q2 Entry Map

Content


are used

Guinea-Bissau GNB GW major cities,

country

2016 Q2 Entry Map

Content


Guyana GUY GY selected streets,

cities, country


Map Content


are used

Haiti HTI HT major cities,

country

2016 Q2 Entry Map

Content


Honduras HND HN selected streets,

cities, country


Map Content



Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Hong Kong HKG HK full: premium house

no., street level

2015 Q3 HERE Map

Content

Y Y n/a no codes

are used

Hong Kong

(self-hosting

spec)

HKG HK full: premium house

no., street level

2015 Q3 HERE Map

Content

Y Y n/a no codes

are used

Hungary HUN HU full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Iceland ISL IS full: house no,

street level

2016 Q2 HERE Map

Content

Y Y Y Y NNN

India IND IN full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNNN,

Indonesia IDN ID full: premium house

no., street level

2016 Q1 HERE Map

Content

Y Y n/a Y NNNNN

Iran (Islamic

Republic of)

IRN IR major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NNNNN-

NNNNN

Iraq IRQ IQ selected streets,

cities, country


Map Content


Ireland IRL IE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y no codes

are used

Isle of Man IMN IM full: house no,

street level

2016 Q2 HERE Map

Content

(Included

in UK map

product)

Y n/a n/a Y CCN

NAA,

CCNN

NAA

Israel ISR IL full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y Y Y NNNNNNN

Italy ITA IT full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Jamaica JAM JM selected streets,

cities, country


Map Content

n/a n/a n/a Y Before

suspension:

CCAAANN

Japan JPN JP major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NNNNNNN

(NNN-

NNNN)

Jersey JEY JE full: house no,

street level

2016 Q2 HERE Map

Content

(Included

in UK map

product)

Y n/a n/a Y CCN NAA


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Jordan JOR JO full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a no codes

are used

NNNNN

- only

for post

boxes

Kazakhstan KAZ KZ full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a Y NNNNNN

Kenya KEN KE full: house no,

street level

2016 Q2 HERE Map

Content


are used

NNNNN

- only

for post

boxes

Kiribati KIR KI major cities,

country

2016 Q2 Entry Map

Content


are used

Korea,

Democratic

People's

Republic of

PRK KP major cities,

country

2016 Q2 Entry Map

Content


are used

Korea,

Republic of

KOR KR major cities,

country

2016 Q2 Entry Map

Content


(NNN-

NNN)

(1988~2015)

Kosovo KOS KX full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNNN

Kuwait KWT KW full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNNN

Kyrgyzstan KGZ KG selected streets,

cities, country


Map Content


Lao People's

Democratic

Republic

LAO LA major cities,

country

2016 Q2 Entry Map

Content


Latvia LVA LV full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y CC-

NNNN

Lebanon LBN LB full: house no,

street level

2016 Q2 HERE Map

Content


NNNN

Lesotho LSO LS full: house no,

street level

2016 Q2 HERE Map

Content

n/a n/a n/a Y NNN

Liberia LBR LR major cities,

country

2016 Q2 Entry Map

Content


Libyan Arab

Jamahiriya

LBY LY selected streets,

cities, country


Map Content



Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Liechtenstein LIE LI full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Lithuania LTU LT full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y CC-

NNNNN

Luxembourg LUX LU full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Macau MAC MO full: premium house

no., street level

2015 Q3 HERE Map

Content

Y Y n/a no codes

are used

Macau (self-

hosting spec)

MAC MO full: premium house

no., street level

2015 Q3 HERE Map

Content

Y Y n/a no codes

are used

Macedonia,

The Former

Yugoslav

Republic of

MKD MK full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a n/a NNNN

Madagascar MDG MG major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NNN

Malawi MWI MW selected streets,

cities, country


Map Content


are used

Malaysia MYS MY full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNN

Maldives MDV MV selected streets,

cities, country


Map Content

n/a n/a n/a n/a NNNN,

NNNNN

Mali MLI ML major cities,

country

2016 Q2 Entry Map

Content


are used

Malta MLT MT full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y AAANNNN

(AAA

NNNN)

Marshall

Islands

MHL MH major cities,

country

2016 Q2 Entry Map

Content


Martinique MTQ MQ full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a Y NNNNN

Mauritania MRT MR major cities,

country

2016 Q2 Entry Map

Content


are used

Mauritius MUS MU major cities,

country

2016 Q2 Entry Map

Content


Mayotte MYT YT full: house no,

street level

2016 Q2 HERE Map

Content



Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Mexico MEX MX full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Micronesia,

Federated

States of

FSM FM major cities,

country

2016 Q2 Entry Map

Content


or

NNNNN-

NNNN

Moldova,

Republic of

MDA MD selected streets,

cities, country

2016 Q2 HERE Map

Content

Y n/a n/a n/a CCNNNN

(CC-

NNNN)

Monaco MCO MC full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Mongolia MNG MN selected streets,

cities, country

2016 Q2 HERE Map

Content


Montenegro MNE ME full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a Y Y NNNNN

Montserrat MSR MS major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a MSR

1110-1350

Morocco MAR MA full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNNN

Mozambique MOZ MZ full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNN

Myanmar MMR MM major cities,

country

2016 Q2 Entry Map

Content


Namibia NAM NA full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a n/a NNNNN

Nauru NRU NR major cities,

country

2016 Q2 Entry Map

Content


are used

Nepal NPL NP selected streets,

cities, country


Map Content


Netherlands NLD NL full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

New

Caledonia

NCL NC major cities,

country

2016 Q2 Entry Map

Content


New Zealand NZL NZ full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Nicaragua NIC NI selected streets,

cities, country


Map Content



Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Niger NER NE major cities,

country

2016 Q2 Entry Map

Content


Nigeria NGA NG selected streets,

cities, country


Map Content

Y n/a n/a n/a NNNNNN

Niue NIU NU major cities,

country

2016 Q2 Entry Map

Content


are used

Norfolk Island NFK NF full: house no,

street level

2016 Q2 HERE Map

Content

(Included in

Australia map

product)

Y n/a Y Y NNNN

Northern

Mariana

Islands

MNP MP major cities,

country

2016 Q2 Entry Map

Content


Norway NOR NO full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Oman OMN OM full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a no codes

are used

NNN -

only for

post

boxes

Pakistan PAK PK major cities,

country

2013 Q1 Entry Map

Content


Palau PLW PW major cities,

country

2016 Q2 Entry Map

Content


Palestinian

Territory,

Occupied

PSE PS selected streets,

cities, country

2016 Q2 HERE Map

Content

n/a n/a n/a n/a NNN

Panama PAN PA full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a n/a NNNNNN

Papua New

Guinea

PNG PG major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a NNN

Paraguay PRY PY selected streets,

cities, country


Map Content


Peru PER PE full: house no,

street level

2016 Q2 HERE Map

Content

n/a n/a n/a Y NNNNN

Philippines PHL PH full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a n/a NNNN

Pitcairn PCN PN major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a AAAANAA

one

code:


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

PCRN

1ZZ

Poland POL PL full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

(NN-

NNN)

Portugal PRT PT full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Puerto Rico PRI PR full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y Y Y NNNNN

Qatar QAT QA full: house no,

street level

2016 Q2 HERE Map

Content

Y Y n/a no codes

are used

Reunion REU RE full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a Y 974NN

Romania ROU RO full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNNN

Russian

Federation

RUS RU full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNNN

Rwanda RWA RW full: house no,

street level

2016 Q2 HERE Map

Content


are used

Saint

Barth#lemy

BLM BL full: house no,

street level

2016 Q2 HERE Map

Content

n/a n/a n/a Y 97133

Saint Helena SHN SH major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a STHL

1ZZ or

TDCU

1ZZ

Saint Kitts

and Nevis

KNA KN selected streets,

cities, country


Map Content


are used

Saint Lucia LCA LC major cities,

country

2016 Q2 Entry Map

Content


are used

Saint Martin MAF MF major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a 97150

Saint Pierre

and Miquelon

SPM PM major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a 97500

Saint Vincent

and The

Grenadines

VCT VC selected streets,

cities, country


Map Content

n/a n/a n/a n/a CCNNNN

Samoa WSM WS major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

San Marino SMR SM full: house no,

street level

2016 Q2 HERE Map

Content

(Included in

Italy map

product)

Y Y Y Y 4789N

Sao Tome and

Principe

STP ST major cities,

country

2016 Q2 Entry Map

Content


are used

Saudi Arabia SAU SA full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNN

for PO

Boxes.

NNNNN-

NNNN

for

home

delivery.

Senegal SEN SN major cities,

country

2016 Q2 Entry Map

Content


Serbia SRB RS full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Seychelles SYC SC major cities,

country

2016 Q2 Entry Map

Content


are used

Sierra Leone SLE SL major cities,

country

2016 Q2 Entry Map

Content


are used

Singapore SGP SG full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNNN

Sint Maarten SXM SX major cities,

country

2016 Q2 Entry Map

Content


are used

Slovakia SVK SK full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

(NNN

NN)

Slovenia SVN SI full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

(CC-

NNNN)

Solomon

Islands

SLB SB major cities,

country

2016 Q2 Entry Map

Content


are used

Somalia SOM SO major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a AA

South Africa ZAF ZA full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

South Sudan SSD SS major cities,

country

2015 Q1 Entry Map

Content

n/a n/a n/a n/a

Spain ESP ES full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Sri Lanka LKA LK selected streets,

cities, country


Map Content


Sudan SDN SD selected streets,

cities, country


Map Content


Suriname SUR SR selected streets,

cities, country


Map Content


are used

Svalbard and

Jan Mayen

Islands

SJM SJ major cities,

country

2016 Q2 Entry Map

Content


Swaziland SWZ SZ full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a n/a Y ANNN

Sweden SWE SE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

(NNN

NN)

Switzerland CHE CH full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNN

Syrian Arab

Republic

SYR SY selected streets,

cities, country


Map Content


are used

Taiwan TWN TW full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Tajikistan TJK TJ major cities,

country

2016 Q2 Entry Map

Content


Tanzania,

United

Republic of

TZA TZ selected streets,

cities, country


Map Content


are used

Thailand THA TH full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a Y NNNNN

Timor-Leste TLS TL major cities,

country

2016 Q2 Entry Map

Content


are used

Togo TGO TG major cities,

country

2016 Q2 Entry Map

Content


are used

Tokelau TKL TK major cities,

country

2016 Q2 Entry Map

Content


are used


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Tonga TON TO major cities,

country

2016 Q2 Entry Map

Content


are used

Trinidad and

Tobago

TTO TT selected streets,

cities, country


Map Content


Tunisia TUN TN selected streets,

cities, country


Map Content


Turkey TUR TR full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

Turkmenistan TKM TM major cities,

country

2016 Q2 Entry Map

Content


Turks and

Caicos Islands

TCA TC major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a TKCA

1ZZ

Tuvalu TUV TV major cities,

country

2016 Q2 Entry Map

Content


are used

Uganda UGA UG selected streets,

cities, country


Map Content


are used

Ukraine UKR UA full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a n/a NNNNN

United Arab

Emirates

ARE AE full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y n/a no codes

are used

United

Kingdom

GBR GB full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y A[A]N[A/

N]

United States USA US full: premium house

no., street level

2016 Q2 HERE Map

Content

Y Y Y Y NNNNN

(optionally

NNNNN-

NNNN)

Uruguay URY UY full: house no,

street level

2016 Q2 HERE Map

Content

n/a Y n/a Y NNNNN

Uzbekistan UZB UZ selected streets,

cities, country


Map Content

n/a n/a n/a n/a NNN

NNN

Vanuatu VUT VU major cities,

country

2016 Q2 Entry Map

Content


are used

Vatican City

State (Holy

See)

VAT VA full: house no,

street level

2016 Q2 HERE Map

Content

(Included in

Italy map

product)

n/a n/a Y Y 120

Venezuela VEN VE full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a n/a NNNN or

NNNN A


Country/Area ISOA3

ISOA2



PointAd-dresses


PostalCodes

PostalCodeFormat

Vietnam VNM VN full: premium house

no., street level

2016 Q2 HERE Map

Content

n/a Y n/a n/a NNNNNN

Virgin Islands

(British)

VGB VG major cities,

country

2016 Q2 Entry Map

Content

n/a n/a n/a n/a CCNNNN

Virgin Islands

(U.S.)

VIR VI full: house no,

street level

2016 Q2 HERE Map

Content

Y n/a Y Y NNNNN

Wallis and

Futuna Islands

WLF WF major cities,

country

2016 Q2 Entry Map

Content


Western

Sahara

ESH EH full: house no,

street level

2016 Q2 HERE Map

Content

(included in

Morocco map

product)

n/a n/a n/a n/a

Yemen YEM YE selected streets,

cities, country


Map Content


are used

Zambia ZMB ZM selected streets,

cities, country


Map Content


Zimbabwe ZWE ZW selected streets,

cities, country


Map Content


are used

Åland Islands ALA AX full: premium house

no., street level

2016 Q2 HERE Map

Content

(Included in

Skandinavia

map product)

n/a Y Y Y NNNNN

(CC-

NNNNN

from

abroad)

Coverage CategoriesThe following sections provide additional information on the standard data categories for the

Geocoder API.

Coverage Level

The following coverage levels are available by country/area for the Geocoder API:

• Full: premium house no., street level – Full coverage to house number level with selected house

numbers based on premium Point Adressing and/or Premium Address Ranges for high accuracy

geocoding results.

• Full: house no, street level – Full coverage to house number level based on Base Address Ranges

that are interpolated for high accuracy geocoding results.


• Selected streets, cities, country – Coverage down to street level.

• Major cities, country – Coverage down to city level.

Map Release

HERE releases updates for its maps on a regular basis. This column indicates the version number

of the latest release, indicated by the quarter and year of the release. The available map release

version is also included in Geocoder API responses in the MapReference section if requested via

locationattributes=mapReference.

MapVersion: Version of the map schema. Format: QQ/YYYY, e.g. Q1/2016

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: NAAM16109 (region: North

America (NAAM), map schema: Q1/2016 (161), weekly update 09)

Map Data Classification

The underlying maps used in the Geocoder API are assigned on of the following categories:

• HERE Map Content – This map cateogry represents map content that is comprehensive,

automotive-grade data suitable for navigation, location-based services, advanced route planning

and enterprise applications. You'll find HERE Map Content in vehicle navigation systems, the

top routing websites and millions of the top brands of GPS-enabled wireless devices around the

world. They're also the maps powering geographic information systems, homeland security and

they're the foundation for a new generation of location-based services.

• Intermediate Map Content – This map cateogry represents map content that is a separate class

of map products provided to support customers who are interested in introducing LBS and

navigation applications for emerging markets. Based on third-party source data deemed to be

the highest available level of quality, Intermediate Map Content can be suitable for a range of

functions, including navigation, search and display, and display only. However, they do not adhere

to the same specifications or required verification as the company's flagship product, HERE Map

Content. The Intermediate Map Content offering is an essential tool for customers who require

maps in a faster time to market for key regions of the world, and desire the same exceptional

service and support they have come to expect from us.

• Entry Map Content – This map cateogry represents map content that is a separate class of

map product sourced from a third party, compiled and edge matched to HERE Map Content.

Combining HERE Map Content data with Entry Map Content data enables seamless global or

regional map-based solutions. This product is designed primarily for map display and positional

location functionality. It has no navigable attributes and offers a limited road network. Entry

Map Content has a broad variety of inclusion levels per country but each country will comply to a


defined minimum specification. Sub-regions have been defined for ease of communication and

product distribution: Africa, Asia, Eastern Europe, Indonesia, Latin America and Oceania.

Localized Address Labels

This value indicates whether localized address labels are available.

Point Addresses

Point Addressing provides a point adjusted to the road as a precise address location. This product

resolves non-standard addressing issues in countries where non-sequential numbering is used or

where address ranges do not exist. For some countries, point address data is not available.

Postal Code Boundaries

This value indicates whether shape information is available for postal codes in the country/area.

Postal Codes

This value indicates whether postal code information is available for the country/area. Note that

some countries/area do not have ay postal codes, others may have postal codes, but the data is not

available, and others have postal codes that are available.

Postal Code Format

Different countries have different postal code formats. This column indicates the expected format.

For example, Andorra's postal code format is ADNNN (for example, AD100 for Canillo) and the Isle of

Man's postal code format is CCN NAA (for example, IM5 1LP for The Links, Peel or CCNN NAA for PO

boxes and large postal recipients).

Political Views

Description

The Geocoder provides a feature that can show available territories through the point of view of

particular countries.

A neutral international view is made available by default, where territories may have unresolved

claims.


Examples

Below is an example of the Kashmiri city of "Srinagar". The Geocoder now represents this neutrally

for the International community. India and Pakistan have their own particular views available for this

locality using the parameter &politicalview= and their respective 3-Letter ISO country codes.

International View of "Srinagar" (default)

Query:

&prox=34.0922244,74.8193568,1000

Previous Result:

Label: "Ganderbal Road, Khaniyar, Srinagar 190003, India",Country: "IND",State: "JK",County: "Srinagar",City: "Srinagar",District: "Khaniyar",Street: "Ganderbal Road",PostalCode: "190003",

Current Result:

Empty response (neutral territory)

Indian Political View of "Srinagar"

Query:

&prox=34.0922244,74.8193568,1000&politicalview=IND

Result:

Label: "Ganderbal Road, Khaniyar, Srinagar 190003, India",Country: "IND",State: "JK",County: "Srinagar",City: "Srinagar",District: "Khaniyar",Street: "Ganderbal Road",PostalCode: "190003",

Pakistani Political View of "Srinagar"

Query:

&prox=34.0922244,74.8193568,1000&politicalview=PAK

Result:

Label: "190003, Pakistan",Country: "PAK",


PostalCode: "190003",

Currently Supported Disputes

The following views are currently supported:

• ARE: Abu Musa Island, Tunb Islands

• ARG: Argentina

• EGY: Halaib Triangle

• GRC: Northern Cyprus

• IND: India

• ISR: Israel view on East Jerusalem

• KEN: Ilemi Triangle

• MAR: Western Sahara

• PAK: Pakistan

• RUS: Crimea, Kuril Islands (Shikotan, Iturup, Habomai, and Kunashir)

• TUR: Northern Cyprus, Southern Cyprus

• VNM: Vietnam

For any political view that is unsupported, the Geocoder falls back to the default view. For example,

politicalview=USA or politicalview=FRA does not impact a response in any way.

Name Example Reverse GeocoderCoordinates

Political ViewSupport

Description

Northern Arunachal Pradesh 28.6512526, 95.2272352 default, IND Default = Neutral territory (empty response)

IND = Part of the Indian State of Arunachal

Pradesh

Falkland Islands -51.6958016, -57.8529192 default, ARG Default = Falklands Islands

ARG = Part of Argentina's "Tierra Del Fuego"

South Georgia and SouthSandwich Islands

-54.2915196, -36.4940174 default, ARG Default = South Georgia And The South

Sandwich Islands

ARG = Part of Argentina's "Tierra Del Fuego"

(Indian-ChineseBorder)Kaurik

32.2112327, 78.5563334 default, IND Default = Neutral territory (empty response)

IND = Part of the Indian State of Himachal

Pradesh

(Indian-ChineseBorder)Lapthal

30.7338287, 80.1058805 default, IND Default = Neutral territory (empty response)




Description

IND = Part of the Indian State of Uttarakhand

(Indian-Chinese Border)Sang 31.2917262, 79.0702687 default, IND Default = Neutral territory (empty response)

IND = Part of the Indian State of Uttarakhand

(Kashmir)Aksai Chin 35.1355791, 79.0428155 default, IND,

PAKDefault = Neutral territory (empty response)

IND = Part of the Indian State of Jammu &

Kashmir

PAK = Seen as a part of China

(Kashmir)Azad Kashmir 33.9430273, 73.8271172 default, IND,



Kashmir

PAK = Seen as a part of Pakistan

(Kashmir)Gilgit-Baltistan 35.8260676, 75.0474641 default, IND,



Kashmir


(Kashmir)Pa-li-chia-ssu 33.257519, 79.2483097 default, IND,



Kashmir


(Kashmir)Shaksam Valley 36.0928479, 76.3108918 default, IND,



Kashmir

PAK = Seen as a part of China

(Kashmir)State of Jammu &Kashmir

33.5625116, 76.9892775 default, IND,



Kashmir


(Golan Heights) UN BufferZone

33.2053155, 35.8740408 default Default = Neutral territory (empty response)

(Argentinian-ChileanBorder)South Patagonian IceField

-49.4286077, -73.2129860 default Default = Neutral territory (empty response)

Paracel Islands 16.2438621, 111.7561099 default, VNM Default = Neutral territory (empty response)




Description

VNM = Vietnamese Islands

Spratly Islands 7.6808132, 111.5774475 default, VNM Default = Neutral territory (empty response)

VNM = Vietnamese Islands

Suriname-French GuianaTriangle

2.8357961, -54.1090861 default Default = Neutral territory (empty response)

Suriname-Guyana Triangle 2.1528005, -57.3365359 default Default = Neutral territory (empty response)

Macclesfield Bank 15.8434538, 114.3056814 default Default = Neutral territory (empty response)

Scarborough Shoal 15.4895344, 113.8210957 default Default = Neutral territory (empty response)

James Shoal 3.973889, 112.348889 default Default = Neutral territory (empty response)

Senkaku/Diaoyutai 25.7446986, 123.4709205 default Default = Neutral territory (empty response)

West Bank 31.9998544, 35.2998283 default Default = No Country

East Jerusalem 31.766327, 35.2453382 default, ISR Default = As part of West Bank

ISR = As part of Israel

Northern Cyprus 35.2453975, 33.3968783 default, GRC,

TURDefault = Turkish-Cypriot Administered Area

GRC = As a part of Cyprus (Republic of Cyprus)

TUR = Turkish Republic of Northern Cyprus

Southern Cyprus 35.0441914, 33.1554733 default, TUR Default = Cyprus (Republic of Cyprus)

TUR = Greek Cypriot Admin of Southern

Cyprus

Cyprus UN Neutral Zone 35.1691202, 33.2394362 default Default = UN Neutral Zone

Cyprus British Bases 34.6024439, 32.9538086 default Default = British Sovereign BSB Areas

Kinmen Islands 24.4642701, 118.3791237 default Default = Taiwanese Islands

Matsu Islands 26.2238182, 119.9946911 default Default = Taiwanese Islands

Kosovo 42.6718168, 21.1624711 default Default = No Country

Western Sahara 24.118844, -13.7725855 default, MAR Default = Neutral territory (empty response)

MAR = As a part of Morocco

Abu Musa Island 25.8871195, 55.0354848 default, ARE Default = Neutral territory (empty response)

ARE = As a part of the United Arab Emirates

Tunb Islands 26.2623118, 55.308378

25.8871195, 55.0354848

default, ARE Default = Neutral territory (empty response)

ARE = As a part of the United Arab Emirates




Description

Ilemi Triangle 4.7502929, 35.2197958 default, KEN Default = Neutral territory (empty response)

KEN = As a part of Kenya

Halaib Triangle 22.2363029, 35.1661332 default, EGY Default = Neutral territory (empty response)

EGY = As a part of Egypt

Crimea 44.95748, 34.10827 default, RUS Default = Part of Ukraine

RUS = As part of Russia

Kuril Islands (Shikotan,Iturup, Habomai, andKunashir)

45.1279501, 147.80728

(Iturup)

default, RUS Default = Neutral territory (empty response)

RUS = As part of Russia

Liancourt Rocks 37.2393599, 131.8758573 default Default = Neutral territory (empty response)

Lake Malawi -9.98382, 34.39834 default Default = Neutral territory (empty response)

Geocoder API Developer's Guidedocumentation.developer.here.com/pdf/geocoding_hlp/6.2... ·...

Documents

Transcript of Geocoder API Developer's Guidedocumentation.developer.here.com/pdf/geocoding_hlp/6.2... ·...