HERE 6.2.104 Geocoder API Developer's Guide
Iklan
Iklan
Geocoder API
Developer's Guide
Version 6.2.104
Geocoder API Developer's Guide
► Contents
2
Contents
Legal Notices
4
Document Information
5
Using Backwards Incompatible Features
....................................................................................
Customizing the Response with Attribute Switches
................................................................
Geocoder API Developer's Guide
► Contents
3
Multi Reverse Geocode Resource
................................................................................................
Multi Reverse Geocode Response
................................................................................................
Chapter 5: Coverage Information
.........................................................................................
Geocoder API Developer's Guide
► Legal Notices
4
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.
Geocoder API Developer's Guide
► Document Information
Document Information
Product
Name:
Version:
Document
Name:
Id:
Status:
Date:
Signatory:
Issuer-Certificate:
Serial-No.:
method:
Geocoder API
Version 6.2.104
Geocoder API Developer's Guide ac221b2-1454431225
FINAL
2016-Feb-02, 16:42 (GMT)
O=HERE, CN=here.com, ST=Berlin, C=DE
O=HERE, CN=here.com, ST=Berlin, C=DE
17391143833054135595 urn:adobe.com:Adobe.PPKLite:adbe.pkcs7.sha1 (Adobe
Signature)
5
Geocoder API Developer's Guide
► Overview
Chapter
1
Overview
Topics:
•
•
This section introduces the Geocoder API and describes its common use cases.
6
Geocoder API Developer's Guide
► Overview
7
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 can be 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 Market
St&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").
Geocoder API Developer's Guide
► Overview
• Find landmarks of national importance (for example, "Eiffel Tower").
• Get addresses or area information for a coordinate (for example, "41.8838 -87.6389")
8
Geocoder API Developer's Guide
► Quick Start
Chapter
2
Quick Start
Topics:
•
•
•
•
•
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.
9
Geocoder API Developer's Guide
► Quick Start
10
Making Your First Requests
Sometimes 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
on page 26.
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
on page 26 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
Geocoder API Developer's Guide
► Quick Start
11
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
Geocoder API Developer's Guide
► Quick Start
&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
12
Reverse Geocode Request
The 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>
Geocoder API Developer's Guide
► Quick Start
<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>
13
Geocoder API Developer's Guide
► Quick Start
</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>
14
Geocoder API Developer's Guide
► Quick Start
15
<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
Geocoder API Developer's Guide
► Quick Start
16
&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>
Geocoder API Developer's Guide
► Quick Start
17
<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>
Geocoder API Developer's Guide
► Quick Start
18
<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.
Geocoder API Developer's Guide
► Quick Start
19
•
RouteDistance
refers to the distance in meters from the snapped position on the link to the navigation position of the address. A user needs to travel this distance following the road to reach the entry of the house.
•
Direction
refers to the bearing of the display position of the address relative to a 0 bearing point 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>
Geocoder API Developer's Guide
► Quick Start
<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>
20
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
Geocoder API Developer's Guide
► Quick Start
21
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.
Multi Reverse Geocoding Example
Example
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,50 id=0002&prox=50.1618996,8.5334997,50 id=0003&prox=40.72962607104243,-73.98685008095087,50 id=0004&prox=47.609877297128094,-122.34250277090143,50 id=0005&prox=-22.98040197212022,-43.189731399601726,50 id=0006&prox=-8.494347821639211,115.25337974172669
id=0007&prox=28.63383758137441,77.21917444061432,50 id=0008&prox=-33.92046215720197,18.42085660357364,50 id=0009&prox=21.00272769618338,-89.62247149160008,50 id=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.
Geocoder API Developer's Guide
► Quick Start
22
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>
Geocoder API Developer's Guide
► Quick Start
...
</Result>
</Item>
...
</Response>
</ns2:MultiSearch>
23
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>
Geocoder API Developer's Guide
► Quick Start
24
<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
► User Guide
Chapter
3
User Guide
Topics:
•
•
•
•
•
The articles in this section provide a guide to using the Geocoder
API.
25
Geocoder API Developer's Guide
► User Guide
26
Acquiring Credentials
All 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 Request
A 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
Base URL
Value/Example
https://geocoder.api.here.com
Description
Production environment https://reverse.geocoder.api.here.com
on page 27 https://geocoder.cit.api.here.com
Geocoder API Developer's Guide
► User Guide
27
Element
Path
Resource
Value/Example
https:// reverse.geocoder.cit.api.here.com
/6.2
/geocode.json
/geocode.xml
/reversegeocode.json
/reversegeocode.xml
/multi-reversegeocode.json
/multi-reversegeocode.xml
/search.json
/search.xml
&app_code={YOUR_APP_CODE}
Description
GET only except for multireversegeocode (POST), specify request details via query parameters
Application Code Substitute your own unique app_code
Substitute your own unique app_id Application Id
&app_id={YOUR_APP_ID}
Customer Integration Testing
HERE 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
on page
49.
The CIT environment is not intended for general production use.
Request Encoding
Encode 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.
Geocoder API Developer's Guide
► User Guide
28
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 Concepts
This section provides information on key concepts used in the Geocoder API.
Using Backwards Incompatible Features
All 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 Compatibility
The 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 be populated for existing requests.
• Adding new error subtypes.
• Hardening constraint for an element value.
Geocoder API Developer's Guide
► User Guide
29
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 API
To 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 strategy to 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 History
These 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.
Geocoder API Developer's Guide
► User Guide
30
◦
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
◦
Includes gen=2 functionality.
◦
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
◦
Includes gen=3 functionality.
◦
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
◦
Includes gen=4 functionality.
◦ 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
Geocoder API Developer's Guide
► User Guide
31
◦
Includes gen=5 functionality.
◦
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
◦
Includes gen=6 functionality.
Geocoder API Developer's Guide
► User Guide
32
◦
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
◦
Includes gen=7 functionality.
◦ 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)
◦
Includes gen=8 functionality.
◦
Location.AdminInfo.TimeZoneOffset
moved to
Location.AdminInfo.TimeZone.Offset
together with the other time zone information.
See
&gen=8
&locationattributes=tz
Location.AdminInfo.TimeZoneOffset
Location.AdminInfo.LocalTime
Location.AdminInfo.Currency
Location.AdminInfo.DrivingSide
Location.AdminInfo.SystemOfMeasure
&gen=9
&locationattributes=tz
Location.AdminInfo.LocalTime
Location.AdminInfo.Currency
Location.AdminInfo.DrivingSide
Location.AdminInfo.SystemOfMeasure
Location.AdminInfo.TimeZone.Id
Location.AdminInfo.TimeZone.Offset
Location.AdminInfo.TimeZone.RawOffset
Location.AdminInfo.TimeZone.NameShort
Location.AdminInfo.TimeZone.NameLong
Location.AdminInfo.TimeZone.NameDstShort
Location.AdminInfo.TimeZone.NameDstLong
Location.AdminInfo.TimeZone.InDaylightTime
Location.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.
Geocoder API Developer's Guide
► User Guide
33
Customizing the Response with Attribute Switches
Responses 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
addressattributes
Values
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.
Geocoder API Developer's Guide
► User Guide
Attribute switch
responseattributes
Values
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. 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.
Note: The value names are case-sensitive.
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
Note: The value names are case-sensitive.
34
Examples
This section provides examples of Geocoder API requests.
Geocoding Examples
This section provides examples of geocode requests.
Geocoder API Developer's Guide
► User Guide
35
Find Address Based on Complete or Partial Address
Information using Freeform Input
The 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
Geocoder API Developer's Guide
► User Guide
36
?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 Address
Information using Qualified Input
If 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.
Geocoder API Developer's Guide
► User Guide
37
<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
Geocoder API Developer's Guide
► User Guide
38
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 Area
Additional 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>
...
Geocoder API Developer's Guide
► User Guide
39
<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 Intersections
Street 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>
...
Geocoder API Developer's Guide
► User Guide
40
<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 Identity
Every 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 Shapes
Location 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
Geocoder API Developer's Guide
► User Guide
41
?searchtext=94301+USA
&additionaldata=IncludeShapeLevel,postalCode
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9
The shape information is in WKT (Well Known Text) 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 Examples
This section provides examples of reverse geocoding requests.
Find Addresses Near a Position
The 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
Geocoder API Developer's Guide
► User Guide
42
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
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 Position
Example 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 Position
Example 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
Geocoder API Developer's Guide
► User Guide
43
Retrieve Area and Landmark Information at a Position
The 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.2
direction: 254.5
matchLevel: "district",
...
location: {
locationId: "NT_3k-9bTamuJdmfGCuY9h3wB",
locationType: "area",
...
address: {
label: "Presidio, San Francisco, CA, United States",
...
distance: -73.7
matchLevel: "landmark",
...
location: {
locationId: "NT_uQxRsUDYq4Gf3gjb2bKrEB_p_wcyTPTwD08nAzfdHIKshSB",
locationType: "park",
name: "Palace of Fine Arts",
...
address: {
label: "Palace Dr, San Francisco, CA 94123, United States",
...
Geocoder API Developer's Guide
► User Guide
44
Retrieve Landmarks Around a Position
This 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.7
matchLevel: "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 Search
A 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
Geocoder API Developer's Guide
► User Guide
45
•
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 Information
Client 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
Geocoder API Developer's Guide
► User Guide
46
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.78
distance: 21.5
matchLevel: "street",
...
location: {
locationId: "NT_nr8HVxV.kOEiHXKlHoIE0A_l_815826134_L",
locationType: "address",
...
address: {
label: "O'Farrell St, San Francisco, CA 94109, United States",
...
relevance: 0.68
distance: 31.6
matchLevel: "street",
...
location: {
locationId: "NT_5V25cCF0wAAoQ4CqmCMt8C_l_815826136_R",
locationType: "address",
...
address: {
label: "Myrtle St, San Francisco, CA 94109, United States",
...
relevance: 0.62
distance: 0.3
matchLevel: "street",
...
location: {
locationId: "NT_5DmLoeLNDKXxFIbZ44QhfA_l_815826149_L",
locationType: "address",
...
address: {
label: "Van Ness Ave, San Francisco, CA 94109, United States",
...
Landmark Geocoding Examples
This section provides examples of landmark geocoding requests.
Find Well Known Landmarks
You 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
Geocoder API Developer's Guide
► User Guide
47
◦ National parks
◦
Tourist attractions
Table 3: Find Well Known Landmarks
Required
• searchtext
(text or name to search for)
Optional (area qualifiers and spatial filters)
•
•
•
•
•
•
•
•
•
•
• 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}
Geocoder API Developer's Guide
► User Guide
&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
Highway Exit
Ferry Terminal
Airport
Historical Monument
Sports Complex
Park/Recreation Area
Amusement Park
Tourist Attraction
Museum
Border Crossing
5999
7940
7947
7996
7999
8410
9999
Category Id
116
4482
4581
48
Geocoder API Developer's Guide
► User Guide
49
Service Support
If you need assistance with this or other HERE products, please contact your HERE representative or
Technical Customer Support.
Geocoder API Developer's Guide
► API Reference
Chapter
4
API Reference
Topics:
•
•
•
This part of the guide provides a comprehensive reference to
Geocoder API.
50
Geocoder API Developer's Guide
► API Reference
51
Resources and Parameters
This 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
page 34 for supported parameter combinations.
Name
Geocoding
Reverse geocoding
Multi reverse geocoding
Landmark geocoding
URL
https://geocoder.api.here.com/6.2/geocode.{format} https://reverse.geocoder.api.here.com /6.2/reversegeocode.{format} https://reverse.geocoder.api.here.com /6.2/multi-reversegeocode.
{format} https://geocoder.api.here.com/6.2/search.{format}
Where {format} is either JSON or XML.
Geocode Resource
This section contains a list of all Geocode request parameters.
.../6.2/geocode.{format}?<parameter>=<value>...
Table 5: Request Parameters
Parameter
additionaldata
Description
Key-value pairs that provide additional input to requests. See
on page 69 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 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]
Geocoder API Developer's Guide
► API Reference
Parameter
app_id app_code bbox city country countryfocus
52
Description
On by default: All except addressLines.
Note: The value names are case-sensitive.
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
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
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
•
• xs:string, fuzzy match
A country specific mapping is required. Example,
USA: City
Germany: Gemeinde 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.
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.
Geocoder API Developer's Guide
► API Reference
Parameter
county district gen housenumber jsonattributes jsoncallback language locationattributes
53
Description
• 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.
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
•
• 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 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.
xs:string, exact match
The house number or house name.
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
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.
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]
Geocoder API Developer's Guide
► API Reference
Parameter
locationid mapview maxresults pageinformation
54
Description
The adminIds switch is available with forward geocoding only. 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.
Note: The value names are case-sensitive.
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.
on page 92
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
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
}" 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:
"metaInfo: {
Geocoder API Developer's Guide
► API Reference
Parameter
politicalview postalcode prox responseattributes searchtext state street
55
Description
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}" 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
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.
xs:string, exact match
Postal code defined by the government of the country.
GeoProximityType, see also
on page 93 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.
Relevant global results are also returned.
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
Note: The value names are case-sensitive.
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 freeform address in the searchtext field.
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 xs:string, fuzzy match
Geocoder API Developer's Guide
► API Reference
56
Parameter
strictlanguagemode token
Description
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 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.
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 Resource
This section contains a list of all Reverse Geocode request parameters.
.../6.2/reversegeocode.{format}?<parameter>=<value>...
Table 6: Request Parameters
Parameter
additionaldata
Element
Key-value pairs that provide additional input to requests. See
on page 69 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 addressattributes
Comma separated list of which elements are present in the response data.
Geocoder API Developer's Guide
► API Reference
Parameter
app_id app_code gen jsonattributes jsoncallback language level locationattributes
57
Element
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.
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
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
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.
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
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.
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.
Comma separated list of which elements are present in the response data.
Geocoder API Developer's Guide
► API Reference
Parameter
maxresults minresults mode
58
Element
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. 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.
Note: The value names are case-sensitive.
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
}" xs:int
Ignore the specified radius until minResults results are found. Default is 0. Currently only supported for Reverse Geocode mode=retrieveAreas.
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 trackPosition
- Retrieve street and address information based on a position and bearing
Geocoder API Developer's Guide
► API Reference
Parameter
pageinformation politicalview pos prox responseattributes sortby
59
Element
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:
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}" 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
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.
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.
GeoProximityType, see also
on page 93 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.
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
Note: The value names are case-sensitive.
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.
Geocoder API Developer's Guide
► API Reference
60
Parameter
strictlanguagemode token
Element
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.
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.
Multi Reverse Geocode Resource
This 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>...
Table 7: Request Parameters
Parameter
additionaldata
Element
Key-value pairs that provide additional input to requests. See
on page 69 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 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.
Geocoder API Developer's Guide
► API Reference
Parameter
app_id app_code gen jsonattributes jsoncallback language level locationattributes
61
Element
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
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
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.
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
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.
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.
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. For reverse geocoding results adminIds are always present unless turned off via locationattributes=none.
locationattributes=-adminIds
has no effect on reverse geocoding results.
Geocoder API Developer's Guide
► API Reference
Parameter
maxresults minresults mode pageinformation
62
Element
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.
Note: The value names are case-sensitive.
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
}" xs:int
Ignore the specified radius until minResults results are found. Default is 0. Currently only supported for Reverse Geocode mode=retrieveAreas.
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 trackPosition
- Retrieve street and address information based on a position and bearing 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:
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
Geocoder API Developer's Guide
► API Reference
Parameter
politicalview responseattributes sortby strictlanguagemode token
63
Element
}" 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
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.
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
Note: The value names are case-sensitive.
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.
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.
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.
Geocoder API Developer's Guide
► API Reference
64
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 Resource
This section contains a list of all Landmark Geocode request parameters.
.../6.2/search.{format}?<parameter>=<value>...
Table 8: Request Parameters
Parameter
additionaldata
Description
Key-value pairs that provide additional input to requests. See
on page 69 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 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.
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
app_code xs:string
A 20 byte Base64 URL-safe encoded string used for the authentication of the client application.
Geocoder API Developer's Guide
► API Reference
Parameter
bbox categoryids city country countryfocus county
65
Description
You must include an app_id and app_code with every request. To get an app_id assigned to you, please see
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
•
•
• xs:integer
Limit landmark results to one or more categories. Examples:
Highway exits: 116
Airports: 4581
Tourist attractions: 7999
•
• xs:string, fuzzy match
A country specific mapping is required. Example,
USA: City
Germany: Gemeinde 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.
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.
xs:string, fuzzy match
Geocoder API Developer's Guide
► API Reference
Parameter
district gen housenumber jsonattributes jsoncallback language locationattributes
66
•
•
Description
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
•
• 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 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.
xs:string, exact match
The house number or house name.
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
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.
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. 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.
Geocoder API Developer's Guide
► API Reference
Parameter
locationid mapview maxresults name pageinformation
67
Description
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.
Note: The value names are case-sensitive.
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.
on page 92
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
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
}" 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 xs:string
Geocoder API Developer's Guide
► API Reference
Parameter
politicalview postalcode prox responseattributes searchtext state
68
Description
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:
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}" 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
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.
xs:string, exact match
Postal code defined by the government of the country.
GeoProximityType, see also
on page 93 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.
Relevant global results are also returned.
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
Note: The value names are case-sensitive.
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 freeform address in the searchtext field.
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
Geocoder API Developer's Guide
► API Reference
69
Parameter
street strictlanguagemode token
Description
• US: State
• Germany: Bundesland 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 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.
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.
Additional Data Parameter
List of KeyValuePairType elements as generic container to attach additional information to requests.
Table 9: Key-value pairs for Additional Data
Key
CrossingStreets
PreserveUnitDesignators
Value
true/false
, determines whether the response contains cross streets.
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.
Geocoder API Developer's Guide
► API Reference
70
Key
Country2
IncludeChildPOIs
IncludeRoutingInformation
AdditionalAddressProvider
HouseNumberMode
FlexibleAdminValues
Value
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.
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.
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.
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.
Defines how to geocode unknown house numbers. The following values are supported:
•
Extrapolation <MAX_HSN_DISTANCE> <MAX_DISTANCE> extrapolation.
: Use
•
•
Extrapolation is performed until a predefined maximum distance in house number and a maximum in meters. The system wide configured maximum values can be overwritten by passing values for MAX_HSN_DISTANCE and/or
MAX_DISTANCE. If any of the maximum is exceeded the result falls back to the street level match.
Fallback <MAX_HSN_DISTANCE>
: Use house number fallback. This is the default value.
Fallback is performed until a predefined maximum distance in house number.
This system-wide configured maximum value can be overwritten by passing a value for MAX_HSN_DISTANCE. If the maximum is exceeded, the result falls back to the street level match.
Streetlevel
: Do not do extrapolation or fallback; instead return a streetlevel match (up-hierarchy).
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
Geocoder API Developer's Guide
► API Reference
71
Key
IntersectionSnapTolerance
AddressRangeSqueezeOffset
AddressRangeSqueezeFactor
IncludeShapeLevel
RestrictLevel
SuppressStreetType
NormalizeNames
IncludeDistanceMarkers
Value
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).
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.
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.
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.
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.
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.
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.
true/false
, option to receive the same normalized admin and street names from forward and reverse geocoding results. By default, the preferred admin and street names for forward geocoding in the result are the names from the user input.
Normalized means name normalization for all Geocoder API components.
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.
Geocoder API Developer's Guide
► API Reference
72
Response Data Types
This section provides reference to the data structures used throughout the Geocoder API.
Search Response
The
consists of a list of
object found for the request together with
Figure 1: Overview Response Types
Geocoder API Developer's Guide
► API Reference
The
is the central entity of a search result. It provides information about the geographical
,
expose detailed information on the address elements. The identifiers stored in the
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
element whereas the
element exposes country or state meta information for the administrative area of a location like the
related to other Locations. This relationship is modeled by the
Figure 2: Overview Location Type
73
Geocoder API Developer's Guide
► API Reference
74
Response (SearchResponseType)
Table 10: Response elements
Type
Description
Meta Information about the Request
Search Results are grouped in Views.
MetaInfo (SearchResponseMetaInfoType)
Table 11: MetaInfo elements
Type
RequestId
Timestamp
Description
Mirrored RequestId value from the request structure. Can be used to trace requests.
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.
The resulting items which have been found along with attributes indicating the quality of the search result.
Geocoder API Developer's Guide
► API Reference
75
Result (SearchResultType)
The SearchResult contains the actual result as a
object together with information on how
good the result matches the search request.
Table 13: Result elements
Type
Relevance
Distance
Direction
MatchLevel
MatchType
MatchCode
Description
Indicates the relevance of the results found; the higher the score the more relevant the alternative. The score is a normalized value between 0 and 1.
Distance between the identified location object and the specified client position in meters. Only provided if a proximity was specified in the request (parameter 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 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.
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.
Detailed information about the match quality on the attribute level. MatchQuality is always 1.0 for reverse geocode results.
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.
Code indicating how well the result matches the request. Enumeration [exact, ambiguous, upHierarchy
, ambiguousUpHierarchy].
Structured representation of the request which led to the current search result.
The location that was found.
AdditionalData
Generic key/value container to keep additional attributes. The defined key/values are:
• houseNumberFallback
Geocoder API Developer's Guide
► API Reference
Type
76
Description
• true/false. This attribute is included, if MatchLevel is houseNumber. It is set to false, if Search could find the requested house number. If set to true, it indicates that the requested house number was corrected to match the nearest known house number houseNumberFallbackDifference
•
•
Difference between the requested house number and the matched house number. This attribute is only included if houseNumberFallback is set to true.
houseNumberExtrapolation true/false. An extrapolated address is marked true. House number extrapolation can be activated with an additional data parameter HouseNumberMode, Extrapolation.
houseNumberExtrapolationDistance
•
For an extrapolated address, this attribute provides the distance in meters from an existing point or range address houseNumberExtrapolationDifference
For an extrapolated address, this attribute provides the difference in house numbers from an existing point or range address.
MatchQuality (LocationMatchQualityType)
MatchQuality provides detailed information about the match quality of a result at attribute level.
Match quality is a value between 0.0 and 1.0. 1.0 represents a 100% match.
Table 14: MatchQuality elements
Type
Country
State
County
City
District
Subdistrict
Street
HouseNumber
PostalCode
Building
Description
Match quality of the result with respect to country information in the request.
Match quality of the result with respect to state information in the request.
Match quality of the result with respect to county information in the request.
Match quality of the result with respect to city information in the request.
Match quality of the result with respect to district information in the request.
Match quality of the result with respect to sub-district information in the request.
Match quality of the result with respect to street information in the request. There are two values of
'Street' when you specify an intersection.
Match quality of the result with respect to house number information in the request.
Match quality of the result with respect to postal code information in the request.
Match quality of the result with respect to building information in the request.
Geocoder API Developer's Guide
► API Reference
77
ParsedRequest (ParsedRequestType)
ParsedRequest shows how the various components of the request were derived from search terms.
Table 15: ParsedRequest elements
Type
Name
Label
Country
State
County
City
District
Subdistrict
Street
HouseNumber
PostalCode
Building
AddressLine
AdditionalData
Description
Input token(s) the parser has categorized as the name of a landmark.
Assembled address value built out of the parsed address components.
Input token(s) the parser has categorized as the country part of an address.
Input token(s) the parser has categorized as the state part of an address.
Input token(s) the parser has categorized as the county part of an address.
Input token(s) the parser has categorized as the city part of an address.
Input token(s) the parser has categorized as the district part of an address.
Input token(s) the parser has categorized as the sub-district part of an address.
Input token(s) the parser has categorized as the street part of an address (including intersections which are defined by two streets).
Input token(s) the parser has categorized as the house number part of an address.
Input token(s) the parser has categorized as the postal code part of an address.
Input token(s) the parser has categorized as the building part of an address.
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.
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
Geocoder API Developer's Guide
► API Reference
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
LocationId
LocationType
Description
A key uniquely identifying a physical location.
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
78
Geocoder API Developer's Guide
► API Reference
79
Type
Name
DisplayPosition
The name of a location. This is relevant for landmarks like parks and lakes.
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
Shape
Bounding box of the location optimized for display
Shape of the location. This is only relevant for areas.
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.
Additional information about the address. The names for address elements are listed together with the language information for this name.
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.
References to a network link and admin areas of the location object.
The most common map attributes of a navigable link. Only available for link based locations like streets and buildings.
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
AdditionalData
Description
• beach
• distanceMarker
For gen<5 the location type is set to point.
Generic key/value container to keep additional attributes. The defined key/values are:
• ExtendedTopLeftLatitude
•
Latitude of the top-left coordinate of the extended bounding box which completely encloses the physical extent of the location.
ExtendedTopLeftLongitude
•
•
Latitude of the top-left coordinate of the extended bounding box
ExtendedBottomRightLatitude
Latitude of the bottom-left coordinate of the extended bounding box
ExtendedBottomRightLongitude
Longitude of the bottom-right coordinate of the extended bounding box
Geocoder API Developer's Guide
► API Reference
80
Type Description
• "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
ReferenceId
MapVersion
MapId
Spot
SideOfStreet
CountryId
StateId
CountyId
CityId
DistrictId
BuildingId
AddressId
Description
PVID of the link (for address level results).
Version of the map schema. Format: QQ/YYYY, e.g. Q1/2015
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)
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.
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].
PVID of the country admin area.
PVID of the state admin area.
PVID of the county admin area.
PVID of the city admin area.
PVID of the district admin area.
External reference to additional building information (currently for internal use only)
PVID of the Point Address. Only available for results with matchLevel houseNumber and matchType pointAddress
. Not available for interpolated results.
Geocoder API Developer's Guide
► API Reference
81
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
Label
Country
State
County
City
District
Subdistrict
Street
HouseNumber
PostalCode
Building
AddressLine
AdditionalData
Definition
Assembled address value for displaying purposes.
ISO 3166-alpha-3 country code
Includes the first subdivision level below the country. Where commonly used, this is a state code such as
CA for California.
Includes the second subdivision level below the country. Use of this field is optional if a second subdivision level is not available.
Refers to the locality of the address.
Includes the subdivision level below the city. Use of this field is optional if a second subdivision level is not available.
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.
Refers to the street name.
House number. Depending on regional characteristics, can also be house name.
Postal code
Building name. Building names are currently only supported for Hong Kong addresses.
Distance marker information for this location. Only populated when explicitly requested with additionaldata=IncludeDistanceMarkers,true
.
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.
Generic key/value container to keep additional attributes. The defined key/values are:
• "CrossingStreet0"
•
•
First cross street near matched address
"CrossingStreet1"
Second cross street near matched address. This value is omitted by the search module, if the location’s distance to CrossingStreet0 is less than half of the distance to CrossingStreet1.
"CountryName"
Geocoder API Developer's Guide
► API Reference
Element
82
Definition
Non-abbreviated, full name of the country.
• "StateName"
•
•
Non-abbreviated, full name of the state.
"CountyName"
Non-abbreviated, full name of the county.
"Country2"
•
•
If requested by passing &additionaldata=Country2,true, this field provides the ISO-3166 alpha-2 country code. By default, two-letter codes are not returned.
Secondary address units as defined by the US Postal Service can be recognized and returned if the PreserveUnitDesignators switch was set to true in SearchRequest.additionalData. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry:
◦
◦
◦
◦
◦
◦
◦
◦
"APT" - recognized value of unit type "Apartment"
"BLDG" - recognized value of unit type "Building"
"FL" - recognized value of unit type "Floor"
"STE" - recognized value of unit type "Suite"
"UNIT" - recognized value of unit type "Unit"
"RM" - recognized value of unit type "Room"
"DEPT" - recognized value of unit type "Department"
"UnknownUnit" - unrecognized address unit value, which is usually printed with a pound ("#") sign.
"PostalCodeType"
◦
◦
◦
◦
For the USA, the Geocoder result shows supplementary information that describes the type of the
5-Digit ZIP, as according to the USPS. The values are as follows:
"N" = Non-Unique
"M" = Military
"P" = PO Box
"U" = Unique Zip
Address Details (AddressDetailsType)
The address details type provides additional information about the address. The names for address elements are listed together with the language information for this name.
Geocoder API Developer's Guide
► API Reference
Table 19: Address Details elements
Element
CountryCode
Country
State
County
City
District
Street
HouseNumber
PostalCode
Building
Definition
ISO 3166-alpha-3 country code
Country name together with the language information
State name together with the language information
County name together with the language information
City name together with the language information
District name together with the language information
Street name together with the language information
Street name decomposed into the different name parts
House number together with the language information (if available)
Postal code
Building name together with the language information
83
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
Country
State
County
City
District
Subdistrict
Street
Definition
List of key/value pairs with country name together with the language information
List of key/value pairs with state name together with the language information
List of key/value pairs with county name together with the language information
List of key/value pairs with city name together with the language information
List of key/value pairs with district name together with the language information
List of key/value pairs with sub-district name together with the language information
List of key/value pairs with street name together with the language information
Geocoder API Developer's Guide
► API Reference
84
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
StreetType
Base name part of the street name. The base name is a numbered route, local name, or commonly accepted name for a street.
Street type part of the street name. Street type is the local municipality designator of each road, such as "street", "road", "strasse", "straat", "via", or "rue de la". Street types are defined as either
"preceding" or "following" the base name and "attached" or "unattached" to the base name.
StreetTypeBefore Defines if the street type is before or after the base name.
StreetTypeAttached Defines if the street type is attached or unattached to the base name.
Prefix
Suffix
A prefix is a directional identifier that precedes, but is not included in, the base name of a road.
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
Value
Offset
Unit
DirectionOnSign
Description
Distance Marker value
Distance in the local units along the highway from the lowest Distance Marker nearest to the matched position on the road.
Local unit of measure used for the offset, either mi or km.
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.
Geocoder API Developer's Guide
► API Reference
85
Note All link info attributes are subject to additional licensing. We reserve the right to require authorization on API level for all or individual attributes with future releases. Currently, only the SpeedLimit attribute requires authorization and the attribute is not included in
LinkInfo
if the client application is not authorized to receive this information.
Table 23: Link Info elements
Type
FunctionalClass
TravelDirection
SpeedCategory
SpeedLimit
LinkFlags
AccessFlags
Description
The functional class is used to classify roads depending on the speed, importance and connectivity of the road.
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.
Classifies the general speed trend of a navigable link based on posted or legal speed. (see
enumeration for possible values)
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.
Flags that describe special characteristics of the link like Motorway, Tollroad, Paved, etc. (see
enumeration for possible values).
Flags that describe access characteristics of the link like Automobiles, Buses, Pedestrians, etc.
(see
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
TimeZoneOffset
LocalTime
Description
UTC Timezone offset applicable for the area.
Local wall clock date and time in UTC format (ISO 8601).
Currency
DrivingSide
ISO 4217 currency code used in the country.
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.
Geocoder API Developer's Guide
► API Reference
86
Timezone (TimezoneType)
The Timezone type provides detailed time zone information including offsets and daylight savings.
Table 25: Timezone elements
Type
Id
Offset
RawOffset
NameShort
NameLong
NameDstShort
NameDstLong
InDaylightTime
DstSavings
Description
Identifier for the timezone taken from the Java 8 platform.
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.
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.
A short standard time name of this time zone.
A long standard time name of this time zone.
A short Daylight Saving Time name of this time zone.
A long Daylight Saving Time name of this time zone.
True, if the time zone is currently in Daylight Saving Time.
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
Type
Description
The type of the relationship to the associated location. The following types of related locations are supported:
• nearByDistanceMarker
Location of a nearby distance marker on the highway. Retrieving distance markers is supported for the Reverse Geocoding mode retrieveAddresses and is enabled by the flag
&additionaldata=includeDistanceMarkers,true
• nearByAddress
Location of a nearby address on the same link. Retrieving nearby addresses is supported for the Reverse Geocoding mode trackPosition and is enabled by the flag
&locationattributes=related.nearByAddress
Geocoder API Developer's Guide
► API Reference
87
Type
MatchType
RouteDistance
Direction
Location
Description
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.
Distance to the associated location. The distance is calculated based on the underlying road geometry.
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.
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 Response
The
structure is the top level element returned by multi reverse geocode
requests. It contains
and one or more
. Each item corresponds to one of the
items in the request, correlated by an ItemId. A response Item contains a list of
which wrap the
objects found for the request.
Figure 3: Overview Multi Search Response Types
Geocoder API Developer's Guide
► API Reference
88
Response (MultiSearchResponseType)
Table 27: Response elements
Type
Description
Meta Information about the Request
List of response items, each element wrapping the result of a corresponding input item in the request.
MetaInfo (MultiSearchResponseMetaInfoType)
Table 28: MetaInfo elements
Type
RequestId
Timestamp
AdditionalData
Description
Mirrored RequestId value from the request structure.Used to trace requests.
Time at which the search was performed.
List of KeyValuePairType elements as generic container to attach additional information to the request.
Item (MultiSearchResponseItemType)
Table 29: Item elements
Type
ItemId
Description
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.
The resulting alternative items which have been found along with attributes indicating the quality of the search result.
Base Data Types
Base Data Types used in the Search Response Structure.
LatitudeType
Location of a place on Earth north or south of the equator.
Geocoder API Developer's Guide
► API Reference
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
LongitudeType
Location 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
• Precision: 7 positions after decimal point, additional positions are ignored
Query Parameter Representation
Valid examples:
90.1234567
-120.3456789
90.123
DistanceType
This type can be used whenever distances need to be represented.
DistanceType is an xs:double type with the following restrictions:
• Unit: meters
• Precision: 4 positions after decimal point, additional positions are ignored
89
Geocoder API Developer's Guide
► API Reference
90
Examples
45.1234
899344
DistanceUnitType
Unit of measure used to describe distance values.
The following enumeration values are supported:
•
• mi km
: Miles
: Kilometers
HeadingType
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. 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
• Precision: 4 positions after decimal point, additional positions are ignored
CardinalDirectionType
Enumeration type representing the four cardinal (north, east, south, west) and the four ordinal (NE,
SE, SW, NW) directions.
The following enumeration values are supported:
•
N: north
•
E: east
•
S: south
•
W: west
•
NE: northeast
•
SE: southeast
•
SW: southwest
Geocoder API Developer's Guide
► API Reference
91
•
NW: northwest
CountryCodeType
This 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
SideOfStreetType
Values to indicate on which side of a link an object is placed.
The following enumeration values are available for SideOfStreetType:
• left
• right
• neither
ShapeFormatType
Defines identifiers for the supported shape representations.
The following enumeration values are available for ShapeFormatType:
•
WKT
Identifier for Well-known text (WKT)
ReverseGeocodeModeType
The 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 the request.
• retrieveLandmarks
Search for landmarks like parks and lakes in the proximity provided in the request.
Geocoder API Developer's Guide
► API Reference
92
• retrieveAll
Search for streets, administrative areas and landmarks. This mode aggregates the results 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.
GeoCoordinateType
The 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.
GeoBoundingBoxType
A 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)
Geocoder API Developer's Guide
► API Reference
◦ Longitude
WGS-84 / degrees with (-180 <= Longitude <=180)
◦ Altitude
Altitude in meters (optional)
• BottomRight
Bottom-right 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)
Query Parameter Representation
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
GeoProximityType
A 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
WGS-84 / degrees with (-90 <= Latitude <=90)
◦
Longitude
WGS-84 / degrees with (-180 <= Longitude <=180)
◦
Altitude
93
Geocoder API Developer's Guide
► API Reference
94
Currently unused
• Radius
Radius in meters
Query Parameter Representation
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
GeoPositionType
A 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.
Query Parameter Representation
The GeoPositionType can be represented in query strings as follows:
<Latitude> + "," + <Longitude> (+ "," + <Heading>)?
Example: pos=37.7890649,-122.4027371,271.4
GeoShapeType
Abstract base class for different shape representations. A shape is a vector geometry object which resides on a map. Please check the enumeration type
for a list of supported representations.
Geocoder API Developer's Guide
► API Reference
95
WKTShapeType
WKTShapeType 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
Example:
String value containing the WKT representation.
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))
KeyValuePairType
This 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.
Query Parameter Representation
A KeyValuePair can be represented in query strings as follows:
<Key> + "," + <Value>
Note Representation formats: Special characters need to be URL-encoded.
LocalizedNameType
A LocalizedNameType enriches a name with the corresponding language information. It defines the following attributes:
• Value
Geocoder API Developer's Guide
► API Reference
96
Text representation of the name
• Language
Language information for the name (RFC 5646 Language Tag)
FunctionalClassType
The 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
SpeedCategoryType
Speed 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
SC1
SC2
SC3
SC4
SC5
SC6
SC7
SC8
Speed range in km/h
>130 km/h
101-130 km/h
91-100 km/h
71-90 km/h
51-70 km/h
31-50 km/h
11-30 km/h
<11 km/h
Speed range in MPH
>80 MPH
65-80 MPH
55-64 MPH
41-54 MPH
31-40 MPH
21-30 MPH
6-20 MPH
<6 MPH
Geocoder API Developer's Guide
► API Reference
97
SpeedLimitType
Speed 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)
LinkFlagType
Values 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
Geocoder API Developer's Guide
► API Reference
98
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.
LinkAccessFlagType
Defines 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
Geocoder API Developer's Guide
► API Reference
99
• Motorcycles
RelationshipEnumType
Enumeration type for the relationship roles that a related location can assume.
The following enumeration values are supported:
• nearByDistanceMarker
Location of a nearby distance marker on the highway.
• nearByAddress
Location of a nearby address on the same link.
UTCTimeOffsetType
UTC 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:00
UTC-06:00
UTC±00:00
UTC+01:00
UTC+04:30
CurrencyType
3-letter code abbreviation for a currency according to ISO 4217
Examples
EUR
USD
RUB
DrivingSideType
Driving side for road traffic
• left
: left-hand traffic
• right
: right-hand traffic
Geocoder API Developer's Guide
► API Reference
100
SystemOfMeasurementType
A 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 Examples
This 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
XSD Version
https://geocoder.api.here.com/6.2/xsd/LBSP-Search-Search.xsd
4.3
XML Schema for endpoint
multi-reversegeocode
results
Schema location
XSD Version
https://geocoder.api.here.com/6.2/xsd/LBSP-Search-MultiSearch.xsd
1.0
Response Examples
Example Geocode Response
For explanations of each element in the XML response, see
<Response>
<MetaInfo>
<Timestamp>2015-09-15T06:10:48.562Z</Timestamp>
</MetaInfo>
<View xsi:type="ns2:SearchResultsViewType">
<ViewId>0</ViewId>
<Result>
<Relevance>1.0</Relevance>
Geocoder API Developer's Guide
► API Reference
<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
For explanations of each element in the XML response, see
<?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>
101
Geocoder API Developer's Guide
► API Reference
102
<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>
Geocoder API Developer's Guide
► API Reference
Example Multi Reverse Response
For explanations of each element in the XML response, see
Multi Reverse Geocode Response
on page 87
<?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>
103
Geocoder API Developer's Guide
► API Reference
<Item>
<ItemId>2</ItemId>
<Result>
...
</Result>
</Item>
...
</Response>
</ns2:MultiSearch>
Example Landmark Geocode Response
For explanations of each element in the XML response, see
<?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>
104
Geocoder API Developer's Guide
► API Reference
</View>
</Response>
</ns2:Search>
105
Geocoder API Developer's Guide
► Coverage Information
106
Chapter
5
Coverage Information
Topics:
•
•
This appendix contains additional information about Geocoder API.
Geocoder API Developer's Guide
► Coverage Information
107
Geocoder Coverage
The 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
page 122.
The Geocoder provides weekly map updates based on the HERE Stable Baseline. The base line for the map schema is currently Q1/2015. Weekly map data updates are based on the map data releases specified per country in the table below.
Table 31: API Coverage
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release Postal
Code
Format
Afghanistan
Albania
Algeria
American
Samoa
Andorra
Angola
Anguilla
AFG AF
ALB AL full: house no, street level
DZA DZ selected streets, cities, country
ASM AS major cities, country major cities, country
AND AD full: house no, street level
AGO AO selected streets, cities, country
AIA AI major cities, country
2016 Q1
2016 Q1
2015 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
Map Data
Classification
Localized
Address
Labels
Point
Addresses
n/a n/a Entry Map
Content
HERE Map
Content
Intermediate
Map Content
Entry Map
Content
Yes n/a n/a n/a n/a n/a
Postal
Code
Boundaries
n/a n/a n/a n/a
Postal
Codes
n/a n/a n/a n/a
HERE Map
Content
(Included in
France map product)
Intermediate
Map Content
Entry Map
Content
Yes n/a n/a n/a n/a n/a
Y n/a n/a
Y
NNNN
NNNN
NNNNN
NNNNN
(optionally
NNNNN-
NNNN or
NNNNN-
NNNNNN)
ADNNN no codes are used n/a AI-2640
Geocoder API Developer's Guide
► Coverage Information
108
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Antarctica
Antigua and
Barbuda
Argentina
Armenia
Aruba
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgium
Belize
Benin
Bermuda
Bhutan
Bolivia
ATA AQ major cities, country
ATG AG major cities, country
2015 Q4
2016 Q1
ARG AR full: premium house no., street level
2016 Q1
2016 Q1 ARM AM major cities, country
ABW AW selected streets, cities, country
2016 Q1
AUS AU
AUT AT full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1
AZE AZ full: premium house no., street level
2016 Q1
2016 Q1 BHS BS full: house no, street level
BHR BH full: house no, street level
2016 Q1
BGD BD selected streets, cities, country
BRB BB selected streets, cities, country
BLR BY
BEL
BLZ
BE
BZ
BEN BJ
2016 Q1
2016 Q1 selected streets, cities, country
2016 Q1 full: premium house no., street level
2016 Q1 selected streets, cities, country
2016 Q1 major cities, country
2016 Q1
BMU BM selected streets, cities, country
BTN BT major cities, country
BOL BO selected streets, cities, country
2016 Q1
2016 Q1
2016 Q1
HERE Map
Content
HERE Map
Content
Intermediate
Map Content
Entry Map
Content
Intermediate
Map Content
Entry Map
Content
Intermediate
Map Content
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a n/a n/a Entry Map
Content
HERE Map
Content
Yes n/a
Yes n/a Entry Map
Content
Intermediate
Map Content
HERE Map
Content
HERE Map
Content n/a
Yes
Yes n/a
Y
Y
Intermediate
Map Content
HERE Map
Content
HERE Map
Content
Intermediate
Map Content
Intermediate
Map Content
Yes
Yes
Yes n/a n/a
Y n/a n/a n/a n/a
Yes
Yes n/a n/a n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a
Postal
Code
Boundaries
n/a n/a n/a n/a n/a
Y
Y n/a n/a n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a
Postal
Codes
Postal
Code
Format
no codes are used no codes are used
Y NNNN n/a no codes are used
Y NNNN
Y n/a no codes are used n/a NNN or
NNNN n/a NNNN n/a n/a
Y no codes are used no codes are used n/a AA n/a n/a
NNNN
NNNN
CCNNNN
CCNNNNN
NNNNNN
NNNN
NNNNN
NNNN
Geocoder API Developer's Guide
► Coverage Information
109
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Bonaire, Sint
Eustatius and
Saba
Bosnia and
Herzegovina
Botswana
Brazil
China (China spec, only
BES BQ major cities, country
BIH BA full: premium house no., street level
2016 Q1
2016 Q1
BWA BW full: house no, street level
BRA BR full: premium house no., street level
2016 Q1
2016 Q1
Brunei
Darussalam
Bulgaria
Burkina Faso
Burundi
Cambodia
Cameroon
Canada
Cape Verde
Cayman
Islands
Central
African
Republic
Chad
BRN BN full: house no, street level
2016 Q1
BGR BG full: premium house no., street level
2016 Q1
BFA BF major cities, country
2016 Q1
BDI BI
KHM KH selected streets, cities, country selected streets, cities, country
2016 Q1
2016 Q1
CMR CM major cities, country
CAN CA full: premium house no., street level
2016 Q1
2016 Q1
CPV CV 2016 Q1
CYM KY
CAF CF major cities, country full: house no, street level major cities, country
2016 Q1
2016 Q1
Chile
TCD TD major cities, country
CHL CL full: premium house no., street level
2016 Q1
2016 Q1
CHN CN full: premium house no., street level
2014 Q4
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a
Postal
Code
Boundaries
n/a
Postal
Codes
no codes are used
Postal
Code
Format
HERE Map
Content
HERE Map
Content
HERE Map
Content
Yes
Yes
Yes
Y n/a
Y n/a
Y n/a n/a n/a
Y no codes are used
Y n/a
NNNNN
NNNNN
(NNNNN-
NNN)
AANNNN HERE Map
Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
Entry Map
Content
Yes
Yes n/a n/a n/a n/a
Yes n/a
Yes n/a
Y n/a n/a n/a n/a
Y n/a n/a n/a
Y n/a n/a n/a n/a
Y n/a n/a n/a
Y no codes are used
NNNN no codes are used n/a NNNNN no codes are used
Y n/a
Y no codes are used
ANA NAN
NNNN
CCN-
NNNN
Entry Map
Content
HERE Map
Content n/a
Yes
HERE Map
Content
(China Nav2)
Yes n/a n/a
Y n/a n/a n/a n/a
Y
Y
NNNNN
NNNNNNN
(NNN-
NNNN)
NNNNNN
Geocoder API Developer's Guide
► Coverage Information
110
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
available inside China)
China
(Outside
China and self-hosting spec)
Colombia
CHN CN major cities, country
Comoros
Congo
Congo, The
Democratic
Republic of
The
Cook Islands
COL CO full: house no, street level
COM KM major cities, country
COG CG major cities, country
COD CD major cities, country
Costa Rica
COK CK
CRI CR major cities, country full: house no, street level
2014 Q4
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
Cote D'Ivoire
Croatia
Cuba
CIV CI full: house no, street level
2016 Q1
HRV HR full: premium house no., street level
2016 Q1
CUB CU selected streets, cities, country
2016 Q1
Curacao
Cyprus
Czech
Republic
Denmark
Djibouti
CUW CW major cities, country
CYP CY major cities, country
CZE CZ
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1
DNK DK full: premium house no., street level
2016 Q1
DJI DJ major cities, country
2016 Q1
Map Data
Classification
Localized
Address
Labels
Point
Addresses
Postal
Code
Boundaries
Postal
Codes
Postal
Code
Format
Entry Map
Content n/a n/a n/a Y NNNNNN
HERE Map
Content
Entry Map
Content
Entry Map
Content
Entry Map
Content n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a no codes are used no codes are used no codes are used
NNNNNN
Entry Map
Content
HERE Map
Content n/a n/a n/a n/a
HERE Map
Content
HERE Map
Content
Intermediate
Map Content
Entry Map
Content
Entry Map
Content
HERE Map
Content n/a
Yes n/a n/a n/a
Yes
HERE Map
Content
Entry Map
Content
Yes n/a
Y n/a n/a n/a
Y n/a
Y n/a n/a n/a
Y n/a n/a n/a
Y n/a
Y n/a no codes are used
Y NNNNN
(NNNN until
2007) no codes are used
Y NNNNN n/a NNNNN no codes are used n/a NNNN
Y
Y no codes are used
NNNNN
(NNN
NN)
NNNN
Geocoder API Developer's Guide
► Coverage Information
111
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Dominica
Dominican
Republic
Ecuador
Egypt
El Salvador
Equatorial
Guinea
Eritrea
Estonia
Ethiopia
Falkland
Islands
(Malvinas)
Faroe Islands
Fiji
Finland
France
French
Polynesia
Gabon
DMA DM major cities, country
DOM DO selected streets, cities, country
ECU EC selected streets, cities, country
2016 Q1
2016 Q1
2016 Q1
EGY EG
SLV SV full: premium house no., street level
2016 Q1 selected streets, cities, country
2016 Q1
2016 Q1 GNQ GQ major cities, country
ERI ER major cities, country
2016 Q1
EST EE
ETH ET
FLK FK full: premium house no., street level
2016 Q1
2016 Q1 major cities, country major cities, country
2016 Q1
FRO FO
FJI
FIN
FRA
FJ
French Guiana GUF GF
PYF
FI
FR
PF
GAB GA major cities, country major cities, country
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1 major cities, country
2016 Q1
Entry Map
Content
Entry Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Entry Map
Content
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a n/a n/a Intermediate
Map Content
Intermediate
Map Content n/a n/a
Yes Y HERE Map
Content
Intermediate
Map Content
Entry Map
Content
Entry Map
Content n/a n/a n/a n/a n/a n/a
HERE Map
Content
Entry Map
Content
Entry Map
Content
Yes n/a n/a
Y n/a n/a
Postal
Code
Boundaries
n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a
Postal
Codes
Postal
Code
Format
no codes are used
Y NNNNN n/a n/a n/a n/a n/a
NNNNNN
NNNNN
1101 no codes are used no codes are used
Y NNNNN
NNNN
Yes n/a n/a n/a
AAAANAA one code:
FIQQ
1ZZ
NNN n/a
Yes
Yes n/a n/a n/a n/a
Y
Y
Y n/a n/a n/a
Y
Y n/a n/a n/a no codes are used
Y
Y
Y n/a n/a
NNNNN
NNNNN
973NN
987NN
NN [city name]
NN
Geocoder API Developer's Guide
► Coverage Information
112
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Gambia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Grenada
Guadeloupe
Guam
Guatemala
Guernsey
GMB GM major cities, country
GEO GE major cities, country
2016 Q1
2016 Q1
DEU DE full: premium house no., street level
2016 Q1
GHA GH selected streets, cities, country
GIB GI full: premium house no., street level
2016 Q1
2016 Q1
GRC GR 2016 Q1
GRL GL full: house no, street level major cities, country
2016 Q1
GRD GD major cities, country
2016 Q1
GLP GP full: premium house no., street level
2016 Q1
GUM GU major cities, country
2016 Q1
2016 Q1 GTM GT selected streets, cities, country
GGY GG full: house no, street level
2016 Q1
Guinea GIN GN major cities, country
Guinea-Bissau GNB GW major cities, country
Guyana GUY GY
Haiti
Honduras
HTI HT selected streets, cities, country major cities, country
HND HN selected streets, cities, country
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
Entry Map
Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
(Included in UK map product)
Entry Map
Content
Entry Map
Content
Intermediate
Map Content
Entry Map
Content
Intermediate
Map Content
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a
Yes n/a Entry Map
Content
HERE Map
Content
Yes Y n/a n/a Intermediate
Map Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Yes
Yes n/a
Y n/a n/a n/a n/a n/a n/a n/a
Yes n/a n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a
Postal
Code
Boundaries
n/a n/a
Y n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
Postal
Codes
Y no codes are used n/a GX11
1AA
Y NNN NN n/a no codes are used
Y 971NN n/a n/a
Y n/a
Postal
Code
Format
no codes are used n/a NNNN
NNNNN
NNNN
NNNNN
NNNNN
AAN
NAA,
AANN
NAA no codes are used n/a NNNN no codes are used n/a NNNN
NNNNN
Geocoder API Developer's Guide
► Coverage Information
113
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Hong Kong
Hong Kong
(self-hosting spec)
Hungary
HKG HK
Iceland
India
Indonesia
Iran (Islamic
Republic of)
Iraq
Ireland
Isle of Man
Israel
Italy
Jamaica
Japan
Jersey
HKG HK full: premium house no., street level
2015 Q3 full: premium house no., street level
2015 Q3
HUN HU full: premium house no., street level
2016 Q1
ISL IS full: house no, street level
2016 Q1
IND IN
IDN
IRN
ID
IR full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1
IRQ IQ
IRL
IMN
IE
IM selected streets, cities, country
2016 Q1 full: premium house no., street level
2016 Q1 full: house no, street level
2016 Q1
ISR
ITA
IL
IT
JAM JM full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1 selected streets, cities, country
2016 Q1
2016 Q1 JPN JP major cities, country
JEY JE full: house no, street level
2016 Q1
Map Data
Classification
HERE Map
Content
Localized
Address
Labels
Point
Addresses
Yes Y
HERE Map
Content
Yes Y
Postal
Code
Boundaries
n/a n/a
Postal
Codes
no codes are used no codes are used
Postal
Code
Format
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
HERE Map
Content
(Included in UK map product)
HERE Map
Content
HERE Map
Content
Intermediate
Map Content
Yes
Yes
Yes
Yes n/a n/a
Yes
Yes n/a
Yes n/a
Y n/a
Y
Y n/a n/a
Y n/a
Y
Y n/a
Y
Y n/a n/a n/a n/a
Y n/a
Y
Y n/a
Y
Y
Y
Y n/a n/a no codes are used
Y
Y
Y
Y
NNNN
NNN
NNNNNN,
NNNNN
NNNNN-
NNNNN
NNNNN
CCN
NAA,
CCNN
NAA
NNNNNNN
Entry Map
Content
HERE Map
Content
(Included in UK map product) n/a
Yes n/a n/a n/a n/a n/a
Y
NNNNN
Before suspension:
CCAAANN
NNNNNNN
(NNN-
NNNN)
CCN NAA
Geocoder API Developer's Guide
► Coverage Information
114
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Jordan
Kazakhstan
Kenya
Kiribati
Korea,
Democratic
People's
Republic of
Korea,
Republic of
Kosovo
Kuwait
Kyrgyzstan
Lao People's
Democratic
Republic
Latvia
Lebanon
Lesotho
Liberia
Libyan Arab
Jamahiriya
JOR JO
KAZ KZ
KEN KE full: premium house no., street level
2016 Q1 full: house no, street level
2016 Q1
KIR
PRK
KI
KP
KOR KR major cities, country
KOS KX full: house no, street level major cities, country major cities, country full: house no, street level
KWT KW full: house no, street level
KGZ KG selected streets, cities, country
LAO LA
LVA LV
LBN LB
LSO LS
LBR
LBY
LR
LY major cities, country
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1
2016 Q1 full: house no, street level full: house no, street level
2016 Q1 major cities, country selected streets, cities, country
2016 Q1
2015 Q1
Map Data
Classification
HERE Map
Content
Localized
Address
Labels
Point
Addresses
Yes n/a
Postal
Code
Boundaries
n/a n/a Y n/a
Postal
Codes
Postal
Code
Format
no codes are used
NNNNN
- only for post boxes
Y NNNNNN HERE Map
Content
HERE Map
Content n/a n/a n/a
Entry Map
Content
Entry Map
Content n/a n/a n/a n/a n/a n/a no codes are used
NNNNN
- only for post boxes no codes are used no codes are used
Entry Map
Content n/a n/a
HERE Map
Content
HERE Map
Content
Intermediate
Map Content
Entry Map
Content
Yes
Yes n/a n/a
HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
Yes n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a
Y n/a n/a
NNNNNN
(NNN-
NNN)
(1988~2015)
NNNNN
NNNNN
NNNNNN
NNNNN
CC-
NNNN
NNNN
NNNN
NNN
NNNN
NNNNN
Geocoder API Developer's Guide
► Coverage Information
115
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Liechtenstein
Lithuania
Luxembourg
Macau
Macau (selfhosting spec)
Macedonia,
The Former
Yugoslav
Republic of
Madagascar
Malawi
Malaysia
Maldives
Mali
Malta
LIE LI
LTU LT full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1
LUX LU full: premium house no., street level
2016 Q1
MAC MO full: premium house no., street level
2015 Q3
MAC MO full: premium house no., street level
2015 Q3
MKD MK full: premium house no., street level
2016 Q1
MDG MG major cities, country
2016 Q1
MWI MW selected streets, cities, country
2016 Q1
MYS MY full: premium house no., street level
2016 Q1
2016 Q1 MDV MV selected streets, cities, country
MLI ML major cities, country
2016 Q1
MLT MT full: premium house no., street level
2016 Q1
Marshall
Islands
Martinique
Mauritania
Mauritius
Mayotte
MHL MH major cities, country
2016 Q1
MTQ MQ full: premium house no., street level
2016 Q1
2016 Q1 MRT MR major cities, country
MUS MU major cities, country
2016 Q1
MYT YT full: house no, street level
2016 Q1
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
Intermediate
Map Content
Entry Map
Content
HERE Map
Content
Map Data
Classification
HERE Map
Content
Localized
Address
Labels
Point
Addresses
Yes Y
Yes Y HERE Map
Content
HERE Map
Content
Yes Y
HERE Map
Content
HERE Map
Content
HERE Map
Content
Yes
Yes
Yes
Y
Y
Y
Postal
Code
Boundaries
Y
Y
Y n/a n/a n/a
Postal
Codes
Y
Y
Y
Postal
Code
Format
NNNN
CC-
NNNNN
NNNN no codes are used no codes are used n/a NNNN n/a n/a
Yes n/a n/a
Yes
Entry Map
Content
HERE Map
Content
Entry Map
Content
Entry Map
Content
HERE Map
Content n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a
Y n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a NNN no codes are used
Y NNNNN n/a NNNN,
NNNNN no codes are used
Y AAANNNN
(AAA
NNNN) n/a NNNNN
Y NNNNN no codes are used n/a NNNNN n/a NNNNN
Geocoder API Developer's Guide
► Coverage Information
116
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Mexico
Micronesia,
Federated
States of
MEX MX full: premium house no., street level
2016 Q1
FSM FM major cities, country
2016 Q1
Moldova,
Republic of
MDA MD selected streets, cities, country
2016 Q1
Monaco
Mongolia
Montenegro
Montserrat
Morocco
Mozambique
Myanmar
Namibia
Nauru
Nepal
Netherlands
New
Caledonia
New Zealand
Nicaragua
MCO MC full: premium house no., street level
2016 Q1
2016 Q1 MNG MN selected streets, cities, country
MNE ME full: house no, street level
2016 Q1
MSR MS major cities, country
MAR MA full: house no, street level
2016 Q1
2016 Q1
2016 Q1 MOZ MZ full: house no, street level
MMR MM major cities, country
NAM NA full: house no, street level
NRU NR major cities, country
NPL NP selected streets, cities, country
2016 Q1
2016 Q1
2016 Q1
2016 Q1
NLD NL full: premium house no., street level
2016 Q1
NCL NC major cities, country
NZL NZ full: premium house no., street level
2016 Q1
2016 Q1
NIC NI selected streets, cities, country
2016 Q1
Map Data
Classification
HERE Map
Content
Localized
Address
Labels
Point
Addresses
Yes Y
Entry Map
Content n/a n/a
Postal
Code
Boundaries
Y n/a
Postal
Codes
Y n/a
HERE Map
Content
Yes n/a
Y n/a
Y n/a
Y
Postal
Code
Format
NNNNN
NNNNN or
NNNNN-
NNNN
CCNNNN
(CC-
NNNN)
NNNNN HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
Intermediate
Map Content
Yes n/a
Yes n/a
Yes
Yes n/a
Yes n/a n/a
Yes n/a
Yes n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a
Y n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a
Y n/a
Y n/a n/a
Y n/a n/a n/a n/a n/a no codes are used n/a
Y n/a
Y n/a
NNNNN
NNNNN
MSR
1110-1350
NNNNN
NNNN
NNNNN
NNNNN
NNNNN
NNNN
988NN
NNNN
NNNNN
Geocoder API Developer's Guide
► Coverage Information
117
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Niger
Nigeria
NER NE major cities, country
NGA NG selected streets, cities, country
Niue NIU NU major cities, country
Norfolk Island NFK NF full: house no, street level
Northern
Mariana
Islands
Norway
Oman
Pakistan
Palau
MNP MP major cities, country
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
NOR NO full: premium house no., street level
2016 Q1
OMN OM full: house no, street level
2016 Q1
PAK PK major cities, country
PLW PW major cities, country
PSE PS selected streets, cities, country
2013 Q1
2016 Q1
2016 Q1 Palestinian
Territory,
Occupied
Panama
Papua New
Guinea
Paraguay
Peru
Philippines
Pitcairn
PAN PA
PNG PG
PRY
PER
PY
PE
PHL PH
PCN PN full: premium house no., street level
2016 Q1 major cities, country
2016 Q1 selected streets, cities, country full: house no, street level
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a
Yes n/a Intermediate
Map Content
Entry Map
Content n/a n/a
HERE Map
Content
(Included in
Australia map product)
Entry Map
Content
Yes n/a n/a n/a
Postal
Code
Boundaries
n/a n/a n/a
Y n/a
Postal
Codes
n/a n/a n/a
Postal
Code
Format
NNNN
NNNNNN no codes are used
Y NNNN
NNNNN
HERE Map
Content
HERE Map
Content
Yes
Yes n/a
Y n/a n/a
Y n/a n/a
Y no codes are used n/a
NNNN
NNN only for post boxes
NNNNN Entry Map
Content
Entry Map
Content
HERE Map
Content n/a n/a n/a n/a n/a n/a n/a n/a
NNNNN
NNN
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
HERE Map
Content
HERE Map
Content
Entry Map
Content n/a n/a n/a n/a n/a n/a
Y n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a
NNNNNN
NNN
NNNN
NNNNN
NNNN
AAAANAA one code:
Geocoder API Developer's Guide
► Coverage Information
118
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Poland POL PL full: premium house no., street level
2016 Q1
Portugal
Puerto Rico
Qatar
Reunion
Romania
Russian
Federation
Rwanda
Saint
Barth#lemy
Saint Helena
PRT
PRI
PT
PR full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1
QAT QA full: house no, street level
REU RE full: premium house no., street level
2016 Q1
2016 Q1
ROU RO full: premium house no., street level
2016 Q1
RUS RU full: premium house no., street level
2016 Q1
2016 Q1 RWA RW full: house no, street level
BLM BL
SHN SH full: house no, street level major cities, country
2016 Q1
2016 Q1
Saint Kitts and Nevis
Saint Lucia
Saint Martin
Saint Pierre and Miquelon
Saint Vincent and The
Grenadines
Samoa
KNA KN
LCA LC
MAF MF major cities, country
SPM PM major cities, country
VCT VC selected streets, cities, country major cities, country selected streets, cities, country
WSM WS major cities, country
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
2016 Q1
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Map Data
Classification
Localized
Address
Labels
Point
Addresses
Postal
Code
Boundaries
Postal
Codes
Postal
Code
Format
HERE Map
Content
Yes
Yes
Y
Y
Y
Y
Y
Y
PCRN
1ZZ
NNNNN
(NN-
NNN)
NNNN n/a
Yes n/a
Yes
Yes n/a n/a n/a
Y n/a
Y
Y
Y n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a n/a
Y no codes are used
Y
Y
Y no codes are used
Y
NNNNN
974NN
NNNNNN
NNNNNN
97133
Intermediate
Map Content
Entry Map
Content
Entry Map
Content
Entry Map
Content
Intermediate
Map Content n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a STHL
1ZZ or
TDCU
1ZZ no codes are used no codes are used n/a 97150 n/a n/a
97500
CCNNNN
Entry Map
Content n/a n/a n/a n/a
Geocoder API Developer's Guide
► Coverage Information
119
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
San Marino
Sao Tome and
Principe
Saudi Arabia
Senegal
Serbia
Seychelles
Sierra Leone
Singapore
Sint Maarten
Slovakia
Slovenia
SMR SM full: house no,
STP ST
SAU SA
SEN SN
SRB RS
SYC SC
SLE SL
SGP SG
SXM SX
SVK SK street level major cities, country
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1 major cities, country
2016 Q1 full: premium house no., street level
2016 Q1 major cities, country
2016 Q1 full: premium house no., street level
2016 Q1
SVN SI full: premium house no., street level
2016 Q1
Solomon
Islands
Somalia
South Africa
SLB SB
SOM SO major cities, country
ZAF ZA major cities, country full: premium house no., street level
2016 Q1
2016 Q1
2015 Q4
Entry Map
Content
HERE Map
Content
Entry Map
Content
Entry Map
Content
HERE Map
Content
Entry Map
Content
HERE Map
Content
Map Data
Classification
Localized
Address
Labels
Point
Addresses
Yes n/a HERE Map
Content
(Included in
Italy map product) n/a n/a Entry Map
Content
HERE Map
Content
Yes Y
Postal
Code
Boundaries
Y n/a n/a n/a n/a n/a
Postal
Codes
Y
Postal
Code
Format
4789N no codes are used
Y NNNNN for PO
Boxes.
NNNNN-
NNNN for home delivery.
n/a NNNNN
HERE Map
Content
Entry Map
Content
Entry Map
Content
HERE Map
Content
Yes n/a n/a
Yes n/a
Yes
Yes n/a n/a
Yes
Y n/a n/a
Y n/a
Y
Y n/a n/a
Y
Y n/a n/a n/a n/a
Y
Y n/a n/a
Y
Y no codes are used no codes are used
Y no codes are used
Y
Y no codes are used n/a AA
NNNN
(CC-
NNNN)
Y
NNNNN
NNNNNN
NNNNN
(NNN
NN)
NNNN
Geocoder API Developer's Guide
► Coverage Information
120
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
South Sudan
Spain
Sri Lanka
Sudan
Suriname
Svalbard and
Jan Mayen
Islands
Swaziland
Sweden
Switzerland
Syrian Arab
Republic
Taiwan
Tajikistan
SSD SS
ESP
LKA
ES
LK
SDN SD
SUR SR
SJM SJ
SWZ SZ
SWE SE major cities, country
2015 Q1 full: premium house no., street level
2016 Q1 selected streets, cities, country
2016 Q1
2015 Q1 selected streets, cities, country selected streets, cities, country major cities, country
2016 Q1
2016 Q1 full: house no, street level
2016 Q1 full: premium house no., street level
2016 Q1
CHE CH full: premium house no., street level
2016 Q1
SYR SY selected streets, cities, country
2015 Q1
TWN TW full: premium house no., street level
2016 Q1
TJK TJ 2016 Q1
TZA TZ major cities, country selected streets, cities, country
2016 Q1 Tanzania,
United
Republic of
Thailand
Timor-Leste
Togo
Tokelau
THA TH
TLS
TGO TG
TKL
TL
TK full: premium house no., street level
2016 Q1
2016 Q1 major cities, country major cities, country
2016 Q1 major cities, country
2016 Q1
HERE Map
Content
HERE Map
Content
HERE Map
Content
Entry Map
Content
Entry Map
Content
Entry Map
Content
Yes
Yes
HERE Map
Content
Intermediate
Map Content
HERE Map
Content
Entry Map
Content
Intermediate
Map Content
Yes n/a
Yes n/a n/a
Yes n/a n/a n/a
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a
Yes Y HERE Map
Content
Intermediate
Map Content n/a n/a
Intermediate
Map Content
Intermediate
Map Content
Entry Map
Content n/a n/a n/a n/a n/a n/a
Postal
Code
Boundaries
n/a
Y n/a n/a n/a n/a
Postal
Codes
n/a
Y n/a n/a
Postal
Code
Format
NNNNN
NNNNN
NNNNN no codes are used n/a NNNN n/a n/a Y ANNN
Y
Y n/a
Y n/a n/a
Y n/a n/a n/a
Y
Y n/a
Y n/a n/a n/a n/a n/a n/a
Y
Y no codes are used
Y n/a no codes are used
Y no codes are used no codes are used no codes are used
NNNNN
(NNN
NN)
NNNN
NNNNN
NNNNNN
NNNNN
Geocoder API Developer's Guide
► Coverage Information
121
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Tonga
Trinidad and
Tobago
Tunisia
TON TO major cities, country
TTO TT selected streets, cities, country
2016 Q1
2016 Q1
TUN TN selected streets, cities, country
2016 Q1
Turkey TUR TR full: premium house no., street level
2016 Q1
Turkmenistan TKM TM major cities, country
2016 Q1
2016 Q1 Turks and
Caicos Islands
TCA TC
Tuvalu TUV TV
Uganda
Ukraine major cities, country major cities, country
2016 Q1
UGA UG selected streets, cities, country
UKR UA
ARE AE
2016 Q1 full: premium house no., street level
2016 Q1 full: premium house no., street level
2016 Q1 United Arab
Emirates
United
Kingdom
GBR GB
United States USA US full: premium house no., street level full: premium house no., street level
2016 Q1
2016 Q1
Uruguay
Uzbekistan
Vanuatu
Vatican City
State (Holy
See)
Venezuela
URY UY
UZB UZ
VUT VU
VAT VA full: house no, street level selected streets, cities, country major cities, country full: house no, street level
VEN VE
2016 Q1
2016 Q1
2016 Q1
2016 Q1 full: premium house no., street level
2016 Q1
Map Data
Classification
Entry Map
Content
Localized
Address
Labels
Point
Addresses
n/a n/a n/a n/a Intermediate
Map Content
Intermediate
Map Content n/a n/a
Yes Y HERE Map
Content
Entry Map
Content
Entry Map
Content
Entry Map
Content n/a n/a n/a n/a n/a n/a
Intermediate
Map Content
HERE Map
Content
HERE Map
Content
HERE Map
Content
HERE Map
Content n/a
Yes
Yes
Yes
Yes n/a
Y
Y
Y
Y
Postal
Code
Boundaries
n/a n/a n/a
Y n/a n/a n/a n/a n/a n/a
Y
Y n/a n/a
Postal
Codes
Postal
Code
Format
no codes are used n/a NNNNNN n/a
Y n/a
NNNN
NNNNN
NNNNNN n/a TKCA
1ZZ no codes are used no codes are used n/a NNNNN no codes are used
Y A[A]N[A/
N]
Y
Y
NNNNN
(optionally
NNNNN-
NNNN)
NNNNN HERE Map
Content
Intermediate
Map Content
Entry Map
Content
HERE Map
Content
(Included in
Italy map product)
HERE Map
Content n/a n/a n/a n/a n/a n/a n/a n/a
Y n/a n/a
Y n/a n/a NNN
NNN no codes are used
Y 120 n/a NNNN or
NNNN A
Geocoder API Developer's Guide
► Coverage Information
122
Country/Area ISO
A3
ISO
A2
Coverage Level Map Release
Vietnam
Virgin Islands
(British)
Virgin Islands
(U.S.)
VNM VN
VGB VG
VIR VI full: premium house no., street level
2016 Q1 major cities, country full: house no, street level
Wallis and
Futuna Islands
WLF WF major cities, country
Western
Sahara
ESH EH full: house no, street level
2016 Q1
2016 Q1
2016 Q1
2016 Q1
Yemen
Zambia
YEM YE selected streets, cities, country
ZMB ZM selected streets, cities, country
2015 Q1
2016 Q1
Zimbabwe ZWE ZW selected streets, cities, country
Åland Islands ALA AX full: premium house no., street level
2016 Q1
2016 Q1
Map Data
Classification
HERE Map
Content
Localized
Address
Labels
Point
Addresses
n/a Y n/a n/a Entry Map
Content
HERE Map
Content
Yes n/a
Entry Map
Content
HERE Map
Content
(included in
Morocco map product)
Intermediate
Map Content n/a n/a n/a n/a n/a n/a
Intermediate
Map Content
Intermediate
Map Content n/a n/a
HERE Map
Content
(Included in
Skandinavia map product) n/a n/a n/a
Y
Postal
Code
Boundaries
n/a n/a
Y n/a n/a n/a n/a n/a
Y
Postal
Codes
n/a n/a
Y n/a n/a
Postal
Code
Format
NNNNNN
CCNNNN
NNNNN
986NN no codes are used n/a NNNNN no codes are used
Y NNNNN
(CC-
NNNNN from abroad)
Coverage Categories
The 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.
Geocoder API Developer's Guide
► Coverage Information
123
• 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/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)
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
Geocoder API Developer's Guide
► Coverage Information
124
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.
Geocoder API Developer's Guide
► Coverage Information
125
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",
Geocoder API Developer's Guide
► Coverage Information
126
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 Geocoder
Coordinates
Political View
Support
Northern Arunachal Pradesh 28.6512526, 95.2272352
default, IND
Falkland Islands
Description
Default = Neutral territory (empty response)
IND = Part of the Indian State of Arunachal
Pradesh
-51.6958016, -57.8529192 default, ARG
Default = Falklands Islands
ARG = Part of Argentina’s “Tierra Del Fuego”
South Georgia and South
Sandwich Islands
(Indian-Chinese
Border)Kaurik
-54.2915196, -36.4940174 default, ARG
Default = South Georgia And The South
Sandwich Islands
ARG = Part of Argentina’s “Tierra Del Fuego”
32.2112327, 78.5563334
default, IND
Default = Neutral territory (empty response)
IND = Part of the Indian State of Himachal
Pradesh
(Indian-Chinese
Border)Lapthal
30.7338287, 80.1058805
default, IND
Default = Neutral territory (empty response)
Geocoder API Developer's Guide
► Coverage Information
127
Name Example Reverse Geocoder
Coordinates
Political View
Support
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,
PAK
Default = 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,
PAK
Default = Neutral territory (empty response)
IND = Part of the Indian State of Jammu &
Kashmir
PAK = Seen as a part of Pakistan
(Kashmir)Gilgit-Baltistan
35.8260676, 75.0474641
default, IND,
PAK
Default = Neutral territory (empty response)
IND = Part of the Indian State of Jammu &
Kashmir
PAK = Seen as a part of Pakistan
(Kashmir)Pa-li-chia-ssu
33.257519, 79.2483097
default, IND,
PAK
Default = Neutral territory (empty response)
IND = Part of the Indian State of Jammu &
Kashmir
PAK = Seen as a part of Pakistan
(Kashmir)Shaksam Valley
36.0928479, 76.3108918
default, IND,
PAK
Default = Neutral territory (empty response)
IND = Part of the Indian State of Jammu &
Kashmir
PAK = Seen as a part of China
(Kashmir)State of Jammu &
Kashmir
33.5625116, 76.9892775
default, IND,
PAK
Default = Neutral territory (empty response)
IND = Part of the Indian State of Jammu &
Kashmir
PAK = Seen as a part of Pakistan
(Golan Heights) UN Buffer
Zone
33.2053155, 35.8740408
default Default = Neutral territory (empty response)
(Argentinian-Chilean
Border)South Patagonian Ice
Field
Paracel Islands
-49.4286077, -73.2129860 default
16.2438621, 111.7561099
default, VNM
Default = Neutral territory (empty response)
Default = Neutral territory (empty response)
Geocoder API Developer's Guide
► Coverage Information
128
Name
Spratly Islands
Example Reverse Geocoder
Coordinates
Political View
Support
Description
VNM = Vietnamese Islands
7.6808132, 111.5774475
default, VNM
Default = Neutral territory (empty response)
VNM = Vietnamese Islands
2.8357961, -54.1090861
default
Default = Neutral territory (empty response)
Suriname-French Guiana
Triangle
Suriname-Guyana Triangle
Macclesfield Bank
Scarborough Shoal
James Shoal
Senkaku/Diaoyutai
West Bank
East Jerusalem
Northern Cyprus
Southern Cyprus
Cyprus UN Neutral Zone
Cyprus British Bases
Kinmen Islands
Matsu Islands
Kosovo
Western Sahara
Abu Musa Island
Tunb Islands
2.1528005, -57.3365359
15.8434538, 114.3056814
15.4895344, 113.8210957
3.973889, 112.348889
default default default default
25.7446986, 123.4709205
default
31.9998544, 35.2998283
default
31.766327, 35.2453382
default, ISR
Default = Neutral territory (empty response)
Default = Neutral territory (empty response)
Default = Neutral territory (empty response)
Default = Neutral territory (empty response)
Default = Neutral territory (empty response)
Default = No Country
Default = As part of West Bank
ISR = As part of Israel
35.2453975, 33.3968783
default, GRC,
TUR
Default = Turkish-Cypriot Administered Area
GRC = As a part of Cyprus (Republic of Cyprus)
TUR = Turkish Republic of Northern Cyprus
35.0441914, 33.1554733
default, TUR
35.1691202, 33.2394362
default
34.6024439, 32.9538086
default
24.4642701, 118.3791237
default
26.2238182, 119.9946911
default
42.6718168, 21.1624711
default
Default = Cyprus (Republic of Cyprus)
TUR = Greek Cypriot Admin of Southern
Cyprus
Default = UN Neutral Zone
Default = British Sovereign BSB Areas
Default = Taiwanese Islands
Default = Taiwanese Islands
Default = No Country
24.118844, -13.7725855
default, MAR
Default = Neutral territory (empty response)
MAR = As a part of Morocco
25.8871195, 55.0354848
default, ARE
Default = Neutral territory (empty response)
ARE = As a part of the United Arab Emirates default, ARE
26.2623118, 55.308378
25.8871195, 55.0354848
Default = Neutral territory (empty response)
ARE = As a part of the United Arab Emirates
Geocoder API Developer's Guide
► Coverage Information
129
Name
Ilemi Triangle
Halaib Triangle
Crimea
Kuril Islands (Shikotan,
Iturup, Habomai, and
Kunashir)
Liancourt Rocks
Example Reverse Geocoder
Coordinates
Political View
Support
4.7502929, 35.2197958
default, KEN
Description
Default = Neutral territory (empty response)
KEN = As a part of Kenya
22.2363029, 35.1661332
default, EGY
44.95748, 34.10827
default, RUS
Default = Neutral territory (empty response)
EGY = As a part of Egypt
Default = Part of Ukraine
RUS = As part of Russia
45.1279501, 147.80728
(Iturup) default, RUS
Default = Neutral territory (empty response)
RUS = As part of Russia
37.2393599, 131.8758573
default Default = Neutral territory (empty response)
Unduh
Tautan publik diperbarui
Tautan publik ke obrolan Anda telah diperbarui. You may view and manage your chat links after registration here.
Tautan publik dokumen
Iklan
