Geocoder API
Developer's Guide
Version 6.2.48
Geocoder API Developer's Guide
► Contents
2
Contents
Legal Notices..........................................................................................................................................................4
Document Information.................................................................................................................................... 5
Chapter 1: Overview................................................................................................................................. 6
What is the Geocoder API?...........................................................................................................................7
Why use the Geocoder API?......................................................................................................................... 7
Chapter 2: Quick Start........................................................................................................................... 8
Making Your First Requests......................................................................................................................... 9
Geocoding......................................................................................................................................................... 9
Reverse Geocoding...................................................................................................................................... 11
Multi Reverse Geocoding............................................................................................................................ 13
Landmark Geocoding................................................................................................................................... 15
Chapter 3: User Guide......................................................................................................................... 18
Acquiring Credentials...................................................................................................................................19
Constructing a Request.............................................................................................................................. 19
Customer Integration Testing.......................................................................................................20
Request Encoding............................................................................................................................ 20
Key Concepts.................................................................................................................................................20
Using Backwards Incompatible Features....................................................................................21
Customizing the Response with Attribute Switches................................................................ 23
Examples......................................................................................................................................................... 24
Geocoding.......................................................................................................................................... 24
Reverse Geocoding.......................................................................................................................... 31
Landmark Geocoding...................................................................................................................... 33
Service Support............................................................................................................................................ 35
Geocoder API Developer's Guide
► Contents
3
Chapter 4: API Reference................................................................................................................. 36
Resources and Parameters........................................................................................................................ 37
Geocode Resource........................................................................................................................... 37
Reverse Geocode Resource........................................................................................................... 42
Multi Reverse Geocode Resource................................................................................................ 45
Landmark Geocode Resource....................................................................................................... 49
Additional Data Parameter............................................................................................................ 54
Response Data Types..................................................................................................................................55
Search Response.............................................................................................................................. 56
Multi Reverse Geocode Response................................................................................................64
Base Data Types.............................................................................................................................. 65
Response Schemas and Examples........................................................................................................... 71
XML Schemas.................................................................................................................................... 71
Response Examples......................................................................................................................... 72
Geocoder API Developer's Guide
► Legal Notices
4
Legal Notices
© 2013 HERE. 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 and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States
and other countries.
Other trade names are trademarks or registered trademarks of their 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. Nokia does not warrant that the content is error
free and Nokia 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 Nokia's
negligence, shall Nokia 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 Nokia or an authorized representative has been advised of the
possibility of such damages.
Geocoder API Developer's Guide
► Document Information
Document Information
Product
Name:
Geocoder API
Version:
Version 6.2.48
Document
Name:
Geocoder API Developer's Guide
Id:
1e55747-1385047298
Status:
FINAL
Date:
2013-Nov-21, 15:22 (GMT)
5
Geocoder API Developer's Guide
► Overview
Chapter
1
Overview
Topics:
•
What is the Geocoder API?
•
Why use the Geocoder API?
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?
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, "100 Market St, in
37.84491,-122.5040;37.7267,-122.3598").
Find areas such as cities, states, counties, countries and postal codes (for example, "Springfield,
IL", "London", "California").
Find landmarks of national importance (for example, "Eiffel Tower").
Get addresses or area information for a coordinate (for example, "41.8838 -87.6389")
Geocoder API Developer's Guide
► Quick Start
Chapter
2
Quick Start
Topics:
•
Making Your First Requests
The Geocoder API is a web API that you access using a REST
interface. This article contains example requests that you can run
•
Geocode Request
to see how the service works.
•
Reverse Geocode Request
•
Multi Reverse Geocode Request
•
Landmark Geocode Request
8
Geocoder API Developer's Guide
► Quick Start
9
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. You can use the demo credentials in the
examples for testing, but must substitute them with your own unique values in your website or
application. See Acquiring Credentials on page 19 for more information.
The examples in this guide use the Customer Integration Testing (CIT) environment. This environment
allows you to test your software. For production please use the production environment. See
Constructing a Request on page 19 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
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 Chicago.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&searchtext=425 W Randolph Chicago
Alternatively, specify individual parts of the address, such as housenumber, street, etc.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&housenumber=425
Geocoder API Developer's Guide
► Quick Start
10
&street=W Randolph
&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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&searchtext=Berlin, USA
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&searchtext=Berlin
Geocoder API Developer's Guide
► Quick Start
11
&country=USA
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.
http://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&prox=50.111,8.680,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 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.
<Result>
<Relevance>1.0</Relevance>
<Distance>1.2</Distance>
<MatchLevel>houseNumber</MatchLevel>
<MatchQuality>
<Country>1.0</Country>
<State>1.0</State>
<County>1.0</County>
<City>1.0</City>
<Street>1.0</Street>
<HouseNumber>1.0</HouseNumber>
<PostalCode>1.0</PostalCode>
Geocoder API Developer's Guide
► Quick Start
</MatchQuality>
<Location>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>50.1114661</Latitude>
<Longitude>8.680358</Longitude>
</DisplayPosition>
<MapView>
<TopLeft>
<Latitude>50.1125903</Latitude>
<Longitude>8.6786051</Longitude>
</TopLeft>
<BottomRight>
<Latitude>50.1103419</Latitude>
<Longitude>8.682111</Longitude>
</BottomRight>
</MapView>
<Address>
<Label>Berliner Straße 56, 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>56</HouseNumber>
<PostalCode>60311</PostalCode>
<AdditionalData key="CountryName">Deutschland</AdditionalData>
<AdditionalData key="StateName">Hessen</AdditionalData>
</Address>
<MapReference>
<ReferenceId>778448681</ReferenceId>
<SideOfStreet>neither</SideOfStreet>
</MapReference>
</Location>
</Result>
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 ignored in this case.
http://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&prox=50.111,8.680,100
&mode=retrieveAreas
The response includes
•
Relevance is always 1.0 for reverse geocode results.
•
MatchLevel shows the level of the most precise area information available for the match,
district, city or a higher admininistrative level.
•
Location information in terms of:
◦
◦
LocationType which is one of point, area or line.
Latitude and longitude of the address.
12
Geocoder API Developer's Guide
► Quick Start
◦
◦
13
Latitude and longitude of the area to display the address on a map (MapView).
Address (only the area information, no street or house number).
<Result>
<Relevance>0.57</Relevance>
<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>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>50.1115</Latitude>
<Longitude>8.6805</Longitude>
</DisplayPosition>
<MapView>
<TopLeft>
<Latitude>50.1204932</Latitude>
<Longitude>8.6664765</Longitude>
</TopLeft>
<BottomRight>
<Latitude>50.1025068</Latitude>
<Longitude>8.6945235</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>
</Address>
</Location>
</Result>
Multi Reverse Geocode Request
Retrieve street address or area information for up to one hundred coordinates with one multi reverse
geocoding HTTP POST request. The method is synchronous which means that the reverse geocoding
results are contained in the response.
The body of the HTTP POST request contains the coordinates and optional radius in the prox
parameter and an optional numeric identifier in the id parameter as plain text, one line per pair of
coordinates. The identifier associates each result with the corresponding input. If no id is provided
the system creates one starting with 0.
Geocoder API Developer's Guide
► Quick Start
14
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.
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:
http://reverse.geocoder.cit.api.here.com/6.2/multi-reversegeocode.xml
?mode=retrieveAddresses
&maxresults=1
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
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
"http://reverse.geocoder.cit.api.here.com/6.2/multi-reversegeocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&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
15
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>2013-01-21T16:20:11.694Z</Timestamp>
</MetaInfo>
<Item>
<ItemId>1</ItemId>
<Result>
<Relevance>1.0</Relevance>
<Distance>0.9</Distance>
<MatchLevel>houseNumber</MatchLevel>
<MatchQuality>
<Country>1.0</Country>
<State>1.0</State>
<County>1.0</County>
<City>1.0</City>
<Street>1.0</Street>
<HouseNumber>1.0</HouseNumber>
<PostalCode>1.0</PostalCode>
Landmark Geocode Request
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:
http://geocoder.cit.api.here.com/6.2/search.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&searchtext=Ferry Building, San Francisco
The result is a Place with a PlaceId, a Name, and Location information.
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4">
<Response>
<MetaInfo>
<Timestamp>2013-03-26T12:28:07.981Z</Timestamp>
</MetaInfo>
<View xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns2:SearchResultsViewType">
<ViewId>0</ViewId>
Geocoder API Developer's Guide
► Quick Start
16
<Result>
<Relevance>1.0</Relevance>
<MatchQuality>
<City>1.0</City>
</MatchQuality>
<Place>
<PlaceId>17553305</PlaceId>
<Name>Ferry Building</Name>
<Category>
<CategoryId>7999</CategoryId>
<CategorySystemId>facility</CategorySystemId>
</Category>
<Suppliers>
<SupplierId>3</SupplierId>
</Suppliers>
<Locations>
<LocationId>NT_NTMO_POI17553305</LocationId>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>37.7959213</Latitude>
<Longitude>-122.3944168</Longitude>
</DisplayPosition>
<NavigationPosition>
<Latitude>37.7959213</Latitude>
<Longitude>-122.3944168</Longitude>
</NavigationPosition>
<MapView>
<TopLeft>
<Latitude>37.8049145</Latitude>
<Longitude>-122.4057978</Longitude>
</TopLeft>
<BottomRight>
<Latitude>37.7869281</Latitude>
<Longitude>-122.3830359</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>
<Street>The Embarcadero</Street>
<PostalCode>94111</PostalCode>
<AdditionalData key="CountryName">United States</AdditionalData>
<AdditionalData key="StateName">California</AdditionalData>
</Address>
</Locations>
</Place>
</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:
http://geocoder.cit.api.here.com/6.2/search.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
Geocoder API Developer's Guide
► Quick Start
&searchtext=Ferry Building
&country=USA
17
Geocoder API Developer's Guide
► User Guide
18
Chapter
3
User Guide
Topics:
•
Acquiring Credentials
•
Constructing a Request
•
Key Concepts
•
Examples
•
Service Support
The articles in this section provide a guide to using the Geocoder
API.
Geocoder API Developer's Guide
► User Guide
19
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.
To obtain the credentials for an application, please visit http://developer.here.com/get-started for
more details.
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
http://geocoder.api.here.com
Description
Production environment
http://reverse.geocoder.api.here.com
http://geocoder.cit.api.here.com
http://reverse.geocoder.cit.api.here.com
Path
/6.2
Resource
/geocode.json
/geocode.xml
CIT environment: see Customer
Integration Testing on page 20
GET only except for multireversegeocode (POST), specify
request details via query parameters
/reversegeocode.json
/reversegeocode.xml
/multi-reversegeocode.json
/multi-reversegeocode.xml
/search.json
/search.xml
Application Code
&app_code=AJKnXv84fjrb0KIHawS0Tg
Substitute your own unique
app_code
Application Id
&app_id=DemoAppId01082013GAL
Substitute your own unique app_id
Geocoder API Developer's Guide
► User Guide
20
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 Service Support on page
35.
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%F6ln" for "Köln".
An example request for Köln, Germany:
http://geocoder.cit.api.here.com/6.2/geocode.xml
?app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
&searchtext=K%F6ln%2C%20Germany
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="http://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.
Geocoder API Developer's Guide
► User Guide
21
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.
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
Geocoder API Developer's Guide
► User Guide
22
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.
◦
Return the area display point (e.g. the centroid 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 (recommended)
Geocoder API Developer's Guide
► User Guide
23
◦
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.
Please note that the previous list of changes are not the only changes introduced between two
generations. Only changes that might cause conflicts with existing client implementations are tagged
with a specific generation number.
Customizing the Response with Attribute 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
Geocoder API Developer's Guide
► User Guide
24
Table 2: Attribute switches and values
Attribute switch
Values
addressattributes
Comma separated list of which elements are present in the response data.
Enumeration [country, state, county, city, district, street, houseNumber,
postalCode, addressLines, additionalData]
Abbreviated forms: [ctr, sta, cty, cit, dis, str, hnr, pst, aln, add]
On by default: All except addressLines.
Note: The value names are case-sensitive.
locationattributes
Comma separated list of which elements are present in the response data.
Enumeration [address, mapReference, mapView, additionalData, adminIds]
Abbreviated forms: [ar, mr, mv, ad, ai]
adminIds are available with forward geocoding only.
On by default: All for reverse geocoding. All except mapReference for forward geocoding.
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.
responseattributes
Comma separated list of which elements are present in the response data.
Enumeration [performedSearch, matchQuality, matchType, matchCode,
parsedRequest]
Abbreviated forms: [ps, mq, mt, mc, pr]
On by default: matchQuality, matchType
Note: The value names are case-sensitive.
Examples
This section provides examples of Geocoder API requests.
Geocoding Examples
This section provides examples of geocode requests.
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.
Geocoder API Developer's Guide
► User Guide
25
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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=425 W Randolph Street, Chicago
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
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 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:
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=425 W Randolph, Chicago
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
Example with Ambiguous Address Input
Partial input can be ambiguous. In the following example the street direction is omitted:
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=200 Randolph Street, Chicago
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
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 60606, United States</Label>
Geocoder API Developer's Guide
► User Guide
26
<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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?state=IL
&city=Chicago
&street=W Randolph Street
&housenumber=425
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
The result is the same as the previous freeform input.
<Label>425 W Randolph St, Chicago, IL 60606, United States</Label>
...
<DisplayPosition>
<Latitude>41.8838692</Latitude>
<Longitude>-87.6389008</Longitude>
</DisplayPosition>
Geocoder API Developer's Guide
► User Guide
27
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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?city=Mitte
&street=Friedrichstr 100
&additionaldata=FlexibleAdminValues,1
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
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>
Combining Freeform with Qualified Input
Freeform and qualified input can also be combined. For example, a freeform search can be qualified
with state or country information. The following example limits the search for Main St in Springfield
to the state of Missouri. Without the state information there are more than twenty matches in
various states of the USA.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?state=MO
&searchtext=Main St Springfield
&gen=4
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
Geocoder API Developer's Guide
► User Guide
28
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:
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=Market St
&mapview=37.7983366,-122.4006509;37.7904096,-122.3916387
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
There are two results for two different postal code in the response. The results are sorted by
distance from the map view center.
<Distance>191.8</Distance>
...
<DisplayPosition>
<Latitude>37.7927742</Latitude>
<Longitude>-122.396965</Longitude>
</DisplayPosition>
...
<Label>Market St, San Francisco, CA 94111, United States</Label>
...
<Distance>719.7</Distance>
...
<DisplayPosition>
Geocoder API Developer's Guide
► User Guide
29
<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.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=Pine St @ Market St San Francisco
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
http://geocoder.cit.api.here.com/6.2/geocode.xml
?city=San Francisco
&street=Pine St @ Market St
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
http://geocoder.cit.api.here.com/6.2/geocode.xml
?city=San Francisco
&street0=Pine St
&street1=Market St
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
The response for each of the requests is identical.
<MatchLevel>intersection</MatchLevel>
...
<DisplayPosition>
<Latitude>37.7924881</Latitude>
<Longitude>-122.3973389</Longitude>
</DisplayPosition>
...
<Address>
Geocoder API Developer's Guide
► User Guide
30
<Label>
Pine St & Market St, San Francisco, CA 94111, United States
</Label>
<Country>USA</Country>
<State>CA</State>
<County>San Francisco</County>
<City>San Francisco</City>
<Street>Pine St & Market St</Street>
<PostalCode>94111</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. The LocationID is a hash code generated from address components (based on a default
language so that it is the same for each response language). The LocationID is not guaranteed to
be permanent across map versions. The following example uses the LocationID to retrieve location
information.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?locationid=NT_4N4sL870u5vRO9r+Zt+44A_425
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
Retrieval of Postal Code Shapes
Location information of geocoding requests can include postal code shape information.
These shapes can be used as map overlays, for example. To get shape information add
additionaldata=IncludeShapeLevel,Postalcode to the request, shown in the following
example.
http://geocoder.cit.api.here.com/6.2/geocode.xml
?searchtext=94301 USA
&additionaldata=IncludeShapeLevel,PostalCode
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
Geocoder API Developer's Guide
► User Guide
31
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
32
service falls back to retrieval of area information. The gen parameter with value >=1 is essential for
limiting the results to locations within the set radius. See also Generation History on page 22
http://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=50.1115118,8.6805059,100
&mode=retrieveAddresses
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
Retrieve Area Information at a Position
Example request to retrieve area information at the set position. The mode paramter is set to
retrieveAreas which instructs the service to retrieve the area information at the set position.
http://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=50.1115118,8.6805059
&mode=retrieveAreas
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
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
37, 121
121.0 37.0
37N, 121W
37N,121W
Geocoder API Developer's Guide
► User Guide
•
•
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
33
Invalid formats due to potential conflicts with postal codes.
•
•
37 121
121 37
An example using searchtext containing coordinates.
http://geocoder.cit.api.here.com/6.2/search.xml
?searchtext=50.1115118%208.6805059
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
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
National parks
Tourist attractions
Table 3: Find Well Known Landmarks
Required
Optional (area qualifiers and spatial
filters)
•
searchtext (text or name to search for)
•
country
•
state
•
county
Geocoder API Developer's Guide
► User Guide
Required
34
Optional (area qualifiers and spatial
filters)
•
city
•
district
•
postalcode
•
mapview
•
bbox
•
prox
•
categoryids
•
name
Example landmark request:
This example shows a global search for "Eiffel Tower".
http://geocoder.cit.api.here.com/6.2/search.xml
?searchtext=Eiffel%20Tower
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
&gen=4
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.
http://geocoder.cit.api.here.com/6.2/search.xml
?searchtext=A67 4&categoryids=116
&app_id=DemoAppId01082013GAL
&app_code=AJKnXv84fjrb0KIHawS0Tg
/search.xml?searchtext=A67&name=4&categoryids=116
/search.xml?searchtext=A67&name=4
/search.xml?searchtext=A67 4
/search.xml?searchtext=A67 4 Gross-Gerau&categoryids=116
The table below shows the category Ids for the most relevant landmark categories.
Geocoder API Developer's Guide
► User Guide
35
Table 4: Landmark Category Ids
Category Name
Category Id
Highway Exit
116
Ferry Terminal
4482
Airport
4581
Historical Monument
5999
Sports Complex
7940
Park/Recreation Area
7947
Amusement Park
7996
Tourist Attraction
7999
Museum
8410
Border Crossing
9999
Service Support
If you need assistance with this or other HERE products, please contact your HERE representative or
Technical Customer Support via email at [email protected].
Geocoder API Developer's Guide
► API Reference
Chapter
4
API Reference
Topics:
•
Resources and Parameters
•
Response Data Types
•
Response Schemas and Examples
This part of the guide provides a comprehensive reference to
Geocoder API.
36
Geocoder API Developer's Guide
► API Reference
37
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 Examples on
page 24 for supported parameter combinations.
Name
URL
Geocoding
http://geocoder.api.here.com/6.2/geocode.{format}
Reverse geocoding
http://reverse.geocoder.api.here.com/6.2/reversegeocode.{format}
Multi reverse geocoding
http://reverse.geocoder.api.here.com/6.2/multi-reversegeocode.{format}
Landmark geocoding
http://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
Description
additionaldata
Key-value pairs that provide additional input to requests. See Additional Data Parameter on
page 54 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, street, houseNumber,
postalCode, addressLines, additionalData]
Abbreviated forms: [ctr, sta, cty, cit, dis, str, hnr, pst, aln, add]
On by default: All except addressLines.
Geocoder API Developer's Guide
► API Reference
Parameter
38
Description
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 Acquiring Credentials on page 19.
app_code
xs:string
A 20 byte Base64 URL-safe encoded string used for the authentication of the client
application.
You must include an app_id and app_code with every request. To get an app_id assigned
to you, please see Acquiring Credentials on page 19.
bbox
see also GeoBoundingBoxType on page 68
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.
bbox=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965
city
xs:string, fuzzy match
A country specific mapping is required. Example,
country
•
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.
countryfocus
xs:string, exact match, single ISO 3166-1-alpha-3 country code
Results from the specified country are preferred. This is a soft filter.
•
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.
•
county
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,
district
•
USA: County
•
Germany: Kreis
xs:string, fuzzy match
Geocoder API Developer's Guide
► API Reference
Parameter
39
Description
Subdivision level below the city. Depending on the admin hierarchy in a country this level
might not be applicable. Example,
gen
•
USA: n/a
•
Germany: Ortsteil
xs:int
The gen parameter enables or disables backward incompatible behavior in the API.
•
gen=0 default behavior
•
gen=1
◦
If a reverse geocoding request for an address does not find an address or street
within the set radius the area information is returned instead. If gen=0 the results
with a 10,000 meter radius are returned.
◦
Result MatchLevel for intersection matches is intersection. With gen=0 the
MatchLevel for intersection matches is street.
•
gen=2
◦
Includes gen=1 functionality.
◦
Return the area display point (e.g. the centroid 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 (recommended)
◦
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.
housenumber
xs:string, exact match
The house number or house name.
jsonattributes
xs:int
Geocoder API Developer's Guide
► API Reference
Parameter
40
Description
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
jsoncallback
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
language
LanguageCodeType
The preferred language of address elements in the result. Language code must be provided
according to RFC 4647 standard. Note that the plural form of the parameter (languages)
is supported as well. But only the last specified language in the list is used. All preceding
language preferences are ignored at this time.
locationattributes
Comma separated list of which elements are present in the response data.
Enumeration [address, mapReference, mapView, additionalData, adminIds]
Abbreviated forms: [ar, mr, mv, ad, ai]
adminIds are available with forward geocoding only.
On by default: All for reverse geocoding. All except mapReference for forward geocoding.
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.
locationid
xs:string, exact match
A key uniquely identifying a physical location. Each record in a geocode response contains
a location Id. Use the Id to retrieve the exact same location information. For example, the
location Id for "1 Market Street, 94111 San Francisco" is NT_HoZefYX0bMxoVxCkp1uk2C_1.
mapview
See GeoBoundingBoxType on page 68
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.
mapview=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965
maxresults
xs:int
The number of items in the response structure can be limited. By specifying maxresults,
results are returned in separate pages. Each response contains a handle to the next page. For
example, maxresults=5 returns a maximum of 5 results per page. If there were 8 results in
total, the first page of five results indicates that there is a second page with more results.
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}"
pageinformation
xs:string
Geocoder API Developer's Guide
► API Reference
Parameter
41
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
}"
postalcode
xs:string, exact match
Postal code defined by the government of the country.
prox
GeoProximityType, see also GeoProximityType on page 69
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.
responseattributes
Comma separated list of which elements are present in the response data.
Enumeration [performedSearch, matchQuality, matchType, matchCode,
parsedRequest]
Abbreviated forms: [ps, mq, mt, mc, pr]
On by default: matchQuality, matchType
Note: The value names are case-sensitive.
searchtext
xs:string
searchtext contains free-form text containing address elements. You can specify the
searchtext parameter by itself, or you can specify it with other parameters to narrow your
search. For example, you can specify the state or country paramters along with a freeform address in the searchtext field.
state
xs:string, exact match
First subdivision level below the country. Specify state using full or abbreviated notation. A
country specific mapping is required, for example
street
•
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:
•
or concatenating the two streets using one of the predefined separators ("and", "at",
"&", or "@"), for example:
street0=McAllister St&street1=Market St
street=McAllister St @ Market St
strictlanguagemode
xs:boolean
Geocoder API Developer's Guide
► API Reference
Parameter
42
Description
True - if the value is available in the first language specified in the language parameter
the attribute value is set directly in Address, Place, Location, and Category
elements. Values in alternative languages are returned in the AlternativeValues
element.
False - the best available attribute value based on the language priorities given in
language parameter is returned directly in Address, Place, Location, and Category
elements. No alternatives are returned.
token
xs:string
An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token
is generated based on the user's app_id and received after the registration process of the
application.
Parameter token is deprecated, use app_code instead.
Reverse Geocode Resource
This section contains a list of all Reverse Geocode request parameters.
.../6.2/reversegeocode.{format}?<parameter>=<value>...
Table 6: Request Parameters
Parameter
Element
additionaldata
Key-value pairs that provide additional input to requests. See Additional Data Parameter on
page 54 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, street, houseNumber,
postalCode, addressLines, additionalData]
Abbreviated forms: [ctr, sta, cty, cit, dis, 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 Acquiring Credentials on page 19.
Geocoder API Developer's Guide
► API Reference
Parameter
Element
app_code
xs:string
43
A 20 byte Base64 URL-safe encoded string used for the authentication of the client
application.
You must include an app_id and app_code with every request. To get an app_id assigned
to you, please see Acquiring Credentials on page 19.
gen
xs:int
The gen parameter enables or disables backward incompatible behavior in the API.
•
gen=0 default behavior
•
gen=1
◦
If a reverse geocoding request for an address does not find an address or street
within the set radius the area information is returned instead. If gen=0 the results
with a 10,000 meter radius are returned.
◦
Result MatchLevel for intersection matches is intersection. With gen=0 the
MatchLevel for intersection matches is street.
•
gen=2
◦
Includes gen=1 functionality.
◦
Return the area display point (e.g. the centroid 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 (recommended)
◦
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.
jsonattributes
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
Geocoder API Developer's Guide
► API Reference
Parameter
Element
jsoncallback
xs:string
44
Specifies the name of a user-defined function used to wrap the JSON response.
language
LanguageCodeType
The preferred language of address elements in the result. Language code must be provided
according to RFC 4647 standard. Note that the plural form of the parameter (languages)
is supported as well. But only the last specified language in the list is used. All preceding
language preferences are ignored at this time.
level
xs:string
Target match level of the search result. One of [country, state, county, city, district,
postalCode]. Only valid in combination with gen=2 or higher.
locationattributes
Comma separated list of which elements are present in the response data.
Enumeration [address, mapReference, mapView, additionalData, adminIds]
Abbreviated forms: [ar, mr, mv, ad, ai]
adminIds are available with forward geocoding only.
On by default: All for reverse geocoding. All except mapReference for forward geocoding.
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.
maxresults
xs:int
The number of items in the response structure can be limited. By specifying maxresults,
results are returned in 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
}"
mode
One of two values:
retrieveAddresses - Search for the closest street address or addresses
retrieveAreas - Retrieve the administrative area information for the position provided
in the request
pageinformation
xs:string
A key which identifies the page to be returned when the response is separated into multiple
pages. Only relevant, if maxresults has been specified in a previous request and the
response to the request includes the information that there is another page, for example:
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}"
prox
GeoProximityType, see also GeoProximityType on page 69
Geocoder API Developer's Guide
► API Reference
Parameter
45
Element
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.
responseattributes
Comma separated list of which elements are present in the response data.
Enumeration [performedSearch, matchQuality, matchType, matchCode,
parsedRequest]
Abbreviated forms: [ps, mq, mt, mc, pr]
On by default: matchQuality, matchType
Note: The value names are case-sensitive.
strictlanguagemode
xs:boolean
True - if the value is available in the first language specified in the language parameter
the attribute value is set directly in Address, Place, Location, and Category
elements. Values in alternative languages are returned in the AlternativeValues
element.
False - the best available attribute value based on the language priorities given in
language parameter is returned directly in Address, Place, Location, and Category
elements. No alternatives are returned.
token
xs:string
An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token
is generated based on the user's app_id and received after the registration process of the
application.
Parameter token is deprecated, use app_code instead.
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
Element
additionaldata
Key-value pairs that provide additional input to requests. See Additional Data Parameter on
page 54 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;
Geocoder API Developer's Guide
► API Reference
Parameter
46
Element
IncludeZipAddon,true
addressattributes
Comma separated list of which elements are present in the response data.
Enumeration [country, state, county, city, district, street, houseNumber,
postalCode, addressLines, additionalData]
Abbreviated forms: [ctr, sta, cty, cit, dis, 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 Acquiring Credentials on page 19.
app_code
xs:string
A 20 byte Base64 URL-safe encoded string used for the authentication of the client
application.
You must include an app_id and app_code with every request. To get an app_id assigned
to you, please see Acquiring Credentials on page 19.
gen
xs:int
The gen parameter enables or disables backward incompatible behavior in the API.
•
gen=0 default behavior
•
gen=1
◦
If a reverse geocoding request for an address does not find an address or street
within the set radius the area information is returned instead. If gen=0 the results
with a 10,000 meter radius are returned.
◦
Result MatchLevel for intersection matches is intersection. With gen=0 the
MatchLevel for intersection matches is street.
•
gen=2
◦
Includes gen=1 functionality.
◦
Return the area display point (e.g. the centroid 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.
Geocoder API Developer's Guide
► API Reference
Parameter
47
Element
◦
MatchType pointAddress for reverse geocoding Point Address results.
Otherwise interpolated. With gen<3 address results from reverse geocoding
always have MatchType interpolated.
•
gen=4 (recommended)
◦
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.
jsonattributes
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
jsoncallback
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
language
LanguageCodeType
The preferred language of address elements in the result. Language code must be provided
according to RFC 4647 standard. Note that the plural form of the parameter (languages)
is supported as well. But only the last specified language in the list is used. All preceding
language preferences are ignored at this time.
level
xs:string
Target match level of the search result. One of [country, state, county, city, district,
postalCode]. Only valid in combination with gen=2 or higher.
locationattributes
Comma separated list of which elements are present in the response data.
Enumeration [address, mapReference, mapView, additionalData, adminIds]
Abbreviated forms: [ar, mr, mv, ad, ai]
adminIds are available with forward geocoding only.
On by default: All for reverse geocoding. All except mapReference for forward geocoding.
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.
maxresults
xs:int
The number of items in the response structure can be limited. By specifying maxresults,
results are returned in 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
}"
Geocoder API Developer's Guide
► API Reference
Parameter
Element
mode
One of two values:
48
retrieveAddresses - Search for the closest street address or addresses
retrieveAreas - Retrieve the administrative area information for the position provided
in the request
pageinformation
xs:string
A key which identifies the page to be returned when the response is separated into multiple
pages. Only relevant, if maxresults has been specified in a previous request and the
response to the request includes the information that there is another page, for example:
"metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}"
responseattributes
Comma separated list of which elements are present in the response data.
Enumeration [performedSearch, matchQuality, matchType, matchCode,
parsedRequest]
Abbreviated forms: [ps, mq, mt, mc, pr]
On by default: matchQuality, matchType
Note: The value names are case-sensitive.
strictlanguagemode
xs:boolean
True - if the value is available in the first language specified in the language parameter
the attribute value is set directly in Address, Place, Location, and Category
elements. Values in alternative languages are returned in the AlternativeValues
element.
False - the best available attribute value based on the language priorities given in
language parameter is returned directly in Address, Place, Location, and Category
elements. No alternatives are returned.
token
xs:string
An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token
is generated based on the user's app_id and received after the registration process of the
application.
Parameter token is deprecated, use app_code instead.
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
Geocoder API Developer's Guide
► API Reference
49
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
Description
additionaldata
Key-value pairs that provide additional input to requests. See Additional Data Parameter on
page 54 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, street, houseNumber,
postalCode, addressLines, additionalData]
Abbreviated forms: [ctr, sta, cty, cit, dis, 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 Acquiring Credentials on page 19.
app_code
xs:string
A 20 byte Base64 URL-safe encoded string used for the authentication of the client
application.
You must include an app_id and app_code with every request. To get an app_id assigned
to you, please see Acquiring Credentials on page 19.
bbox
see also GeoBoundingBoxType on page 68
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.
bbox=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965
categoryids
xs:integer
Limit landmark results to one or more categories. Examples:
Geocoder API Developer's Guide
► API Reference
Parameter
city
50
Description
•
Highway exits: 116
•
Airports: 4581
•
Tourist attractions: 7999
xs:string, fuzzy match
A country specific mapping is required. Example,
country
•
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.
countryfocus
xs:string, exact match, single ISO 3166-1-alpha-3 country code
Results from the specified country are preferred. This is a soft filter.
•
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.
•
county
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,
district
•
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,
gen
•
USA: n/a
•
Germany: Ortsteil
xs:int
The gen parameter enables or disables backward incompatible behavior in the API.
•
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
Geocoder API Developer's Guide
► API Reference
Parameter
51
Description
◦
Includes gen=1 functionality.
◦
Return the area display point (e.g. the centroid 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 (recommended)
◦
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.
housenumber
xs:string, exact match
The house number or house name.
jsonattributes
xs:int
If set to 1, the first character of each JSON response attribute name is set to lower case.
Default value is 0.
jsoncallback
xs:string
Specifies the name of a user-defined function used to wrap the JSON response.
language
LanguageCodeType
The preferred language of address elements in the result. Language code must be provided
according to RFC 4647 standard. Note that the plural form of the parameter (languages)
is supported as well. But only the last specified language in the list is used. All preceding
language preferences are ignored at this time.
locationattributes
Comma separated list of which elements are present in the response data.
Enumeration [address, mapReference, mapView, additionalData, adminIds]
Abbreviated forms: [ar, mr, mv, ad, ai]
adminIds are available with forward geocoding only.
On by default: All for reverse geocoding. All except mapReference for forward geocoding.
Geocoder API Developer's Guide
► API Reference
Parameter
52
Description
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.
locationid
xs:string, exact match
A key uniquely identifying a physical location. Each record in a geocode response contains
a location Id. Use the Id to retrieve the exact same location information. For example, the
location Id for "1 Market Street, 94111 San Francisco" is NT_HoZefYX0bMxoVxCkp1uk2C_1.
mapview
See GeoBoundingBoxType on page 68
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.
mapview=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965
maxresults
xs:int
The number of items in the response structure can be limited. By specifying maxresults,
results are returned in 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
}"
name
xs:string
Name of the landmark. The landmark name can also be provided within the searchtext. Use
name instead of searchtext to avoid ambiguity for example with addresses.
Highway exits also fall into the landmark category but note that those consist of a highway
name and an exit name. Only the exit name should be provided in the name parameter. Below
are two ways how to search for exit 4 on highway A67:
pageinformation
•
search.xml?searchtext=A67&name=4
•
search.xml?searchtext=A67 4
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
}"
postalcode
xs:string, exact match
Postal code defined by the government of the country.
Geocoder API Developer's Guide
► API Reference
Parameter
Description
prox
GeoProximityType, see also GeoProximityType on page 69
53
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.
responseattributes
Comma separated list of which elements are present in the response data.
Enumeration [performedSearch, matchQuality, matchType, matchCode,
parsedRequest]
Abbreviated forms: [ps, mq, mt, mc, pr]
On by default: matchQuality, matchType
Note: The value names are case-sensitive.
searchtext
xs:string
searchtext contains free-form text containing address elements. You can specify the
searchtext parameter by itself, or you can specify it with other parameters to narrow your
search. For example, you can specify the state or country paramters along with a freeform address in the searchtext field.
state
xs:string, exact match
First subdivision level below the country. Specify state using full or abbreviated notation. A
country specific mapping is required, for example
street
•
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
strictlanguagemode
xs:boolean
True - if the value is available in the first language specified in the language parameter
the attribute value is set directly in Address, Place, Location, and Category
elements. Values in alternative languages are returned in the AlternativeValues
element.
False - the best available attribute value based on the language priorities given in
language parameter is returned directly in Address, Place, Location, and Category
elements. No alternatives are returned.
token
xs:string
Geocoder API Developer's Guide
► API Reference
Parameter
54
Description
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
Value
CrossingStreets
true/false, determines whether the response contains cross streets.
PreserveUnitDesignators
true/false, secondary address units as defined by the US Postal Service are
recognized and returned if this switch is set to true. Recognized address units are
returned in the Address.AdditionalData field, where the designator is the key
and the unit value is the value of the entry.
Country2
true/false, determines whether ISO-3166 alpha-2 country codes are returned
in the response address AddressType.additionalData[Country2] element.
By default, two-letter codes are not returned.
IncludeChildPOIs
true/false, determines whether child POIs are returned with their parent POI.
Examples for POIs with a parent/child relationship are airports and their terminals
or national parks and their entrances. By default, child POIs are not returned.
IncludeRoutingInformation
true/false, determines whether additional information needed for precise
routing instructions is returned with the request. The data is stored in additional
data fields in returned Location elements. The keys for all of these entries are
prefixed with the string routing, enabling filtering on client side.
AdditionalAddressProvider
List of Provider IDs (space separated) for address source that should be
considered additionally in the search. Currently only provider ID 24 is supported.
Provider 24 adds some addresses in Germany for which the map data does not
have geometry yet. The addresses therefore only have a display coordinate.
If data from an additional address provider is returned, the corresponding
Location element is flagged with an additionalData entry
additionalAddressProvider identifying the provider.
HouseNumberMode
Defines how to geocode unknown house numbers. The following values are
supported:
•
Extrapolation <MAX_HSN_DISTANCE> <MAX_DISTANCE>: Use
extrapolation.
Extrapolation is performed until a predefined maximum distance in house
number and a maximum in meters. The system wide configured maximum
values can be overwritten by passing values for MAX_HSN_DISTANCE and/or
Geocoder API Developer's Guide
► API Reference
Key
55
Value
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.
•
FlexibleAdminValues
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.
•
IntersectionSnapTolerance
1: City and District swapping
N (float in [0, 1]). When reverse geocoding a coordinate, the value controls how
strictly an address match is snapped to the next intersection. A value of 0 indicates
that no points on a link are snapped to an intersection; a value of 1 indicates that
most probably a street intersection is returned as a match. Default value is 0.
AddressRangeSqueezeOffset
N (positive integer), offset in meters which moves the first and last locations of an
address range on a link away from the center point of an intersection. If no value
for the AddressRangeSqueezeXXX parameters is provided, a default constant
offset is used.
AddressRangeSqueezeFactor
N (float in [0, 1]). Similar to AddressRangeSqueezeOffset; the value is provided
relatively to the link length as a percentage. 0.5 means 20% squeeze on both
sides. 1 means range squeezed to point. 0 means no squeeze but also no default
constant offset.
IncludeShapeLevel
Area Level used to populate the shape information in the location results. Only
postalCode is supported.
Response Data Types
This section provides reference to the data structures used throughout the Geocoder API.
Geocoder API Developer's Guide
► API Reference
56
Search Response
The SearchResponse structure is the top level element returned by geocode, reverse geocode and
landmark geocode requests. It contains Meta Information and one or more View elements. Each view
consists of a list of Results wrapping the actual Location object found for the request together with
information about the Match Quality of the result.
Figure 1: Overview Response Types
Geocoder API Developer's Guide
► API Reference
57
Response (SearchResponseType)
Table 10: Response elements
Type
Description
MetaInfo
Meta Information about the Request
View
Search Results are grouped in Views.
MetaInfo (SearchResponseMetaInfoType)
Table 11: MetaInfo elements
Type
Description
RequestId
Mirrored RequestId value from the request structure. Can be used to trace
requests.
Timestamp
Time at which the search was performed.
NextPageInformation
Key which can be used in subsequent requests to acquire the next n results. This
element is only provided if paging has been activated in the request.
PreviousPageInformation
Key which can be used in subsequent requests to acquire the previous n results.
This element is only provided if paging has been activated in the request.
AdditionalData
List of KeyValuePairType elements as generic container to attach additional
information to the request.
View (SearchResultsViewType)
Table 12: View elements
Type
Description
ViewId
A key to distinguish between different types of views. Always set to 0.
PerformedSearch
Search path which was performed for this search run. In case of free-form searches, this element
holds structured information, which indicates how user input has been interpreted by Search. The
Performed Search has the same structure as a search request and can thus be used to repeat the
same search.
Results
The resulting items which have been found along with attributes indicating the quality of the
search result.
Geocoder API Developer's Guide
► API Reference
58
Result (SearchResultType)
The SearchResult contains the actual result as a Location object together with information on how
good the result matches the search request.
Table 13: Result elements
Type
Description
Relevance
Indicates the relevance of the results found; the higher the score the more relevant
the alternative. The score is a normalized value between 0 and 1.
Distance
Distance between the identified location object and the specified client position in
meters. Only provided if a proximity was specified in the request (parameter prox).
MatchLevel
The most detailed address field that matches the geocoding or reverse geocoding
query. Enumeration [country, state, county, city, district, street,
intersection, house Number, postalCode, suite, floor]. intersection
is only supported with gen >= 1; for gen<1 requests street is returned for
intersection matches.
MatchQuality
Detailed information about the match quality on the attribute level. Geocoding
resource only.
MatchType
Quality of the location match.
pointAddress Location matches exactly as Point Address.
interpolated Location was interpolated.
With gen<3 address results from reverse geocoding always have MatchType
interpolated; only with gen>=3 reverse geocoding returns Point Address results
with MatchType pointAddress.
MatchCode
Code indicating how well the result matches the request. Enumeration [exact,
ambiguous, upHierarchy, ambiguousUpHierarchy].
ParsedRequest
Structured representation of the request which led to the current search result.
Location
The location that was found.
AdditionalData
Generic key/value container to keep additional attributes. The defined key/values
are:
•
houseNumberFallback
true/false. This attribute is included, if MatchLevel is houseNumber. It is set
to false, if Search could find the requested house number. If set to true,
it indicates that the requested house number was corrected to match the
nearest known house number
•
houseNumberFallbackDifference
Geocoder API Developer's Guide
► API Reference
Type
59
Description
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
Description
Country
Match quality of the result with respect to country information in the request.
State
Match quality of the result with respect to state information in the request.
County
Match quality of the result with respect to county information in the request.
City
Match quality of the result with respect to city information in the request.
District
Match quality of the result with respect to district information in the request.
Street
Match quality of the result with respect to street information in the request. There
are two values of 'Street' when you specify an intersection.
HouseNumber
Match quality of the result with respect to housenumber information in the
request.
PostalCode
Match quality of the result with respect to postal code information in the request.
Building
Match quality of the result with respect to building information in the request.
ParsedRequest (ParsedRequestType)
ParsedRequest shows how the various components of the request were derived from search terms.
Geocoder API Developer's Guide
► API Reference
60
Table 15: ParsedRequest elements
Type
Description
Name
Input token(s) the parser has categorized as the name of a landmark.
Label
Assembled address value built out of the parsed address components.
Country
Input token(s) the parser has categorized as the country part of an address.
State
Input token(s) the parser has categorized as the state part of an address.
County
Input token(s) the parser has categorized as the county part of an address.
City
Input token(s) the parser has categorized as the city part of an address.
District
Input token(s) the parser has categorized as the district part of an address.
Street
Input token(s) the parser has categorized as the street part of an address (including
intersections which are defined by two streets).
HouseNumber
Input token(s) the parser has categorized as the housenumber part of an address.
PostalCode
Input token(s) the parser has categorized as the postal code part of an address.
Building
Input token(s) the parser has categorized as the building part of an address.
AddressLine
Formatted address lines built out of the parsed address components. The first line
consists of street name, including prefix, directionals and street type, and house number.
The second line consists of the city name and postal code, plus in some countries the
state name or abbreviation. These elements are only populated if the MatchLevel is
street or better. A city match does not contain address lines.
AdditionalData
Secondary address units as defined by the US Postal Service can be recognized and
returned if the PreserveUnitDesignators switch was set to true in the SearchRequest
additionalData field.
Recognized address units are returned in the AdditionalData field, where the designator is
the key and the unit value is the value of the entry:
APT recognized value of unit type Apartment
BLDG recognized value of unit type Bulding
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
61
Location (LocationType)
The location type refers to a physical location including the physical extent. A location can be
referenced either by Location ID or by specifying the address.
Table 16: Location Elements
Type
Description
LocationId
A key uniquely identifying a physical location.
LocationType
Indicates whether the location is an [area, point, line].
DisplayPosition
The display position contains the coordinates at which to place a
marker indicating the given location on the map.
NavigationPosition
A navigation position contains the coordinates of a potential route
waypoint. It is used for routes that pass through the given location.
MapView
Bounding box of the location optimized for display
Shape
Shape of the location. This is only relevant for areas.
AdditionalData
Generic key/value container to keep additional attributes. The defined
key/values are:
•
ExtendedTopLeftLatitude
Latitude of the top-left coordinate of the extended bounding
box which completely encloses the physical extent of the
location.
•
ExtendedTopLeftLongitude
Latitude of the top-left coordinate of the extended bounding
box
•
ExtendedBottomRightLatitude
Latitude of the bottom-left coordinate of the extended bounding
box
•
ExtendedBottomRightLongitude
Longitude of the bottom-right coordinate of the extended
bounding box
•
"additionalAddressProvider"
ProviderId if Location data is provided by an external
address provider. The use of external address providers
has to be activated through an additional data field
"AdditionalAddressProvider" in the request.
Geocoder API Developer's Guide
► API Reference
62
Type
Description
Address
Address record of a Location. Attributes are normalized to US feature
names and can be mapped to the local feature levels (for example,
State matches "Bundesland" in Germany) using mapping tables.
References to a network link and admin areas of the location object.
MapReference
Note: Depending on the search scenario, some sub elements might be omitted.
MapReference (MapReferenceType)
Reference to a Map Object
Table 17: MapReference elements
Type
Description
ReferenceId
PVID of the link (for address level results).
MapVersion
Version of the Map. Format: QQ/YYYY, e.g. Q2/2013
Spot
Relative position of the location along the link. Spot is defined as the fractional
distance from the link's reference-node to the non-reference node, i.e. the value
range is between 0 and 1. This attribute is only relevant if a link is referenced.
SideOfStreet
Indicates whether the referenced location is on the left or right side of the link (if
heading from the reference node to the non-reference node). Enumeration [left,
right, neither].
CountryId
PVID of the country admin area.
StateId
PVID of the state admin area.
CountyId
PVID of the county admin area.
CityId
PVID of the city admin area.
DistrictId
PVID of the district admin area.
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.
Address Type
AddressType defines the following attributes:
Geocoder API Developer's Guide
► API Reference
Element
Definition
Label
Assembled address value for displaying purposes.
Country
ISO 3166-alpha-3 country code
State
Includes the first subdivision level below the country. Where commonly used, this is a state code
63
such as CA for Califonia.
County
Includes the second subdivision level below the country. Use of this field is optional if a second
subdivision level is not available.
City
Refers to the locality of the address.
District
Includes the subdivision level below the city. Use of this field is optional if a second subdivision
level is not available.
Street
Refers to the street name.
HouseNumber
House number. Depending on regional characteristics, can also be house name.
PostalCode
Postal code
Building
Building name. Building names are currently only supported for Hong Kong addresses.
AddressLine
Formatted address lines. The first line consists of street name (including pre-fix, directionals,
street type) and house number. The second line consists of the city name and postal code
plus in some countries the state name or abbreviation. These elements are only populated if
MatchLevel is street or better.
AdditionalData
Generic key/value container to keep additional attributes. The defined key/values are:
•
"CrossingStreet0"
First cross street near matched address
•
"CrossingStreet1"
Second cross street near matched address. This value is omitted by the search
module, if the location’s distance to CrossingStreet0 is less than half of the distance to
CrossingStreet1.
•
"CountryName"
Non-abbreviated, full name of the country.
•
"StateName"
Non-abbreviated, full name of the state.
•
"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"
Geocoder API Developer's Guide
► API Reference
Element
64
Definition
◦
"BLDG" - recognized value of unit type "Bulding"
◦
"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.
Multi Reverse Geocode Response
The MultiSearchResponseType structure is the top level element returned by multi reverse geocode
requests. It contains Meta Information and one or more Items. Each item corresponds to one of the
items in the request, correlated by an ItemId. A response Item contains a list of Search Results,
which wrap the Location objects found for the request.
Figure 2: Overview Multi Search Response Types
Geocoder API Developer's Guide
► API Reference
65
Response (MultiSearchResponseType)
Table 18: Response elements
Type
Description
MetaInfo
Meta Information about the Request
Item
List of response items, each element wrapping the result of a
corresponding input item in the request.
MetaInfo (MultiSearchResponseMetaInfoType)
Table 19: MetaInfo elements
Type
Description
RequestId
Mirrored RequestId value from the request structure.Used to trace requests.
Timestamp
Time at which the search was performed.
AdditionalData
List of KeyValuePairType elements as generic container to attach additional
information to the request.
Item (MultiSearchResponseItemType)
Table 20: Item elements
Type
Description
ItemId
This element contains the key which was specified in the corresponding
request item. If no ItemId has been specified in the request the ItemId is
constructed as the counter of the input items starting with 0.
Result
The resulting alternative items which have been found along with attributes
indicating the quality of the search result.
Base Data Types
Base Data Types used in the Search Response Structure.
Geocoder API Developer's Guide
► API Reference
LatitudeType
Location of a place on Earth north or south of the equator.
LatitudeType is an xs:double type with the following restrictions:
•
•
•
•
Must satisfy: -90 ≤ value ≤ 90
Unit: decimal degrees
Reference System: WGS 84
Precision: 7 positions after decimal point, additional positions are ignored
Examples
45.1234567
-12.3456789
45.123
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
66
Geocoder API Developer's Guide
► API Reference
•
Precision: 4 positions after decimal point, additional positions are ignored
Examples
45.1234
899344
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:
67
Geocoder API Developer's Guide
► API Reference
•
•
68
retrieveAddresses Search for the closest street address or addresses.
retrieveAreas Retrieve the administrative area information for the position provided in the
request.
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
69
Geocoder API Developer's Guide
► API Reference
70
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
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 ShapeFormatType for a list of supported
representations.
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
String value containing the WKT representation.
Example:
POLYGON ((8.694859999000073 50.11352, 8.69483557600006 50.11347330600006,
8.694840580000061 50.11346496600004, 8.694919999000092
50.11342, 8.694895537000093 50.11337503400006, 8.694817765000039
50.11337503400006, 8.694719999000085 50.11342, 8.69470104000004
50.113373025000044, 8.694515205000073 50.11335532600003,
8.694226143000037 50.113315456000066, 8.694224789000089
50.11331529000006, 8.694107760000065 50.11330275100005, 8.693939999000065
50.113329999000086, 8.694859999000073 50.11352))
Geocoder API Developer's Guide
► API Reference
71
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.
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
http://geocoder.api.here.com/6.2/xsd/LBSP-Search-Search.xsd
XSD Version
4.3
XML Schema for endpoint multi-reversegeocode results
Schema location
http://geocoder.api.here.com/6.2/xsd/LBSP-Search-MultiSearch.xsd
XSD Version
1.0
Geocoder API Developer's Guide
► API Reference
Response Examples
Example Geocode Response
For explanations of each element in the XML response, see Search Response on page 56
<Response>
<MetaInfo>
<Timestamp>2013-01-30T15:34:33.995Z</Timestamp>
</MetaInfo>
<View xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns2:SearchResultsViewType">
<ViewId>0</ViewId>
<Result>
<Relevance>1.0</Relevance>
<MatchLevel>houseNumber</MatchLevel>
<MatchQuality>
<City>1.0</City>
<Street>0.9</Street>
<HouseNumber>1.0</HouseNumber>
</MatchQuality>
<MatchType>pointAddress</MatchType>
<Location>
<LocationId>NT_4N4sL870u5vRO9r+Zt+44A_425</LocationId>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>41.8838692</Latitude>
<Longitude>-87.6389008</Longitude>
</DisplayPosition>
<NavigationPosition>
<Latitude>41.8844719</Latitude>
<Longitude>-87.6390915</Longitude>
</NavigationPosition>
<MapView>
<TopLeft>
<Latitude>41.8849933</Latitude>
<Longitude>-87.6404107</Longitude>
</TopLeft>
<BottomRight>
<Latitude>41.882745</Latitude>
<Longitude>-87.6373908</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>
<Street>W Randolph St</Street>
<HouseNumber>425</HouseNumber>
<PostalCode>60606</PostalCode>
<AdditionalData key="CountryName">United States</AdditionalData>
<AdditionalData key="StateName">Illinois</AdditionalData>
</Address>
</Location>
</Result>
</View>
</Response>
72
Geocoder API Developer's Guide
► API Reference
Example Reverse Geocode Response
For explanations of each element in the XML response, see Search Response on page 56
<Result>
<Relevance>1.0</Relevance>
<Distance>1.2</Distance>
<MatchLevel>houseNumber</MatchLevel>
<MatchQuality>
<Country>1.0</Country>
<State>1.0</State>
<County>1.0</County>
<City>1.0</City>
<Street>1.0</Street>
<HouseNumber>1.0</HouseNumber>
<PostalCode>1.0</PostalCode>
</MatchQuality>
<Location>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>50.1114661</Latitude>
<Longitude>8.680358</Longitude>
</DisplayPosition>
<MapView>
<TopLeft>
<Latitude>50.1125903</Latitude>
<Longitude>8.6786051</Longitude>
</TopLeft>
<BottomRight>
<Latitude>50.1103419</Latitude>
<Longitude>8.682111</Longitude>
</BottomRight>
</MapView>
<Address>
<Label>Berliner Straße 56, 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>56</HouseNumber>
<PostalCode>60311</PostalCode>
<AdditionalData key="CountryName">Deutschland</AdditionalData>
<AdditionalData key="StateName">Hessen</AdditionalData>
</Address>
<MapReference>
<ReferenceId>778448681</ReferenceId>
<SideOfStreet>neither</SideOfStreet>
</MapReference>
</Location>
</Result>
Example Multi Reverse Response
For explanations of each element in the XML response, see Multi Reverse Geocode Response on
page 64
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:MultiSearch>
<Response>
<MetaInfo>
<Timestamp>2013-01-21T16:20:11.694Z</Timestamp>
73
Geocoder API Developer's Guide
► API Reference
</MetaInfo>
<Item>
<ItemId>1</ItemId>
<Result>
<Relevance>1.0</Relevance>
<Distance>0.9</Distance>
<MatchLevel>houseNumber</MatchLevel>
<MatchQuality>
<Country>1.0</Country>
<State>1.0</State>
<County>1.0</County>
<City>1.0</City>
<Street>1.0</Street>
<HouseNumber>1.0</HouseNumber>
<PostalCode>1.0</PostalCode>
Example Landmark Geocode Response
For explanations of each element in the XML response, see Search Response on page 56
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4">
<Response>
<MetaInfo>
<Timestamp>2013-03-21T13:28:07.527Z</Timestamp>
</MetaInfo>
<View xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns2:SearchResultsViewType">
<ViewId>0</ViewId>
<Result>
<Relevance>1.0</Relevance>
<MatchQuality>
<Country>1.0</Country>
<State>1.0</State>
</MatchQuality>
<Place>
<PlaceId>801890088</PlaceId>
<Name>Tour Eiffel</Name>
<Category>
<CategoryId>5999</CategoryId>
<CategorySystemId>facility</CategorySystemId>
</Category>
<Suppliers>
<SupplierId>3</SupplierId>
</Suppliers>
<Locations>
<LocationId>NT_NTMO_POI801890088</LocationId>
<LocationType>point</LocationType>
<DisplayPosition>
<Latitude>48.8587303</Latitude>
<Longitude>2.2938099</Longitude>
</DisplayPosition>
<NavigationPosition>
<Latitude>48.8587303</Latitude>
<Longitude>2.2938099</Longitude>
</NavigationPosition>
<MapView>
<TopLeft>
<Latitude>48.8677235</Latitude>
<Longitude>2.2801407</Longitude>
</TopLeft>
<BottomRight>
<Latitude>48.8497371</Latitude>
<Longitude>2.3074791</Longitude>
</BottomRight>
</MapView>
74
Geocoder API Developer's Guide
► API Reference
<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>
</Address>
</Locations>
</Place>
</Result>
</View>
</Response>
</ns2:Search>
75