geocoder api developer's...

Geocoder APIDeveloper's Guide

Version 6.2.50

Geocoder API Developer's Guide 2► Contents

Contents

Legal Notices..........................................................................................................................................................4

Document Information.................................................................................................................................... 5

Chapter 1: Overview................................................................................................................................. 6What is the Geocoder API?...........................................................................................................................7

Why use the Geocoder API?.........................................................................................................................7

Chapter 2: Quick Start........................................................................................................................... 8Making Your First Requests......................................................................................................................... 9

Geocoding.........................................................................................................................................................9

Reverse Geocoding...................................................................................................................................... 11

Multi Reverse Geocoding............................................................................................................................13

Landmark Geocoding...................................................................................................................................15

Chapter 3: User Guide......................................................................................................................... 18Acquiring 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 3► Contents

Chapter 4: API Reference................................................................................................................. 36Resources 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 4► Legal Notices

Legal Notices© 2014 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 5► Document Information

Document Information

Product

Name: Geocoder API

Version: Version 6.2.50

Document

Name: Geocoder API Developer's Guide

Id: 62221e9-1389862914

Status: FINAL

Date: 2014-Jan-16, 9:02 (GMT)

Geocoder API Developer's Guide 6► Overview

Chapter

1

OverviewTopics:

• What is the Geocoder API?

• Why use the Geocoder API?

This section introduces the Geocoder API and describes its

common use cases.

Geocoder API Developer's Guide 7► Overview

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 canbe in structured (qualified) or unstructured (single-line entry, un-qualified) form (for example,"street=425 W Randolph&city=Chicago" or "searchtext=425 W Randolph, Chicago").

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

• Find address within geospatial area (for example, "100 Market St, in37.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 8► Quick Start

Chapter

2

Quick StartTopics:

• Making Your First Requests

• Geocode Request

• Reverse Geocode Request

• Multi Reverse Geocode Request

• Landmark Geocode Request

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

interface. This article contains example requests that you can run

to see how the service works.


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

app_id and app_code are authentication credentials. 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 RequestSend 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


&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


&country=USA

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

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

given coordinate.

Retrieve Addresses

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

latitude 50.111 and longitude 8.680.

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>


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


◦ 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 RequestRetrieve street address or area information for up to one hundred coordinates with one multi reverse

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

results are contained in the response.

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

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

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

the system creates one starting with 0.


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

coordinate pairs result in an error response.

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

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,50id=0002&prox=50.1618996,8.5334997,50id=0003&prox=40.72962607104243,-73.98685008095087,50id=0004&prox=47.609877297128094,-122.34250277090143,50id=0005&prox=-22.98040197212022,-43.189731399601726,50id=0006&prox=-8.494347821639211,115.25337974172669id=0007&prox=28.63383758137441,77.21917444061432,50id=0008&prox=-33.92046215720197,18.42085660357364,50id=0009&prox=21.00272769618338,-89.62247149160008,50id=0010&prox=24.660771905240175,46.71228298253175,50

and the URL of the post request to:

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.


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 RequestLandmark 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>


<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


&searchtext=Ferry Building&country=USA

Geocoder API Developer's Guide 18► User Guide

Chapter

3

User GuideTopics:

• Acquiring Credentials

• Constructing a Request

• Key Concepts

• Examples

• Service Support

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

API.


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

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

To obtain the credentials for an application, please visit http://developer.here.com/get-started for

more details.

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

addition, it may contain resource-specific parameters.

Table 1: Basic request elements

Element Value/Example Description

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

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

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

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

Production environment

CIT environment: see CustomerIntegration Testing on page 20

Path /6.2

Resource /geocode.json

/geocode.xml

/reversegeocode.json

/reversegeocode.xml

/multi-reversegeocode.json

/multi-reversegeocode.xml

/search.json

/search.xml

GET only except for multi-reversegeocode (POST), specifyrequest details via query parameters

Application Code &app_code=AJKnXv84fjrb0KIHawS0Tg Substitute your own unique

app_code

Application Id &app_id=DemoAppId01082013GAL Substitute your own unique app_id

http://developer.here.com/get-started


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

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

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

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

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

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

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

testing in general.

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

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

35.

The CIT environment is not intended for general production use.

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

representation. For example, "K%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 ConceptsThis section provides information on key concepts used in the Geocoder API.


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

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

different URL.

Backwards CompatibilityThe following request interface changes are considered backward compatible:

• Adding new endpoints.

• Adding new optional parameters.

• Adding new enumeration values.

• Changing a parameter from mandatory to optional.

• Softening a parameter constraint.

The following changes in response structures are considered backward compatible:

• Adding new optional elements.

• Adding new enumeration values.

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

• Adding new error subtypes.

• Hardening constraint for an element value.

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

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

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

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

response.

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

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

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

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

• Changing the order of results


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

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

latest generation.

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

documentation.

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

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

assumptions.

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

corresponding generation parameter value.

• gen=0 default behavior

• gen=1

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

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

radius are returned.

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

MatchLevel for intersection matches is street.

• gen=2

◦ Includes gen=1 functionality.

◦ Return the area display point (e.g. the 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


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



◦ 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 SwitchesResponses always contain a default set of elements. You can increase or reduce the amount of

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

returned.

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

&responseattributes=matchCode,parsedRequest

or use abbreviated forms

&responseattributes=mc,pr

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

&locationattributes=-mapView

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

additionalData use:

&locationattributes=-mapView,additionalData

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

The following example returns the whole attribute set except mapView .

&locationattributes=all,-mapView

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

The following example returns only address.

&locationattributes=none,address


Table 2: Attribute switches and values

Attribute switch Values

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

Enumeration [country, state, county, city, district, 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 theresponse data. With adminIds only admin area PVIDs are present.


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

Enumeration [performedSearch, matchQuality, matchType, matchCode,parsedRequest]

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

On by default: matchQuality, matchType


ExamplesThis section provides examples of Geocoder API requests.

Geocoding ExamplesThis section provides examples of geocode requests.

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

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

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


Freeform Example with Complete Address Input

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

address as input.

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>


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

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

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

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

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

postalcode, street, housenumber

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

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

a mapview is present.

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

provided.

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

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

Qualified Input Example

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

complete address as input.

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>


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


Restricting the search to Missouri returns only one address.

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

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

specified state the response contains matches from other states.

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

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

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

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

Relevant global results are also returned.

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

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

higher. Relevant global results are also returned.

Addressline-only Example

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

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

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>


<Latitude>37.7893333</Latitude> <Longitude>-122.4012833</Longitude></DisplayPosition>...<Label>Market St, San Francisco, CA 94104, United States</Label>

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

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

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

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

Intersection Search Example

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

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>


<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 IdentityEvery 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 ShapesLocation 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


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 ExamplesThis section provides examples of reverse geocoding requests.

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

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


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

limiting the results to locations within the set radius. See also Generation History on page 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 PositionExample 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 SearchA simple way to make reverse geocoding requests is to pass the coordinates as searchtext to the

search endpoint.

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

• DD.MMMMM

• DD.MMMMM°

• DD MM SS

• DD MM SS.SS

• DD°MM'SS"

• DD°MM'SS.SS"

• DD°MM.SS'

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

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

• 37,121

• 37, 121

• 121.0 37.0

• 37N, 121W

• 37N,121W


• 37N 121W

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

• 37° 121°

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

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

Invalid formats due to potential conflicts with postal codes.

• 37 121

• 121 37

An example using searchtext containing coordinates.

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 ExamplesThis section provides examples of landmark geocoding requests.

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

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

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

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

include:

◦ Historical monuments

◦ National parks

◦ Tourist attractions

Table 3: Find Well Known Landmarks

Required Optional (area qualifiers and spatialfilters)

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

• state

• county


Required Optional (area qualifiers and spatialfilters)

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


Table 4: Landmark Category Ids

Category Name Category Id

Highway Exit 116

Ferry Terminal 4482

Airport 4581

Historical Monument 5999

Sports Complex 7940

Park/Recreation Area 7947

Amusement Park 7996

Tourist Attraction 7999

Museum 8410

Border Crossing 9999

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

Technical Customer Support via email at [email protected].

mailto:[email protected]

Geocoder API Developer's Guide 36► API Reference

Chapter

4

API ReferenceTopics:

• Resources and Parameters

• Response Data Types

• Response Schemas and Examples

This part of the guide provides a comprehensive reference to

Geocoder API.


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

Geocoder API.

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

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

page 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 ResourceThis section contains a list of all Geocode request parameters.

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

Table 5: Request Parameters

Parameter Description

additionaldata Key-value pairs that provide additional input to requests. See Additional Data Parameter onpage 54 for a full list. Key and value are separated using a ,. Multiple key-value pairs areseparated using a ;:

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

Example:

additionaldata=PreserveUnitDesignators,true; IncludeZipAddon,true








app_id xs:string

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

You must include an app_id and app_code with every request. To get an app_id assignedto you, please see Acquiring Credentials on page 19.

app_code xs:string



bbox see also GeoBoundingBoxType on page 68

A type of Spatial Filter. A spatial filter limits the search for any other attributes in therequest. A bounding box bbox is specified by two latitude / longitude pairs; the first pairdefines 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,

• USA: City

• Germany: Gemeinde

country xs:string, exact match

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

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

countries.

Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO codeand not with the spelled out country name. With names there is a higher risk of misspells andalso not all language translations for all countries are supported.

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

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

names are not supported for country focus.

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

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

countries specified with country filter.

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

county xs:string, fuzzy match

Second subdivision level below the country. Depending on the admin hierarchy in a countrythis level might not be applicable. Example,



• USA: County

• Germany: Kreis

district xs:string, fuzzy match

Subdivision level below the city. Depending on the admin hierarchy in a country this levelmight not be applicable. Example,

• USA: n/a

• Germany: Ortsteil

gen xs:int

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


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



• gen=2


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



• gen=3


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

gen<3 address results from reverse geocoding only have a display position which

in actuality is the navigation position. With gen=3 this bug is fixed.

◦ MatchType pointAddress for reverse geocoding Point Address results.

Otherwise interpolated. With gen<3 address results from reverse geocoding

always have MatchType interpolated.



◦ 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 providedaccording 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 precedinglanguage preferences are ignored at this time.








locationid xs:string, exact match

A key uniquely identifying a physical location. Each record in a geocode response containsa location Id. Use the Id to retrieve the exact same location information. For example, thelocation 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 twolatitude / longitude pairs; the first pair defines the top left corner of the bounding box, thesecond 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. Forexample, maxresults=5 returns a maximum of 5 results per page. If there were 8 results intotal, the first page of five results indicates that there is a second page with more results.

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

pageinformation xs:string



A key which identifies the page to be returned when the response is separated into multiplepages. Only relevant, if maxresults has been specified in a previous request and theresponse to the request includes the information that there is another page, for example:


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 therequest. Proximity specifies a circle to search using a latitude, a longitude, and a radius inmeters.






searchtext xs:string

searchtext contains free-form text containing address elements. You can specify thesearchtext parameter by itself, or you can specify it with other parameters to narrow yoursearch. For example, you can specify the state or country paramters along with a free-form address in the searchtext field.

state xs:string, exact match

First subdivision level below the country. Specify state using full or abbreviated notation. Acountry specific mapping is required, for example

• US: State

• Germany: Bundesland

street xs:string, fuzzy match

The street name can include suite, apt and floor information. When searching for a streetintersection two formats are supported:

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

street0=McAllister St&street1=Market St

• or concatenating the two streets using one of the predefined separators ("and", "at","&", or "@"), for example:

street=McAllister St @ Market St

strictlanguagemode xs:boolean



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

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

elements. Values in alternative languages are returned in the AlternativeValues

element.

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

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

elements. No alternatives are returned.

token xs:string

An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The tokenis generated based on the user's app_id and received after the registration process of theapplication.

Parameter token is deprecated, use app_code instead.

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

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


Parameter Element



Example:







app_id xs:string




Parameter Element

app_code xs:string



gen xs:int



• gen=1






• gen=2




request.



• gen=3

















Parameter Element





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.








maxresults xs:int



mode One of two values:

retrieveAddresses - Search for the closest street address or addresses

retrieveAreas - Retrieve the administrative area information for the position providedin the request






Parameter Element

prox=lat,lon,radius











element.




token xs:string



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

requests are POST requests.

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


Parameter Element



Example:

additionaldata=PreserveUnitDesignators,true;


Parameter Element

IncludeZipAddon,true






app_id xs:string



app_code xs:string



gen xs:int



• gen=1






• gen=2




request.



• gen=3






Parameter Element
















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.








maxresults xs:int




Parameter Element

mode One of two values:

retrieveAddresses - Search for the closest street address or addresses

retrieveAreas - Retrieve the administrative area information for the position providedin the request













element.




token xs:string



Request Body

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

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

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

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

name1=value1&name2=value2


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

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





Example:







app_id xs:string



app_code xs:string



bbox see also GeoBoundingBoxType on page 68

A type of Spatial Filter. A spatial filter limits the search for any other attributes in therequest. A bounding box bbox is specified by two latitude / longitude pairs; the first pairdefines 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:



• Highway exits: 116

• Airports: 4581

• Tourist attractions: 7999

city xs:string, fuzzy match

A country specific mapping is required. Example,

• USA: City

• Germany: Gemeinde

country xs:string, exact match

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

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

countries.

Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO codeand not with the spelled out country name. With names there is a higher risk of misspells andalso not all language translations for all countries are supported.

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

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

names are not supported for country focus.

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

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

countries specified with country filter.

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

county xs:string, fuzzy match

Second subdivision level below the country. Depending on the admin hierarchy in a countrythis level might not be applicable. Example,

• USA: County

• Germany: Kreis

district xs:string, fuzzy match

Subdivision level below the city. Depending on the admin hierarchy in a country this levelmight not be applicable. Example,

• USA: n/a

• Germany: Ortsteil

gen xs:int



• gen=1








• gen=2




request.



• gen=3














housenumber xs:string, exact match

The house number or house name.
















locationid xs:string, exact match

A key uniquely identifying a physical location. Each record in a geocode response containsa location Id. Use the Id to retrieve the exact same location information. For example, thelocation 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 twolatitude / longitude pairs; the first pair defines the top left corner of the bounding box, thesecond 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



name xs:string

Name of the landmark. The landmark name can also be provided within the searchtext. Usename 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 highwayname and an exit name. Only the exit name should be provided in the name parameter. Beloware two ways how to search for exit 4 on highway A67:

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

• search.xml?searchtext=A67 4






postalcode xs:string, exact match

Postal code defined by the government of the country.


prox=lat,lon,radius







searchtext xs:string

searchtext contains free-form text containing address elements. You can specify thesearchtext parameter by itself, or you can specify it with other parameters to narrow yoursearch. For example, you can specify the state or country paramters along with a free-form address in the searchtext field.

state xs:string, exact match

First subdivision level below the country. Specify state using full or abbreviated notation. Acountry specific mapping is required, for example

• US: State

• Germany: Bundesland

street xs:string, fuzzy match

The street name can include suite, apt and floor information. When searching for a streetintersection two formats are supported:

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

street0=McAllister St&street1=Market St

• or concatenating the two streets using one of the predefined separators ("and", "at","&", or "@"), for example:

street=McAllister St @ Market St





element.






token xs:string



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

Table 9: Key-value pairs for Additional Data

Key Value

CrossingStreets true/false, determines whether the response contains cross streets.

PreserveUnitDesignators true/false, secondary address units as defined by the US Postal Service arerecognized and returned if this switch is set to true. Recognized address units arereturned in the Address.AdditionalData field, where the designator is the keyand 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 beconsidered additionally in the search. Currently only provider ID 24 is supported.Provider 24 adds some addresses in Germany for which the map data does nothave geometry yet. The addresses therefore only have a display coordinate.

If data from an additional address provider is returned, the correspondingLocation element is flagged with an additionalData entryadditionalAddressProvider identifying the provider.

HouseNumberMode Defines how to geocode unknown house numbers. The following values aresupported:

• 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


Key Value

values can be overwritten by passing values for MAX_HSN_DISTANCE and/or

MAX_DISTANCE. If any of the maximum is exceeded the result falls back to

the street level match.

• Fallback <MAX_HSN_DISTANCE>: Use house number fallback. This is the

default value.

Fallback is performed until a predefined maximum distance in house number.

This system-wide configured maximum value can be overwritten by passing

a value for MAX_HSN_DISTANCE. If the maximum is exceeded, the result falls

back to the street level match.

• Streetlevel: Do not do extrapolation or fallback; instead return a

streetlevel match (up-hierarchy).

FlexibleAdminValues N (positive integer <= 1). Customizes flexibility in the input values for the adminhierarchy defined in LocationFilterType. The value is a bitmask defining whichhierarchies might be swapped without impacting the match level:

• 0: No swapping at all (default). Exact admin hierarchy values are expected as

input.

• 1: City and District swapping

IntersectionSnapTolerance N (float in [0, 1]). When reverse geocoding a coordinate, the value controls how

strictly an address match is snapped to the next intersection. A value of 0 indicates

that no points on a link are snapped to an intersection; a value of 1 indicates that

most probably a street intersection is returned as a match. Default value is 0.

AddressRangeSqueezeOffset N (positive integer), offset in meters which moves the first and last locations of an

address range on a link away from the center point of an intersection. If no value

for the 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. OnlypostalCode is supported.

RestrictLevel Area level used to restrict address results. When reverse geocoding a coordinate,only address results within the enclosing admin area of the specified level arereturned. The parameter can be used to restrict results to the country of the inputcoordinate. Only country is supported.

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


Search ResponseThe SearchResponse structure is the top level element returned by geocode, reverse geocode and

landmark geocode requests. It contains Meta Information and one or more View elements. Each view

consists of a list of Results wrapping the actual Location object found for the request together with

information about the Match Quality of the result.

Figure 1: Overview Response Types


Response (SearchResponseType)Table 10: Response elements

Type Description

MetaInfo Meta Information about the Request

View Search Results are grouped in Views.

MetaInfo (SearchResponseMetaInfoType)Table 11: MetaInfo elements

Type Description

RequestId Mirrored RequestId value from the request structure. Can be used to trace

requests.

Timestamp Time at which the search was performed.

NextPageInformation Key which can be used in subsequent requests to acquire the next n results. This

element is only provided if paging has been activated in the request.

PreviousPageInformation Key which can be used in subsequent requests to acquire the previous n results.

This element is only provided if paging has been activated in the request.

AdditionalData List of KeyValuePairType elements as generic container to attach additional

information to the request.

View (SearchResultsViewType)Table 12: View elements

Type Description

ViewId A key to distinguish between different types of views. Always set to 0.

PerformedSearch Search path which was performed for this search run. In case of free-form searches, this element

holds structured information, which indicates how user input has been interpreted by Search. The

Performed Search has the same structure as a search request and can thus be used to repeat the

same search.

Results The resulting items which have been found along with attributes indicating the quality of the

search result.


Result (SearchResultType)The SearchResult contains the actual result as a Location object together with information on how

good the result matches the search request.

Table 13: Result elements

Type Description

Relevance Indicates the relevance of the results found; the higher the score the more relevant

the alternative. The score is a normalized value between 0 and 1.

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/valuesare:

• 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


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


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 andreturned if the PreserveUnitDesignators switch was set to true in the SearchRequestadditionalData field.

Recognized address units are returned in the AdditionalData field, where the designator isthe 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


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 definedkey/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.


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.

MapReference References to a network link and admin areas of the location object.

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:


Element Definition

Label Assembled address value for displaying purposes.

Country ISO 3166-alpha-3 country code

State Includes the first subdivision level below the country. Where commonly used, this is a state code

such as CA for 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"


Element 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 ResponseThe MultiSearchResponseType structure is the top level element returned by multi reverse geocode

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

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

which wrap the Location objects found for the request.

Figure 2: Overview Multi Search Response Types


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 TypesBase Data Types used in the Search Response Structure.


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

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

• Must satisfy: -90 ≤ value ≤ 90

• Unit: decimal degrees

• Reference System: WGS 84

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

Examples

45.1234567-12.345678945.123

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

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

• Must satisfy: -180 ≤ value ≤ 180

• Unit decimal degrees

• Reference System: WGS 84


Query Parameter Representation

Valid examples:

90.1234567-120.345678990.123

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

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

• Unit: meters



Examples

45.1234899344

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

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

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

Examples

DEUGBR

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

The following enumeration values are available for SideOfStreetType:

• left

• right

• neither

ShapeFormatTypeDefines identifiers for the supported shape representations.

The following enumeration values are available for ShapeFormatType:

• WKT

Identifier for Well-known text (WKT)

ReverseGeocodeModeTypeThe following enumeration values are available for ReverseGeocodeModeType:


• retrieveAddresses Search for the closest street address or addresses.

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

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

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

GeoCoordinateTypeThe GeoCoordinateType represents a geographical position.

The following attributes are defined:

• Latitude

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

decimal point

• Longitude

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

decimal point

• Altitude

Altitude in meters. Optional.

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

derived from the abstract base type GeoAreaType.

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

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

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

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

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

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

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

The GeoBoundingBoxType has the following attributes:

• TopLeft

Top-left corner of the rectangular area.

◦ Latitude

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


◦ Longitude

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

◦ Altitude

Altitude in meters (optional)

• BottomRight

Bottom-right corner of the rectangular area.

◦ Latitude


◦ Longitude


◦ Altitude

Altitude in meters (optional)


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

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

Example:

bbox=37.7902858,-122.4027371;37.7890649,-122.3993039

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

GeoAreaType.

The ProximityType has the following attributes:

• Center

Center of the circular area.

◦ Latitude


◦ Longitude


◦ Altitude


Currently unused

• Radius

Radius in meters


The GeoProximityType can be represented in query strings as follows:

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

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

ProximityType element is "prox".

Example: prox=37.7890649,-122.4027371,1000

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

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

representations.

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

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

Well-known_text for more details.

WKTShapeType defines the following attributes:

Value String value containing the WKT representation.

Example:

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

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

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


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

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

The following attributes are defined:

• Key

Name of the property

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


A KeyValuePair can be represented in query strings as follows:

<Key> + "," + <Value>

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

Response Schemas and ExamplesThis chapter provides references to the XML schema locations for all endpoints and examples of

complete service responses in XML format.

XML Schemas

XML Schema for geocode, reversegeocode, and search results

Schema location 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


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>


Example Reverse Geocode Response


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


</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


<?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>


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

geocoder api developer's...

Documents