developer's guide routing api -...

Routing APIDeveloper's Guide

Version 7.2.30

Routing API Developer's Guide 2► Contents

Contents

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

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

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

Why use the Routing API?............................................................................................................................ 8

Customization Options..................................................................................................................... 8

Chapter 2: Quick Start........................................................................................................................... 9Requesting a Simple Route........................................................................................................................10

Requesting a Public Transport Route..................................................................................................... 10

Chapter 3: User Guide......................................................................................................................... 12Acquiring Credentials...................................................................................................................................13

Constructing a Request.............................................................................................................................. 13

GET request.......................................................................................................................................13

Customer Integration Testing.......................................................................................................14

Key Concepts.................................................................................................................................................14

Private Transport Routing............................................................................................................. 14

Public Transport Routing............................................................................................................... 17

Schema Evolution......................................................................................................................................... 26

Service Support............................................................................................................................................ 26

Examples.........................................................................................................................................................26

Calculate Route Examples..............................................................................................................26

Chapter 4: API Reference................................................................................................................. 30Resources and Parameters........................................................................................................................31

Calculate Route................................................................................................................................ 31

Routing API Developer's Guide 3► Contents

Common Parameter Types............................................................................................................35

Response Data Types..................................................................................................................................51

CalculateRouteResponseType.......................................................................................................51

Routing Data Types.........................................................................................................................53

Base Data Types.............................................................................................................................. 87

Error Data Types........................................................................................................................... 103

HTTP Status Codes....................................................................................................................................109

Routing API Developer's Guide 4► Legal Notices

Legal Notices© 2013 HERE. All rights reserved.

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

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

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

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

prior written consent of HERE.

Trademark Acknowledgements

HERE and Nokia are trademarks or registered trademarks of Nokia Corporation in the United States

and other countries.

Other trade names are trademarks or registered trademarks of their owners.

Disclaimer

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

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

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

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

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

content before acting on it.

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

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

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

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

possibility of such damages.

Routing API Developer's Guide 5► Document Information

Document Information

Product

Name: Routing API

Version: Version 7.2.30

Document

Name: Routing API Developer's Guide

Id: a121f69-1380642105

Status: FINAL

Date: 2013-Oct-01, 15:42 (GMT)

Routing API Developer's Guide 6► Overview

Chapter

1

OverviewTopics:

• What is the Routing API?

• Why use the Routing API?

The HERE Routing API calculates routes between two or more

locations and provides additional route-related information, such

as real-time traffic updates.

Route information consists of a graphical representation of the

route and a detailed turn-by-turn route description. It enables

mapping applications to render the geographical representation

of the route together with the map data, so that the route is

displayed on the map.

The Routing API is customizable so that the route calculation and

additional information can be adapted to both consumer and

enterprise applications and specific application use cases.


What is the Routing API?HERE Routing API is a web service API that offers easy and fast routing for several regions in the

world.

The Routing API provides the following capabilities:

• Calculate a route for a set of waypoints.

The following static routing attributes are supported in all HERE digital map formats and are available

in the Routing API:

• form of way (such as roundabouts, ramps, service roads)

• road numbers

• direction of traffic flow (such as one-way, two-way, divided highway)

• road condition

• network classifications

• blocked passages

• special restrictions

• restricted maneuvers

• toll roads

• speed categories

• build up areas

In addition, maps can be enhanced with

• pedestrian information

◦ stairs

◦ elevators

◦ pathways through parks, plazas, buildings, bridges, and tunnels

◦ sidewalks

◦ crosswalks

• public transport information

◦ transit line name

◦ transit company name

◦ transit station name

Note: Public Transport TimeTable Routing and Traffic Enabled Routing are features thatmay be subject to premium pricing. For details please contact your sales representative.


Why use the Routing API?HERE Routing API can be used in a variety of consumer and enterprise applications including

• Navigation and traffic web portals

• Navigation and routing on mobile devices

• Logistics (tour optimization)

• Freight and vehicle exchange portals

Customization OptionsYou can tailor the route calculation for different use cases by

• defining areas or links that the route must not cross

• selecting a means of transportation, such as car, public transport, or pedestrian

• selecting a route type such as fastest, or shortest

• deciding whether to consider current traffic and traffic patterns, seasonal closures, speedcategories and speed limits, road construction status, as well as short and long-term closures

• defining custom penalty parameters to determine the weighting for using specific roadattributes in the route calculation, for example, toll road, motorway, boat and rail ferries, publictransport

Routing API Developer's Guide 9► Quick Start

Chapter

2

Quick StartTopics:

• Requesting a Simple Route

• Requesting a Public TransportRoute

The articles in this section provide information to help you start

using the HERE Routing API.


Requesting a Simple RouteTo calculate directions for private transport between two locations, using the

CalculateRouteRequest, include:

• your authentication credentials, app_id and app_code (see Acquiring Credentials on page 13)

• the start (waypoint0) and destination (waypoint1) waypoints,

• and the mode, which describes the type of route calculation and whether to take traffic intoaccount.

This example requests the fastest route for a car without taking traffic conditions into account.

Note that the waypoints are specified in latitude and longitude by using the geo! string value.

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.5,13.4&waypoint1=geo!52.5,13.45&mode=fastest;car;traffic:disabled

Requesting a Public Transport RouteTo request a public transport route using the CalculateRoute service:

• include your authentication credentials, app_id and app_code (see Acquiring Credentials onpage 13 )

• specify the start (waypoint0) and destination (waypoint1) waypoints,

• and choose a public transport routing mode.

Additionally, we recommend also including the combineChange request parameter, which includes

change maneuvers in the response where the user must switch transit lines, as opposed to enter

and leave maneuver combinations.

This is an example request for the fastest route using estimated public transport routing. It includes

the elements above, specifying the waypoints in latitude and longitude by using the geo! string

value.

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.530,13.326&waypoint1=geo!52.513,13.407&mode=fastest;publicTransport


&combineChange=true

Routing API Developer's Guide 12► User Guide

Chapter

3

User GuideTopics:

• Acquiring Credentials

• Constructing a Request

• Key Concepts

• Schema Evolution

• Service Support

• Examples

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

Routing 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 Routing 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://route.api.here.com

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

Production environment

CIT environment: see CustomerIntegration Testing on page 14

Path /routing/7.2/

Resource calculateroute All support GET and calculateroutealso POST, specify request details viaquery parameters

Format Supported formats:

json

xml

Application Code &app_code=AJKnXv84fjrb0KIHawS0Tg Substitute your own unique

app_code

Application Id &app_id=DemoAppId01082013GAL Substitute your own unique app_id

GET requestHere is an example of a routing request, which uses the HTTP GET method:

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg

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


&waypoint0=geo!52.5,13.4&waypoint1=geo!52.5,13.45&mode=fastest;car;traffic:disabled

The following example shows how to retrieve the same search data in XML format:

http://route.cit.api.here.com/routing/7.2/calculateroute.xml?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.5,13.4&waypoint1=geo!52.5,13.45&mode=fastest;car;traffic:disabled

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

26.

The CIT environment is not intended for general production use.

Key ConceptsThis section provides key concepts that underlie the HERE Routing API.

Private Transport RoutingThis topic provides generic usage instructions and guidelines for Private Transport Routing

functionality.


Private Transport Routing ModeRouting mode allows you to influence the decisions made by the routing engine when creating routes.

Each mode specifies key information, such as the type of routing used (Type), whether you are are

routing for a vehicle, pedestrian or public transport (TransportModes), whether or not to consider

traffic (TrafficMode), and what route features should be considered (Feature).

A given routing mode will specify these pieces of information using the mode request parameter, with

the syntax shown below:

RoutingMode = Type + [TransportModes] + [TrafficMode] + [Feature]

For example, if you requested that the service create the fastest route for a car, without considering

current traffic conditions, your request would include this line:

&mode=fastest;car;traffic:disabled

Routing TypesThe Routing API routing engine prioritizes links included in the route for travel time during the day,

link distance, other features, and current traffic conditions (if enabled).

Most use cases need a route with the fastest travel time, which you can request using the fastest

routing mode, however there may be times when it makes sense to choose another routing mode.

Types prioritize these elements as follows:

• fastest: routing favors the least amount of travel time, can consider traffic if enabled. This isthe most commonly used routing type.

• shortest: routing favors the least amount of travel distance, disregards traffic

Transport ModeThe transport mode for private transport allows you to specify (using the TransportModes request

parameter) the type of vehicle for which you are routing, from the list below.

Note: TransportModes is also used to specify public transport routing. Please see Public

Transport Routing Mode on page 17 for details.

Each transport mode applies different considerations, as described:

• car: routing for cars, adheres to link rules and restrictions (for example, speed limits, directionof travel, etc.), can consider traffic if enabled

• pedestrian: routing for pedestrians, considers pedestrian maneuverability of links, disregardstraffic


Traffic-Enabled RoutingEnabling traffic allows the Routing API to consider up-to-date traffic information when calculating

a route. If the route calculation is performed for the current time, traffic information will be based

on current data. Calculations for future times will use typical traffic patterns to route appropriately.

If the request does not include a departure time, the service will assume that the depature is the

current time.

You can only enable traffic information for some types and transport modes, as described above.

Note: This feauture may be subject to premium pricing. For details please contact your salesrepresentative.

Routing Mode Parameter CombinationsThis section provides valid parameter combinations for routing mode, used in private transport

routing.

Transport Type Mode Combinations

car Traffic-enabled:

• mode=fastest;car;traffic:enabled

Traffic not enabled:

• mode=fastest;car;traffic:disabled

• mode=shortest;car

pedestrian • mode=fastest;pedestrian

• mode=shortest;pedestrian

Attribute SwitchesAttribute switches allow you to select the subset of response data you require for each request.

By default, the Routing API returns a list of [waypoints, summary, and legs]. If you use the

responseattributes request parameter, you can add or remove elements for particular use cases

from this default list.

To save bandwidth and simplify processing, the best practice is to select only the set of attributes

you require, by using the none value and adding required attributes. For example, the following

example returns only route legs.

&responseattributes=none,legs


This example adds shape and notes to the response, in addition to the default list:

&responseattributes=shape,notes

or use the abbreviated forms:

&responseattributes=sh,no

The following example removes legs from the default list:

&responseattributes=-legs

To add notes to the previous example, returning waypoints, summary and notes; use:

&responseattributes=-legs,notes

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

following example returns the whole attribute set except legs .

&responseattributes=all,-legs

For a complete list of attribute switches available in the Routing API, see

RouteRepresentationOptionsType on page 38.

Public Transport RoutingThis topic provides usage instructions and guidelines for Public Transport Routing functionality.

Public Transport Routing ModeRouting API calculates public transport routes in one of two different ways:

• Estimated routing (publicTransport) uses aggregate data to estimate a route. In this mode,

precise departure and arrival times are not available, however an arrival or departure time is not

required.

• Timetable routing (publicTransportTimeTable) uses dynamic data to provide a more

precise, detailed route. In this mode, departure and arrival times are available, but the request

must specify either an arrival or departure time (but not both).

If you request timetable routing, and it is not available, the service returns estimated routing instead.

However if you have specified an arrival time, which is unsupported by estimated routing, the

service returns an error response.


Note: Always use the fastest Routing Mode Type when calculating Public Transport routes.See RoutingTypeType on page 48 for more information.

mode=fastest;publicTransport

Please refer to the table below for key differences between Estimated Routing and Timetable

Routing.

Table 2: Public Transport Routing Feature Availability Matrix

Feature Name Estimated Routing Timetable Routing

Respects public transit access points Yes No

Schematic transit line geometry Yes No

Accurate time information No Yes

Company logo images Yes No

LinkId functionality Yes No

Note: Timetable Routing may be subject to premium pricing. For details please contact yoursales representative.

Calculating Transit Departure TimesIn timetable routing, the service provides scheduled transit departure times in the response, based

on information provided by public transport routing companies. The routing engine incorporates

a time buffer between walking into the station and the actual transit departure time, known as a

waitTime. You can calculate the actual transit departure time by adding the waitTime shown in the

response to the time associated with the maneuver.

The waitTime is also included in the overall travelTime for the route. If you would like strictly the

journey time, you must subtract associated waitTime values from the overall travelTime.

Example: Calculating Departure Time

In the public transport routing response example below, we see that the actual train departure time is

2013-04-10T11:51:00, which is 60 seconds later than the time specified as the maneuver time.

{ "position": {...}, "instruction": "...", "travelTime": 720, "time": "2013-04-10T11:50:00", "action": "enter", "waitTime": 60,


"_type": "PublicTransportManeuverType"}

Example: Calculating Departure Time with a Line Change

If the route itinerary contains a transit line change, waitTime specifies the amount of time available

to change lines. In this example, the journey itself takes only six minutes. Four minutes waitTime is

required to change the transit line:

{ "position": {...}, "instruction": "...", "travelTime": 600, "time": "2013-04-10T12:02:00", "action": "change", "waitTime": 240, "_type": "PublicTransportManeuverType"}

See also: ManeuverType on page 60, PublicTransportManeuverType on page 70.

Arrival and Departure GuaranteesWhen requesting a public transit route, it is not always possible to strictly follow departure and

arrival parameters. Due to transit availability, the schedule might start and end later or earlier

than the time specified. Please use alternate routes to offer more schedule options to the end user.

Alternate RoutesIf requested, the service can provide any available alternate routes. As timetable routing can provide

accurate time information and estimated routing cannot, alternate routes are defined differently for

each type of public transport routing:

In estimated routing, possible alternate routes are:

• Geometrically different from the original route

• Not significantly different from the original route in estimated time of arrival.

In timetable routing, possible alternate routes can be:

• Scheduled at different times

• Via different transport types

• Geometrically different, if not significantly different from the original route in estimated time ofarrival.


Note: As timetable information is highly dynamic, we cannot give any particular guarantees onthe number of and contents of alternate routes.

Requesting Alternate RoutesTo request multiple alternate routes in the response, set the alternatives request parameter

to the number of additional routes that the service should return. For example, if you specify

alternatives=3 in the request, the service can return up to 4 routes in the response: the original

route and three alternates. Note that the alternatives parameter specifies maximum number of

additional routes returned. For any route, the service may or may not find admissible alternates, so it

is possible that even with several alternates requested, the response will contain only one route.

Alternate Route OrderingWe provide different guarantees for route ordering in estimated and TimeTable routing. Common is:

if no alternates are requested the best possible route is returned. Same applies to the first alternate

route - no matter whether estimated or TimeTable rotuing is used, first alternate is the most optimal.

Since notion of alternate route in estimated routing does not allow to sensibly compare routes with

each other, there is no particular guarantees on the order of second and following alternates.

For TimeTable routing, however, ordering is defined as follows:

• If departure time is specified routes are sorted by the time of arrival in ascending order (earlierarrival time is - better).

• If arrival time is specified:

◦ Routes that arrive on time are returned first and are sorted by the time of departure indescending order (later departure time is - better)

◦ Routes that arrive late are returned next and are sorted by the time of arrival in ascendingorder (earlier arrival time is - better).

Copyright NoticesIn certain cases, data provided by Transit Agencies cannot be used without displaying copyright

notices to the end user. If the routing response contains this type of data, the service adds source

attribution information to the route response. Source attribution must be displayed together with a

route. This requirement forms part of the terms and conditions of the API.

Example: Source Attribution in Route Response

If copyright information is available, routing response will contain a sourceAttribution attribute.

It contains ready-to-display string in the attribution attribute, as well as data supplier information

in structured form. See types SourceAttributionType and SourceSupplierType for more

details.

In addition to generic attribution string expressed by SourceAttributionType::Attribution

response can contain additional information about data supplier that has to be exposed in the client

application. This information is included in SourceSupplierType::Note in the form of note

objects. Each note has a specific type so client can distinguish different kinds of notes from each

other. See type SourceSupplierNoteType for details.

Please also find an example of attribution information below:

"response": { "metaInfo": { ... }, "route": [ { "mode": { ... } } ], "language": "en-us", "sourceAttribution": { "attribution": "With the support of <span class=\"company\"%gt;<a href=\"http://example-company-a.com\"%gt;Company A</a%gt;</span%gt;, <span class=\"company\"%gt;<a href=\"http://example-company-b.com\"%gt;Company B</a%gt;</span%gt;. All information is provided without warranty of any kind", "supplier": [ { "title": "Company A", "href": "http://example-company-a.com", "note": [ { "type":"ticketPurchase", "text":"Buy tickets at %lt;a href="http://example-company-a.com/tickets"%gt;example-company-a.com%lt;/a%gt;", "href":"http://example-company-a.com/tickets", "hrefText":"example-company-a.com" } ] }, { "title": "Company B", "href": "http://example-company-b.com" } ] }}

See also: RouteNoteType on page 83, RouteNoteCodeType.


Public Transport ManeuversPublic Transport Rouitng extends maneuvers available in pedestrian mode with following actions:

• enter: maneuver to enter a transit station

• leave: maneuver to either depart the transit station or change public transport lines

• change: maneuver to change public transport lines, only provided if the combineChangeparameter value is set to true, if not then enter and leave pairs are used instead

(see also PublicTransportActionType, combineChange, TransportModeType on page

48)

Maneuver Logic and Ordering

Public transport routes include both pedestrian and public transit segments, using maneuvers for

each as follows:

1. A depart maneuver starts the route in pedestrian mode.

2. Pedestrian maneuvers follow until the first Public Transport section.

3. An enter maneuver starts the public transport section of the route.

4. Optionally, either change or enter-leave maneuver pairs follow to indicate transit linechanges.

5. A leave maneuver ends the public transport section of the route.

6. A continue maneuver begins a segment in pedestrian mode.

7. Optionally, additional public transport and pedestrian segments follow.

8. An arrive maneuver ends the route.

Requesting Additional DataYou can request additional data from the service to provide more detail about lines or maneuvers,

using attribute switches, or to obtain information about company logos, which can then be requested

directly from the Map Image API.

Attribute Switches

Routing API can provide additional data by using attribute switches in the request. When requesting

additional information, the best practice is to request only information that is required by the client.

Fetching information from the service, transmitting it, and parsing it on client side might drastically

affect the overall solution performance.


The most useful attribute switches to use in a public transport route request are:

• routeattributes, which can be used to enable the output of:

◦ lines, or the short version li: public transport line information

◦ groups, or the short version gr: maneuver group information

• maneuverattributes, which controls additional Public Transport Maneuver information

• lineattributes, which controls additional Public Transport line information output

See also: Attribute Switches on page 16.

Maneuver GroupsManeuver groups allow you to organize maneuvers into sections based on TransportModeType, to

better provide the user with an itinerary sumary and brief route instructions.

To request maneuver groups, use group attribute switcher in routeAttributes. Once requested,

groups will provide:

• Identifiers of first and last maneuvers in the group

• Transport mode

• Summary, arrival and wait descriptions in localized text, if available.

Example: Itinerary Summary Using Maneuver Groups

Maneuver groups allow a routing application to display an itinerary summary with similar actions

grouped together, as shown in the example below.

Figure 1: Intinerary Summary

This information is displayed in the response as shown below:

maneuverGroup : [ <3 elem> 0: { firstManeuver : "M1" lastManeuver : "M3" mode : "pedestrian" summaryDescription : "Walk to Reinickendorfer Straße." arrivalDescription : "Arrive at Reinickendorfer Straße." } 1: { firstManeuver : "M4" lastManeuver : "M5" mode : "publicTransport" publicTransportType: "railMetro" summaryDescription : "Take the rail U6 towards Alt-Mariendorf." arrivalDescription : "Get off at Tempelhof." waitDescription : "3 minutes to connect." } 2: { firstManeuver : "M6" lastManeuver : "M11"mode : " pedestrian"summaryDescription : "Get off at Tempelhof and walk to your destination." arrivalDescription : "Arrive at Hessenring." }]

Company LogosCompany logos are exposed from the routing service as an external resource (see

ExternalResourceType). They are available for estimated routing and can be obtained by asking

for companyLogo attribute in lineattributes. If logo is available, it will be returned as follows:

"companyLogo": { "resourceType": "vendorIcon", "filename": "1611547c89c9be1164df5a04d8f393f9"}

Identifier, exposed as a filename can be then used to obtain transit company logo through Map

Image API. Example request is shown below. Please refer to corresponding documentation for more

details.

http://image.maps.cit.api.here.com/mia/1.6/companylogo?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&logoid=1611547c89c9be1164df5a04d8f393f9&w=256

&h=256

Figure 2: The response of the query above contains a logo for a Berlin train station

Format User Instructions with HTML and CSSYou can use predefined CSS classes to format the HTML output of the routing instructions, and

therefore customize presentation to the user. To do this, set the instructionFormat request

parameter to html, which will augment maneuver instructions with HTML markup and associated CSS

classes.

When this is enabled for public transit routing, the service will wrap instruction text in tags

with the following associated classes:

• company: transit company name

• station: station name

• transit: transit type

• line: transit line name

• destination: line destination name

• distance-description: entire statement that describes the distance to proceed, forexample, "follow for n stops"

• stops: number of stops or stations in "follow for" statement, for example, "n stops"

Example: Public Transit Routing Instructions with HTML

Here are some examples of HTML-wrapped output from the service, with associated classes.

For the enter maneuver:

Go to the U station U Pankstr. (Berlin) and take the rail U8 towards S+U Hermannstr. (Berlin). Follow for 1 station.

For change maneuver:

At station S+U Gesundbrunnen Bhf (Berlin) change to the line S1</line> towards S Wannsee Bhf (Berlin). Follow for 1 stations.

For leave maneuver:

Leave the line S1 at station S+U Potsdamer Platz Bhf (Berlin) and leave the station

Schema EvolutionThe two digits of the service version ensure that backward incompatible changes force a change in

the URL. The old version is maintained for a defined period of time. Bugfix releases not impacting the

interface as well as maintenance releases with backward compatible interface changes are deployed

using the same URL.

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

ExamplesThis section provides examples of Routing API requests.

Calculate Route ExamplesThis section provides examples of calculate route requests.

Private TransportThis topic describes example scenarios for private transport routing.

mailto:[email protected]


Requesting a Route Avoiding an AreaTo calculate directions between two coordinates without traveling through a specified area, use the

CalculateRouteRequest service specifying the start (waypoint0), endpoint (waypoint1) and

area to avoid (avoidareas as a rectangular area, defining the top left and bottom right corners).

The string geo! indicates that you are specifying each point using latitude and longitude. Note that

you also have to specify an app_id and app_code (see Acquiring Credentials on page 13), type of

route calculation and whether to take traffic into account.

The following example calculates a route from the Westin Grand hotel (52.516858379, 13.3884717)

at Unter den Linden in Berlin to the Staatsoper in Berlin (52.51733824, 13.394678415)

avoiding passing the Deutsche Guggenheim (52.51704771, 13.39131492) by specifying

a rectangle that contains it (top left 52.517100760,13.3905424488 and bottom right

52.5169701849,13.391808451), and also the fastest route for a car without taking traffic

conditions into account.

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.516858379,13.3884717&waypoint1=geo!52.51733824,13.394678415&mode=fastest;car;traffic:disabled&avoidareas=52.517100760,13.3905424488;52.5169701849,13.391808451

Requesting a Route via a Third CoordinateTo calculate directions between two coordinates via a third coordinate, use the

CalculateRouteRequest service specifying the start (waypoint0), middle point (waypoint1)

and destination (waypoint2). Specifying waypoint1 as stopOver instead of passThrough means

breaking the journey here, not just driving through. The string geo! indicates that you are specifying

each point using latitude and longitude. Note that you also have to specify an app_id and app_code

(see Acquiring Credentials on page 13 ), type of route calculation and whether to take traffic into

account.

In the following example we request the fastest route for a car without taking traffic conditions

into account from the Westin Grand hotel at Unter den Linden in Berlin (52.516858379, 13.3884717)

to the Staatsoper in Berlin (52.51733824, 13.394678415) via the Deutsche Guggenheim

(52.51704771, 13.39131492).

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&mode=fastest;car;traffic:disabled


&waypoint0=geo!52.516858379,13.3884717&waypoint1=geo!stopOver!52.51704771,13.39131492&waypoint2=geo!52.51733824,13.394678415

Public TransportThis topic describes example scenarios for public transport routing.

Requesting a Public Transportation Route by Arrival TimeTo request a public transport route using the CalculateRouteRequest service, you must specify

the start (waypoint0) and destination (waypoint1) waypoints, choose a public transport routing

mode, and request a route note in the response. Additionally, you must include your authentication

credentials, app_id and app_code as with each request to the Routing API.

This request queries a route and specifies the arrival time, using timetable routing:

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!51.512,-0.111&waypoint1=geo!51.519,-0.074&combineChange=true&routeattributes=notes&mode=fastest;publicTransportTimeTable&arrival=2013-09-09T12:44:56

Requesting Additional Details for Public TransportTo request a public transport route using the CalculateRouteRequest service, you must specify




This is an example estimated public transport routing request that also includes additional detail:

specifically line information, maneuver groups, and notes.

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.530,13.326&waypoint1=geo!52.513,13.407&mode=fastest;publicTransport&combineChange=true&routeattributes=li,gr,no&maneuverattributes=all


&lineattributes=all

See also: RoutingModeType on page 47, TransportModeType on page 48.

Request Alternate RoutesTo request a public transport route using the CalculateRouteRequest service, you must specify




This is an example estimated public transport routing request for alternate routes, in addition to the

main route.

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.530,13.326&waypoint1=geo!52.513,13.407&mode=fastest;publicTransport&combineChange=true&alternatives=3

Routing API Developer's Guide 30► API Reference

Chapter

4

API ReferenceTopics:

• Resources and Parameters

• Response Data Types

• HTTP Status Codes

Articles in this section provide a comprehensive reference to the

query parameters supported by the HERE Routing API.


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

API.

Calculate Route http://route.api.here.com/routing/7.2/calculateroute.{format}

Where {format} is either json or xml.

All results returned in xml format have the following properties:

Namespace: http://route.api.here.com/lbsp/Errors/1

http://route.api.here.com/lbsp/Common/4

http://route.api.here.com/lbsp/Routing-Common/4

http://route.api.here.com/lbsp/Routing-CalculateRoute/4

http://route.api.here.com/lbsp/Routing-CalculateMatrix/1

http://route.api.here.com/lbsp/Routing-Version/1

Schema location: http://route.api.here.com/routing/7.2/xsd/LBSP-Errors.xsd

http://route.api.here.com/routing/7.2/xsd/LBSP-Common.xsd

http://route.api.here.com/routing/7.2/xsd/LBSP-Routing-Common.xsd

http://route.api.here.com/routing/7.2/xsd/LBSP-Rout-

ing-CalculateRoute.xsd

http://route.api.here.com/routing/7.2/xsd/LBSP-Rout-

ing-CalculateMatrix.xsd

http://route.api.here.com/routing/7.2/xsd/LBSP-Routing-Version.xsd

XSD Version 4.2

Calculate RouteUse the calculateroute resource to return a route between two waypoints. The required

parameters for this resource are app_id and app_code, two or more way points (waypoint0 and

waypoint1, to waypointN) and mode (specifying how to calculate the route, and for what mode of

transport).

../routing/7.2/calculateroute.{format}?<parameter>=<value>...

Parameter Description

app_id A 20 bytes 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 13.

app_code A 20 bytes 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_idassignedto you, please see Acquiring Credentials on page 13.

waypoint List of waypoints that define a route. The first element marks the start, the last the end

point. Waypoints in between are interpreted as via points.

waypoint0=geo!52.5,13.4

mode The routing mode determines how the route is calculated.

See also RoutingModeType on page 47

Type;TransportModes;TrafficMode;Feature

&mode=fastest;car;traffic:disabled;motorway:2

requestid Clients may pass in an arbitrary string to trace request processing through the system. The

RequestId is mirrored in the MetaInfo element of the response structure.

avoidlinks Links which the route must not cross. List of LinkIdType. LinkIdType is a xs:string with

the following regular expression restrictions: [-]\d+

avoidlinks=-53623477

departure Time when travel is expected to start. Traffic patterns and incidents are taken into

account when calculating the route. Specify either DepartureTime or ArrivalTime, not

both.xs:dateTime

departure=2013-07-04T17:00:00+02:00Z

arrival Time when travel is expected to end, only applies to timetable routing. Traffic patterns and

incidents are taken into account when calculating the route. Specify either DepartureTime or

ArrivalTime, not both. xs:dateTime

alternatives Number of alternative routes calculated. xs:integer

metricsystem The default is the metric system associated with the language settings. xs:string. Enum

[imperial | metric]

viewbounds If the view bounds are given in the request only shapes and links which fit into these boundswill be returned. A common use case for this is the drag and drop scenario where the client is



only interested in a rough visual update of the route in the currently visible bounds. Array ofBoundingBox.

viewbounds=37.7902858,-122.4027371;37.7890649,-122.3993039

resolution Integer resolution of the view in meters per pixel, and optional snap resolution in meters perpixel. Snap resolution lets the routing service to pick links with waypoints that are visible inthe client display resolution.

This information allows the route shape in the response to reflect the client's resolution.

resolution=viewresolution:snapresolutionresolution=300:0,01

alternatives Number of alternative routes calculated. xs:integer

instructionformat Defines the representation format of the maneuver's instruction text. InstructionFormatType

on page 45 instructionformat=Enum [ txt | html]

language A list of languages for all textual information, the first supported language is used. If thereare no matching supported languages the reponse is an error. See Languages on page 38for a list of supported languages.

jsonattributes Flag to control JSON output. Combine parameters by adding their values. See also JSON

Representation on page 50 .

jsonattributes=2

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

representation Define which elements are included in the response as part of the data representation of theroute. See also RouteRepresentationModeType on page 40.

Enum[overview | display | dragNDrop | navigation | linkPaging | turnByTurn]

routeattributes Define which atrributes are included in the response as part of the data representation of theroute. Defaults to waypoints, summary, legs, lines. See also RouteAttributeType on page40.

Enum[waypoints | summary | | shape | boundingBox | legs | notes | lines |compressShapes ]

legattributes Define which attributes are included in the response as part of the data representationof the route legs. Defaults to maneuvers, waypoint, length, travelTime. See alsoRouteLegAttributeType on page 41.

Enum [waypoint | maneuvers | links | length | travelTime | shape | indices] |boundingBox | baseTime | trafficTime | summary |

maneuverattributes Define which attributes are included in the response as part of the data representationof the route maneuvers. Defaults to position, length, travelTime. See alsoManeuverAttributeType on page 41

Enum[ position | shape | travelTime | length | time | link | publicTransportLine| roadName | nextRoadName | roadNumber | nextRoadNumber | signPost | notes| action | direction | freewayExit | freewayJunction | indices | baseTime |

trafficTime | waitTime | | boundingBox | compressedShapes | roadShield |startAngle ]

linkattributes Define which attributes are included in the response as part of the data representation ofthe route links. Defaults to shape, speedLimit, . See also RouteLinkAttributeType on page43.

Enum[shape , length | speedLimit | dynamicSpeedInfo | flags | address| roadNumber | roadName | nextLink |publicTransportLine | remainTime| remainDistance | maneuver | functionalClass | nextStopName | speedCategory | predecessors | indices | compressedShapes]

lineattributes Sequence of attribute keys of the fields that are included in public transport line elements. If

not specified, defaults to lineForeground, , . PublicTransportLineAttributeType

[GeneralizationTolerances] Species the desired tolerances for generalizations of the base route geometry. Tolerances

are given in degrees of longitude or latitude on a spherical approximation of the Earth. One

meter is approximately equal to 0:00001 degrees at typical latitudes. xs:double

maxnumberofchanges int

Maximum number of transit changes. PublicTransportType

mindurationforchange PublicTransportType

Duration needed to change from one transport line to the next.

avoidtransporttypes PublicTransportType

List of transport types not to include in the response route.

walkTimeMultiplier Allows to prefer or avoid public transport routes with longer walking distances. A value > 1.0

means a slower walking speed and will prefer routes with less walking distance.

combineChange Enables the change maneuver in the route response, which indicates a public transit line

change. In the absence of this maneuver, each line change is represented with a pair of

subsequent enter and leave maneuvers. We recommend enabling combineChange

behavior wherever possible, to simplify client-side development.

combineChange=true

Example Request

http://route.cit.api.here.com/routing/7.2/calculateroute.xml?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!52.5,13.4&waypoint1=geo!52.5,13.45&mode=fastest;car;traffic:disabled

Example Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<rtcr:CalculateRoute xmlns:rtcr="http://www.navteq.com/lbsp/Routing-CalculateRoute/4"> <Response> <MetaInfo> <Timestamp>2013-05-21T14:49:50.645Z</Timestamp> <MapVersion>8.0.49.122</MapVersion> <ModuleVersion>7.2.26.0_CD-336_1</ModuleVersion> <InterfaceVersion>2.4.31</InterfaceVersion> </MetaInfo> <Route> <Waypoint> <LinkId>-1609300611616932926</LinkId> <MappedPosition> <Latitude>52.4999823</Latitude> <Longitude>13.3999649</Longitude> </MappedPosition> <OriginalPosition> <Latitude>52.5</Latitude> <Longitude>13.4</Longitude> </OriginalPosition> <Type>stopOver</Type> <Spot>0.3606557</Spot> <SideOfStreet>left</SideOfStreet> <MappedRoadName>Neuenburger Straße</MappedRoadName> <Label>Neuenburger Straße</Label>

Common Parameter Types

WaypointParameterTypeSpecify route waypoints in one of the following manners:

• a rough position: GeoWaypointParameterType

• a reference to a street: NavigationWaypointParameter with StreetPositions

• an exact reference to a link: NavigationWaypointParameter with LinkPositions


GeoWaypointParameterType

The GeoWaypointParameterType defines a waypoint by latitude and longitude coordinates, and an

optional radius. Parameter structure:

waypoint = geo + [Type] + Position + [TransitRadius]

Parameter component Structure Description

geo geo! Indicates that the parameter contains ageographical position.

[Type] Enum[stopOver! | passThrough!] 180 degree turns are allowed forstopOver but not for passThrough.Waypoints defined through a drag-n-drop action should be marked as pass-through. PassThrough waypoints will notappear in the list of maneuvers.

Position Latitude, Longitude, [Altitude];

37.7914050,-122.3987030,25;

Latitude WGS-84 degrees between -90and 90. Longitude WGS-84 degreesbetween -180 and 180. Altitude inmeters.

[TransitRadius] TransitRadius

200

Matching Links are selected within thespecified TransitRadius, in meters.For example to drive past a city withoutnecessarily going into the city centeryou can specify the coordinates ofthe center and a TransitRadius of5000m.

NavigationWaypointParameterType with StreetPositions

The NavigationWaypointParameter defines a waypoint by street position and name. The street

name helps select the right road in complex intersection scenarios such as a bridge crossing another

road. A common use case for this scenario is when the user specifies a waypoint by selecting a place

or a location after a search.

The optional display position of the waypoint defines where the location is displayed on a map. It

denotes the center of the location and is not navigable, i.e. it is not located on a link in the routing

network in contrast to the navigation positions of a location. The display position allows the routing

engine to decide whether the waypoint is located on the left or on the right-hand side of the route.

Parameter structure:

waypoint0 = street + [Type] + [DisplayPosition] + StreetPosition


URL component Structure Description

street street! Indicates that parameters contains astreet position.

[Type] Enum[stopOver! | passThrough!] 180 degree turns are allowed forstopOver but not for passThrough.Waypoints defined through a drag-n-drop action should be marked as pass-through. PassThrough waypoints will notappear in the list of maneuvers.

[DisplayPosition] Latitude, Longitude, [Altitude];

37.3456,56.778,567;

Latitude WGS-84 degrees between -90and 90. Longitude WGS-84 degreesbetween -180 and 180. Altitude inmeters.

StreetPosition Latitude, Longitude, [Altitude],[StreetName]

WGS-84 degrees between -90 and 90.Altitude in meters. There can be multiplestreet positions in one parameter.

NavigationWaypointParameterType with LinkPositions

The NavigationWaypointParameter defines a waypoint by LinkId and SideOfStreet with optional

Spot value. Spot is defined as the fractional distance from the link's reference-node to the non-

reference node, with a value between 0 and 1. SideofStreet indicates whether the waypoint is on the

left or right side of the link when heading from the reference node to the non-reference node.

The optional display position of the waypoint defines where the location is displayed on a map. It

denotes the center of the location and is not navigable, i.e. it is not located on a link in the routing

network in contrast to the navigation positions of a location. The display position allows the routing

engine to decide whether the waypoint is located on the left or on the right-hand side of the route.

Parameter structure:

waypoint0 = street + [Type] + [DisplayPosition] + LinkId + [Spot] + SideofStreet


link street! Indicates that request contains a link position.

[Type] Enum[stopOver!|passThrough!]

180 degree turns are allowed for stopOver butnot for passThrough. Waypoints defined througha drag-n-drop action should be marked as pass-through. PassThrough waypoints will not appear inthe list of maneuvers.

[DisplayPosition] Latitude, Longitude, [Altitude];

37.3456,56.778,567;

Latitude WGS-84 degrees between -90 and 90.Longitude WGS-84 degrees between -180 and 180.Altitude in meters.



LinkPosition LinkId, [Spot], SideOfStreet

743460795,0.1342,right

Id of the Link position, Relative position of thelocation along the link between 0 and 1, left orright side of the street. There can be multiplestreet positions in one parameter.

RouteRepresentationOptionsTypeIn many use cases, not all objects and attributes in the route's object model are required at once.

The enumeration type RouteRepresentationMode defines which parts of the route are returned

by services for standard use cases. Any custom route representation definition besides these

predefined modes is possible by using the detailed AttributeType switches (see RouteAttribute,

RouteLegAttribute, RouteAttribute, ManeuverAttribute and RouteLinkAttribute).

Parameter representation:

LanguagesThe Routing API supports the following languages. The language codes are listed in parentheses.

Language Maneuvers Itinerary warnings Public transportmaneuvers/groups

English – United

Kingdom (en-gb)

+ + +

English – United States

(en-us)

+ + +

German – Germany (de-

de)

+ + +

Czech – Czech Republic

(cs-cz)

+ +

Danish – Denmark (da-

dk)

+ +

Dutch – Netherlands

(nl-nl)

+ +

Finnish – Finland (fi-fi) + +

French – France (fr-fr) + + +


Language Maneuvers Itinerary warnings Public transportmaneuvers/groups

Italian – Italy (it-it) + + +

Norwegian – Norway

(no-no)

+ +

Polish – Poland (pl-pl) + + +

Portuguese – Brazil (pt-

br)

+ +

Portuguese – Portugal

(pt-pt)

+ + +

Spanish – Spain (es-es) + +

Swedish – Sweden (sv-

se)

+ +

Simplified Chinese –

China (zh-cn)

+ +

Traditional Chinese –

Taiwan (zh-tw)

+ +

Hungarian – Hungary

(hu-hu)

+ +

Greek – Greece (el-gr) + +

Turkish – Turkey (tr-tr) + +

Romanian – Romania

(ro-ro)

+ +

Japanese – Japan (ja-jp) + +

Russian – Russia (ru-ru) + + +

Slovenian – Slovenia (sl-

sl)

+ +


RouteRepresentationModeType

Enumeration Description

overview Overview mode only returns the Route and the RouteSummary object

display Display mode that allows to show the route with all maneuvers. Links won't be

included in the response

dragNDrop Drag and Drop mode to be used during drag and drop (re-routing) actions. The

response will only contain the shape of the route restricted to the view bounds

provided in the representation options.

navigation Navigation mode to provide all information necessary to support a navigation

device. This mode activates the most extensive data response as all link

information will be included in the response to allow a detailed display while

navigating.

linkPaging Paging mode that will be used when incrementally loading links while navigating

along the route. The response will be limited to link information.

turnByTurn Turn by turn mode to provide all information necessary to support turn by turn.

This mode activates all data needed for navigation excluding any redundancies.

RouteAttributeType

Enumeration Short value Description

waypoints wp Indicates whether via points shall be included in the route.

summary sm Indicates whether a route summary shall be provided for the

route.

shape sh Indicates whether the shape of the route shall be provided

for the route.

boundingBox bb Indicates whether the bounding box of the route shall be

provided for the route.

legs lg Indicates whether the legs of the route shall be provided for

the route.

notes no Indicates whether additional notes shall be provided for the

route.

lines li Indicates whether PublicTransportLines shall be provided for

the route.


RouteLegAttributeType


waypoint wp Indicates whether the waypoint shall be included in the route

leg.

maneuvers mn Indicates whether the maneuvers of the route leg shall be

provided.

links li Indicates whether the links along the route leg shall be

provided.

Length le Indicates whether the route leg should include its length

travelTime tt Indicates whether the route leg should include its duration

shape sh Indicates whether the shape of the segment to the next

maneuver should be included in the maneuvers.

indices ix Indicates whether shape index information (FirstPoint,

LastPoint) should be included in the maneuvers instead of

copying shape points to the maneuver.

boundingBox bb Indicates whether the bounding box of the maneuver shall be

provided.

baseTime bt Indicates whether the BaseTime information should be

provided in RouteLegs.

trafficTime tm Indicates whether the TrafficTime information should be

included in RouteLegs.

summary sm Indicates whether distance and time summary information

should be included in RouteLegs.

ManeuverAttributeType


position po Indicates whether the position should be included in the

maneuvers.

shape sh Indicates whether the shape of the segment to the next

maneuver should be included in the maneuvers.

travelTime tt Indicates whether the time needed to the next maneuver

should be included in the maneuvers.

length le Indicates whether the distance to the next maneuver should

be included in the maneuvers.



time ti Indicates whether the point in time when the maneuver will

take place should be included in the maneuvers.

link li Indicates whether the link where the maneuver takes place

shall be included in the maneuver.

publicTransportLine pt Indicates whether the information about the public transport

line should be included in the maneuvers.

platform pl Indicates whether the platform information for a public

transport line should be included in the maneuvers.

equipment eq Indicates whether equipment at the maneuver should be

included in the maneuvers.

lane la Indicates whether lane information should be included in the

maneuvers.

roadName rn Indicates whether the road name should be included in the

maneuvers.

nextRoadName nr Indicates whether the name of the next road shall be included

in the maneuvers.

roadNumber ru Indicates whether the road number should be included in the

maneuvers.

nextRoadNumber nu Indicates whether the number of the next road should be


roadTemplate rt Indicates whether the template for route display should be


signPost sp Indicates whether the sign post information should be


notes no Indicates whether additional notes should be included in the

maneuvers.

action ac Indicates whether actions should be included in the

maneuvers.

direction di Indicates whether directions should be included in the

maneuvers.

nextManeuver nm Indicates whether a reference to the next maneuver should

be included in the maneuvers.

freewayExit fe Indicates whether the freeway exit should be included in the

maneuvers.

freewayJunction fj Indicates whether the freeway junction should be included in

the maneuvers.



baseTime bt Indicates whether the BaseTime information should be

included in the maneuvers. By default, BaseTime information

is not included in the maneuvers.

trafficTime tm Indicates whether the TrafficTime information should

be included in the maneuvers. By default, TrafficTime

information is not included in the maneuvers.


LastPoint) should be included in the maneuvers instead of

copying shape points to the maneuver.

boundingBox bb Indicates whether the bounding box of the route shall be

provided for the route.

roadShield rs Indicates whether road shield information should be included

in the maneuvers.

startAngle sa Indicates whether start angle information should be included

in the maneuvers.

waitTime wt Indicates whether wait time information should be included in

public transport maneuvers.

RouteLinkAttributeType


Shape sh Indicates whether the link should include its geometry

length le Indicates whether the link should include its length

speedLimit sl Indicates whether the link should include SpeedLimit

dynamicSpeedInfo ds Indicates whether the link should include dynamic speed

information

incidents ic Indicates whether the link should include incidents

truckRestrictions tr Indicates whether the link should include truck restrictions

externalResources er Indicates whether the link should include external resources

flags fl Indicates whether the link should include link flags

address ad Indicates whether the link should include the link's address

roadNumber rn Indicates whether the link should include the link's road

number

roadName ro Indicates whether the link should include the link's road

number



freewayExit fe Indicates whether the link should include the name of the

freeway exit

freewayJunction fj Indicates whether the link should include the name of the

freeway junction

timezone tz Indicates whether the link should include the timezone

corridorLevel cl Indicates whether the link should include the corridor level

nextLink nl Indicates whether the link should include the link which will be

next when following the route

stubs st Indicates whether the link should include the corridor stubs

publicTransportLine pt Indicates whether the link should include information about

the public transport line.

TMCCodes tm Indicates whether the link should include information about

the covered TMC Codes.

jamFactor jf Indicates whether the link's dynamic speed info should

include information about the jam factor.

jamFactorTrend jt Indicates whether the link's dynamic speed info should

include information about the jam factor trend.

confidence co Indicates whether the link's dynamic speed info should

include information about the level of confidence with

respect to traffic information.

remainTime rt Indicates whether the link should include information about

the remaining time until the destination is reached.

remainDistance rd Indicates whether the link should include information about

the remaining distance until the destination is reached.

maneuver ma Indicates whether the link should include information about

the associated maneuver.

functionalClass fc Indicates whether the link should include information about

the functional class.

nextStopName ns Indicates whether the link should include information about

the next stop.

additionalData dd Indicates whether the link should include the container for

additional data.

speedCategory sc Indicates whether the link should include speed category

information.

predecessors pr Indicates whether the link should include predecessor link ID

information.

successors su Indicates whether the link should include predecessor link ID

information.


LastPoint) should be included in links instead of copying

shape points.

InstructionFormatTypeRepresentation formats for instruction texts.

• text returns the instruction as a plain text string

• native based on the message templates used in the routing engine with the different parameter

values being tagged with corresponding xml tags. For example:

<junction>AS. Frankfurt-Friedberger Landstr.</junction>

• html instruction format is based on span tags with different CSS classes to assign semantics to

the tagged part of the instruction. For example:

AS. Frankfurt-Friedberger Landstr.

Table 3: HTML Instruction CSS Classes

CSS Class Description Example

street road name Lilienweg

city city name Frankfurt

country country name (currently not used.) Germany

direction turn direction text left

junction junction and exit name; in Europe most often

used with a junctionname and a exit name; in the

US most often only the exit number

Bad Homburger Kreuz (17)

sign signpost information Weilburg, Usingen, Oberursel-Oberstedten

number road number A5, E451

heading cardinal directions north

length segment length, including the metric type 5.5 miles

time travel time; used in the last summary instruction 39 min

price toll information (currently not used)

CSS Class Description Example

transit Transit type train

line transit line S5

company Transit line company RMV

arrivalsummary Class to markup summaries in last instructions

per leg. The instruction text for this class may

include other spans for different classes

The trip takes 4 miles and 10 mins.

distance-

description

Provides information on travel distances in

instruction texts.

Go for 43 miles

company part of transit line name

exit roundabout exit number

next-street name of next street heading towards ...

Examples of HTML with CSS Classes

"Take exit AS. Frankfurt-FriedbergerLandstr. tothe left ontoA661 towardsOberursel,Friedberg, Kassel, Bad Homburg, 661. Go for 5.5 miles."

Turn right onto <spanclass="street">US-101 South towards Los Angeles. Go for 30 miles.

Take exit Bad Homburger Kreuz (17) onto A5 towards Kassel, Giessen. Go for 20 miles.

Go for 43 miles

Instruction> Arrive at <spanclass="street">Knobelsdorffstraße. <spanclass="arrivalsummary">The trip takes <spanclass="length">4 miles and 10mins.<Instruction>

The trip takes 4 miles and <spanclass="time">10 mins.


BoundingBoxTypeA BoundingBoxType defines a rectangular area in a geographic coordinate system by specifying the

top left and bottom right corners of the area. Parameter representation:

bbbox = TopLeft + BottomRight

Parameter component Description

TopLeft Top-left corner of the rectangular area. Latitude WGS-84 degrees between -90 and 90.Longitude WGS-84 degrees between -180 and 180. Altitude in meters.

Latitude, Longitude, [Altitude]

bbox=37.7902858,-122.4027371;37.7890649,-122.3993039

BottomRight Top-left corner of the rectangular area. Latitude WGS-84 degrees between -90 and 90.Longitude WGS-84 degrees between -180 and 180. Altitude in meters.

Latitude, Longitude, [Altitude]

bbox=37.7902858,-122.4027371;37.7890649,-122.3993039

RoutingModeTypeThe RoutingMode specifies how the route is calculated. Parameter representation:

RoutingMode = Type + [TransportModes] + [TrafficMode] + [Feature]

Parameter component Structure

Type RoutingType relevant to calculation. See also RoutingTypeType on page 48.

ENUM [fastest | shortest ];

[TransportModes] Specify which mode of transport to calculate the route for. See alsoTransportModeType onpage 48.

ENUM [car | pedestrian | publicTransport | publicTransportTimeTable |

bicycle];

[TrafficMode] Specify whether to take traffic into account. See also TrafficModeType on page 48.

traffic: Enum [enabled | disabled | default]

[Feature] Route feature weightings to be applied when calculating the route. As many as required.

See also RouteFeatureWeightType on page 49.


Parameter component Structure

RouteFeatureType: RouteFeatureWeightType

motorway:-2;

&mode=fastest;car;traffic:disabled;motorway:2

RoutingTypeTypeRoutingType provides identifiers for different optimizations which can be applied during the route

calculation. Selecting the routing type affects which constraints, speed attributes and weights are

taken into account during route calculation.

When calculating Public Transport routes, always use fastest mode.


fastest Route calculation from start to destination optimizing based on the travel time. If

the travel time forecast is considering current traffic information depends on the

provided traffic mode.

shortest Route calculation from start to destination disregarding any traffic conditions. In

this mode, the distance of the route is minimized.

TrafficModeType


enabled Take the dynamic traffic conditions into account (current traffic, traffic patterns,

short term closures, long term closures)

disabled Do not take dynamic traffic conditions into account (only apply time restrictions

and seasonal closures)

default Let the service automatically apply traffic related constraints that are suitable

for the selected routing type, transport mode, and departure time. Also user

entitlements will be taken into consideration.

TransportModeTypeDepending on the transport mode special constraints, speed attributes and weights are taken into

account during route calculation.



car Route calculation for cars.

pedestrian Route calculation for a pedestrian. As one effect, maneuvers will be optimized for

walking, i.e. segments will consider actions relevant for pedestrians and maneuver

instructions will contain texts suitable for a walking person. This mode disregards

any traffic information.

RouteFeatureTypeThe routing features can be used to define special conditions on the calculated route. The user can

weight each feature with positive or negative weights, see type RouteFeatureWeight.


tollroad Identifier for toll roads

motorway Identifier for motorways

boatFerry Identifier for boat ferries

railFerry Identifier for rail ferries

publicTransport Identifier for public transport

tunnel Identifier for tunnels

dirtRoad Identifier for dirt roads

park Identifier for links through parks

HOVLane Identifier for high-occupancy vehicle (HOV) lanes

stairs Identifier for stairs. This route feature is only applicable for pedestrian routing.

RouteFeatureWeightTypeRoute feature weights are used to define weighted conditions on special route features like tollroad,

motorways, etc.


-3 strictExclude The routing engine guarantees that the route does not contain

strictly excluded features. If the condition cannot be fulfilled no route is returned.

HOVLanes and stairs are examples where a strict exclusion might be required.

-2 softExclude The routing engine does not consider links containing the

corresponding feature. If no route can be found because of these limitations the

condition is weakened.



-1 avoid The routing engine assigns penalties for links containing the corresponding

feature.

0 normal The routing engine does not alter the ranking of links containing the

corresponding feature.

1 prefer The routing engine will prefer links containing the corresponding route

feature.

JSON RepresentationThe jsonAttribute parameter controls the JSON response represntation. Combine different

values by adding the respective values.

Value Description

1 Lower case first character of identifiers

2 Include null elements in JSON output. The default is to suppress null elements

4 Include empty collections and arrays in JSON output. The default is to suppress empty

collections.

8 Include _type element in JSON output for classes with abstract parent classes, this is the

default behaviour.

16 Use plural naming for collections. The default is to use singular naming.

32 Flatten list of shape strings to double arrays containing lat/lon pairs. Potentially available

altitude values are not returned. By default shapes are returned as lists of strings.

64 Flatten list of shape strings to double arrays containing lat/lon/alt triplets. Altitude values are

returned if available. By default shapes are returned as lists of strings.

128 Supress JSON response object wrapper.

For example, to specify JSON output with lowercased identifiers (1), including _type attributes (8) and

a double representation of shape points (32) use jsonAttributes=41:

http://route.cit.api.here.com/routing/7.2/calculateroute.json?app_id=DemoAppId01082013GAL&app_code=AJKnXv84fjrb0KIHawS0Tg&waypoint0=geo!37.7914050,-122.3987030&waypoint1=geo!37.7866569,-122.4026513&jsonAttributes=39&mode=fastest;car;


Response Data TypesArticles in this section provide a comprehensive reference to data types used throughout the Routing

API.

This section covers the high-level data structure for each routing capability (for example,

CalculateRouteResponseType), and then the included types, categorized as either Routing Data

Types or Base Data Types.

Routing Data Types directly enable the routing process. Examples of these types include:

• link information (for example, type of link, characteristics of the link, relationship to other links)

• vehicle information (for example, maneuvering capabilities)

• route information (for example, start and end point of the route, route sections, waypoints alongthe route, metadata)

Base Data Types provide more generalized information about the environment where routing is being

conducted. Examples of these types include:

• measurements (for example, speed, weight, distance)

• geometry types (for example, bounding box, corridor)

• location-based information (for example, latitude, longtitude, country, language)

• general (ID types, outside resources, additional information containers)

Base Data Types may also be common to other mapping-related services offered by HERE.

CalculateRouteResponseTypeCalculateRouteResponseType contains response data, structured to match a particular

request for the CalculateRoute operation. The Route element may appear more than once

in the response if multiple routes are available between the start and end points. Refer to

CalculateRouteRequestType, described in Calculate Route on page 31 for details on

associated request elements.


Data elements may be hidden if they contain no data.

Figure 3: CalculateRouteResponseType

CalculateRouteResponseType defines the following attributes:

Table 4: Response Elements

Element Description

MetaInfo RouteResponseMetaInfoType on page 75

Provides details about the request itself, such as the time at which it wasprocessed, a request id, or the map version on which the calculation was based.

Route RouteType on page 77

Contains the calculated path across a navigable link network, as specified in therequest. Routes contain navigation instructions for a single trip as: waypoints


Element Description

(fixed locations) and route legs (sections of the route between waypoints). Eachresponse may also include information about the route itself, such as its overallshape, map location, or a summary description.

Language LanguageCodeType on page 96

Indicates the language used for all textual information related to the route.

If the requested language is unavailable, the service defaults to the generic versionof the requested language, if available. For example, if the request specifies BritishEnglish (en-uk), and this is unavailable, the service returns the response usingAmerican English instead (en-us).

See Languages on page 38 for a list of supported languages.

Routing Data TypesThese types directly enable the routing process. They are used by CalculateRoute. Routing Data

Types fall into these categories:

• Enumeration Types on page 54, which are simple, routing-related types that are restricted toa limited set of acceptable values

• link information (for example, type of link, characteristics of the link, relationship to other links)

◦ RouteLinkType on page 78

◦ PrivateTransportLinkType on page 63

◦ PublicTransportLinkType on page 69

◦ PublicTransportLineType on page 67

◦ PublicTransportStopType on page 73

◦ DynamicSpeedInfoType on page 58

• vehicle information (for example, maneuvering capabilities)

◦ ManeuverType on page 60

◦ PrivateTransportManeuverType on page 65

◦ PublicTransportManeuverType on page 70

• route information (for example, start and end point of the route, route sections, waypoints along

the route, metadata)

◦ RouteResponseMetaInfoType on page 75

◦ RouteType on page 77

◦ RouteLegType on page 80

◦ WaypointType on page 85

◦ RouteSummaryType on page 84

◦ Enumeration Types on page 54

◦ RoadShieldType on page 74

◦ RouteNoteType on page 83


Enumeration TypesType

LineStyleType

Line style used to draw a line.

Enum [solid, dotted, dash]

RouteLinkFlagType

Defines a list of special characteristics that may apply to a link.

Enum [boatFerry, dirtRoad, motorway, noThroughRoad, railFerry, tollroad,tunnel]

• boatFerry: Link can only be traversed by using a boat ferry

• dirtRoad: Link is part of a dirt road

• motorway: Link is part of a motorway

• noThroughRoad: Link is part of a road that you can enter but you have to exit the same way

• railFerry: Link can only be traversed by using a rail ferry

• tollroad: Link is part of a toll road

• tunnel: Link passes through a tunnel

RouteNoteTypeType

Defines type identifiers for RoutingNote objects.

Enum [info, warning, restriction, violation, traffic]

• info: Indicates an additional information for the maneuver or the segment leading to the maneuver, like "border

crossing", "segment includes tunnel/bridge/toll/unpaved/etc."

• warning: Indicates a note with warning character, like "sharp curve ahead".

• restriction: Indicates a note providing additional information about time dependent restrictions on the segment

("road closed during winter").

• violation: Indicates a note providing additional information about violated routing options, such as route contains

tollroads even though it has been requested to avoid tollroads.

• traffic: Indicates a note providing additional information on traffic.

RouteNoteCodeType

Defines identifiers for RoutingNote objects.

Enum [ copyright, routingOptionViolated, passingPlace, roadNameChanged, sharpCurveAhead,linkFeatureAhead, timeDependentRestriction, previousIntersection, nextIntersection,adminDivisionChange, countryChange, gateAccess, privateRoad, tollbooth, tollroad, unpavedRoad,restrictedTurn, seasonalClosures, congestion, roadworks, accident, closure, trafficFlow]

• routingOptionViolated: Indicates that routing options have been violated, in other words, the route contains route

features that should have been avoided. The service provides the violated routing feature as text.

• copyright: Contains copyright notices that must be displayed to the end user when using data provided by Transit

Agencies.


Type

• previousIntersection: Indicates the name of a previous intersection in a maneuver, such as for indicating the last

intersection before arrival. The service provides the name of the intersection along with a descriptive text in the Text

field of the corresponding note, such as "The last intersection is Markkulantie"

• nextIntersection: Indicates the name of a next intersection in a maneuver, such as for indicating the last

intersection before arrival. The service provides the name of the intersection along with a descriptive text in the Text

field of the corresponding note, such as "If you reach Rantalantie, you've gone too far".

• adminDivisionChange: Indicates that some part of route crosses administrative division border (state, province, etc.)

• countryChange: Indicates that some part of route crosses country border.

• gateAccess: Indicates that some part of route enters or leaves a gated area.

• privateRoad: Indicates that some part of route runs through a privately owned road.

• tollBooth: Indicates that some part of route may require a stop at a toll booth.

• tollRoad: Indicates that some parts of the route are toll roads.

• unpavedRoad: Indicates that some part of route is unpaved.

• restrictedTurn: Indicates that some parts of the route may be subject to turn restrictions.

• seasonalClosures: Indicates that one should expect seasonal closures on some part of route.

• congestion: Indicates that one should expect congestions on some part of route.

• roadworks: Indicates that there are roadworks expected on some part of route.

• accident: Indicates that there has been an accident reported on some part of route.

• closure: Indicates that there is a road closure affecting the route.

• trafficFlow: Indicates that there is traffic flow (such as sluggish traffic) affecting the route.

PublicTransportActionType

Enumeration to identify different action types needed for public transport maneuvers.

Enum[enter, leave]

PublicTransportTypeType

Enumeration to identify different action types needed for public transport maneuvers

Enum[busPublic, busTouristic, busIntercity, busExpress, railMetro, railMetroRegional railLight,

railRegional, trainRegional, trainIntercity, trainHighSpeed, monoRail, aerial, inclined, water,

privateService]

PublicTransportLinkFlagType

Enumeration to identify additional attributes classifying a public transport link.

Enum[barrierFree]

ResourceTypeType

Defines a list of supported resource type identifiers.

Enum[junctionView, signAsReal, directionArrow, advertising, vendorIcon, vendorLogo, routeTemplate]

• junctionView: Identifier for the bitmap representing the Junction View

• signAsReal: Identifier for the bitmap representing the sign-as-real information


Type

• directionArrow: Identifier for the bitmap representing the direction arrow at a junction. Displayed on top of the

junction view

• advertising: Identifier for the bitmap representing any kind of advertisement

• vendorIcon: Identifier for the bitmap representing the vendor icon, such as of a public transport system.

• vendorLogo: Identifier for the bitmap representing the vendor logo, such as of a public transport system

• routeTemplate: Identifier for the svg resource representing a template for displaying routes (such as highway signs).

Clients will have to include the route number in the graphic to display a concrete route sign

DirectionType

Enumeration type to identify directions at a maneuver.

Enum [ forward, bearRight, lightRight, right, hardRight, uTurnRight, uTurnLeft, hardLeft,left, lightLeft,

bearLeft]

SideOfStreetType

Enumeration type to identify on which side of a link an object is placed.

Enum [ left, right, neither]

WaypointParameterTypeType

Enumeration type to identify waypoint varieties.

Enum [ stopOver, passThrough]

• stopOver: 180 degree turns are allowed to continue on the route

• passThrough: route does not support a break. These points do not appear in list of maneuvers.

Note: Waypoints defined through a drag and drop action should be marked as passThrough.

PrivateTransportActionType

Describes maneuvers actionable by a private transport vehicle or pedestrian.

Enum [ depart, departAirport, arrive, arriveAirport, arriveLeft, arriveRight,

leftLoop,leftUTurn,sharpLeftTurn, leftTurn, continue, slightRightTurn, rightTurn,sharpRightTurn,

rightUTurn, rightLoop, leftExit, rightExit, leftRamp, rightRamp, leftFork, middleFork, rightFork,

leftMerge, rightMerge, nameChange, trafficCircle, ferry ,leftRoundaboutExit1, leftRoundaboutExit2,

leftRoundaboutExit3, leftRoundaboutExit4, leftRoundaboutExit5, leftRoundaboutExit6,

leftRoundaboutExit7, leftRoundaboutExit8, leftRoundaboutExit9, leftRoundaboutExit10,

leftRoundaboutExit11, leftRoundaboutExit12, rightRoundaboutExit1, rightRoundaboutExit2,

rightRoundaboutExit3, rightRoundaboutExit4, rightRoundaboutExit5, rightRoundaboutExit6,

rightRoundaboutExit7, rightRoundaboutExit8, rightRoundaboutExit9, rightRoundaboutExit10,

rightRoundaboutExit11, rightRoundaboutExit12]

• depart: departure maneuver, such as "Start at"

• departAirport: departure at an airport maneuver, such as "Start toward the airport exit"

• arrive: Identifer for an arrival maneuver., such as "Arrive at"

• arriveAirport: Identifer for an arrival at the airport maneuver, such as "Follow the signs to your terminal"


Type

• arriveLeft: Identifer for an arrival maneuver with the destination on the left-hand side, such as "Arrive at"

• arriveRight: Identifer for an arrival maneuver with the destination on the right-hand side, such as "Arrive at"

• leftLoop: left-hand loop maneuver., such as "Make a left-hand loop onto"

• leftUTurn: left-hand U-turn maneuver., such as "Make a U-turn at"

• sharpLeftTurn: sharp left turn maneuver., such as "Make a hard left turn onto"

• leftTurn: left turn maneuver, such as "Turn left on"

• slightLeftTurn: slight left turn maneuver., such as "Bear left onto"

• continue: continue maneuver, such as "Continue on"

• slightRightTurn: slight right turn maneuver., such as "Bear right onto"

• rightTurn: right turn maneuver, such as "Turn right on"

• sharpRightTurn: sharp right turn maneuver., such as "Make a hard right turn onto"

• rightUTurn: right u-turn maneuver., such as "Make a right U-turn at"

• rightLoop: right loop maneuver, such as "Make a right-hand loop onto"

• leftExit: left exit maneuver, such as "Take the left exit to"

• rightExit: right exit maneuver, such as "Take the right exit to"

• leftRamp: left ramp maneuver, such as "Take the left ramp onto"

• rightRamp: right ramp maneuver, such as "Take the right ramp onto"

• leftFork: left fork maneuver, such as "Take the left fork onto"

• middleFork: middle fork maneuver, such as "Take the middle fork onto"

• rightFork: right fork maneuver, such as "Take the right fork onto"

• leftMerge: left merge maneuver, such as "Merge left onto"

• rightMerge: right merge maneuver, such as "Merge right onto"

• nameChange: name change maneuver (no maneuver action needed), such as "Road becomes"

• trafficCircle: traffic circle maneuver, such as "At the traffic circle take the exit to"

• ferry: ferry maneuver, such as "Take the ferry to"

• leftRoundaboutExit1: roundabout maneuver (left-hand traffic), such as "Take the first exit of the roundabout onto"

• leftRoundaboutExit2: roundabout maneuver (left-hand traffic), such as "Take the second exit of the roundabout

onto"

• leftRoundaboutExit3: roundabout maneuver (left-hand traffic), such as "Take the third exit of the roundabout

onto"

• leftRoundaboutExit4: roundabout maneuver (left-hand traffic), such as "Take the fourth exit of the roundabout

onto"

• leftRoundaboutExit5: roundabout maneuver (left-hand traffic), such as "Take the fifth exit of the roundabout onto"

• leftRoundaboutExit6: roundabout maneuver (left-hand traffic), such as "Take the sixth exit of the roundabout

onto"

• leftRoundaboutExit7: roundabout maneuver (left-hand traffic), such as "Take the 7th exit of the roundabout onto"



Type


• leftRoundaboutExit10: roundabout maneuver (left-hand traffic), such as "Take the 10th exit of the roundabout

onto"


onto"


onto"

• rightRoundaboutExit1: roundabout maneuver (right-hand traffic), such as "Take the first exit of the roundabout

onto"

• rightRoundaboutExit2: roundabout maneuver (right-hand traffic), such as "Take the second exit of the roundabout

onto"

• rightRoundaboutExit3: roundabout maneuver (right-hand traffic), such as "Take the third exit of the roundabout

onto"

• rightRoundaboutExit4: roundabout maneuver (right-hand traffic), such as "Take the fourth exit of the roundabout

onto"

• rightRoundaboutExit5: roundabout maneuver (right-hand traffic), such as "Take the fifth exit of the roundabout

onto"

• rightRoundaboutExit6: roundabout maneuver (right-hand traffic), such as "Take the sixth exit of the roundabout

onto"

• rightRoundaboutExit7: roundabout maneuver (right-hand traffic), such as "Take the 7th exit of the roundabout

onto"


onto"


onto"


onto"


onto"


onto"

DynamicSpeedInfoTypeTo provide an estimat of time that is as close to the current reality as possible, the

DynamicSpeedInfoType contains dynamic speed information on the link.

The service provides this data if the departure time and date is part of the route calculation request.

If traffic is enabled for the request, the route calculation accounts for:


• time-dependant road closures and maneuvers (such as seasonal closures, reversible lanes, time-dependent truck restrictions)

• real-time traffic information and incidents

DynamicSpeedInfoType is an xs:sequence type with the following data elements.

Figure 4: DynamicSpeedInfoType

Element Description

TrafficSpeed SpeedType on page 98

Traffic-enabled speed, which is the estimated speed considering traffic-relevantconstraints.

TrafficTime xs:duration on page 100

Contains the travel time estimate for this element, considering traffic andtransport mode. Based on the TrafficSpeed. The service may also account foradditional time penalties, so this may be greater than the element length dividedby the TrafficSpeed.

BaseSpeed SpeedType on page 98

Estimated speed without considering any traffic-related constraints.

BaseTime xs:duration on page 100

Contains the travel time estimate for this element, considering transport modebut not traffic conditions. Based on the BaseSpeed. The service may also accountfor additional time penalties, therefore this may be greater than the elementlength divided by the BaseSpeed.


GeneralizationTypeThe service returns GeneralizationType in route responses for requests carrying the

generalizationTolerances parameter. The default is to not return any GeneralizationType.

Figure 5: GeneralizationType

Element Description

Tolerance xs:double

Contains the tolerance level used in the request.

Index xs:int

Specifies the offset into the global shape array to be used for a givengeneralization tolerance.

ManeuverTypeA maneuver describes the action needed to leave one street segment and enter the

following street segment to progress along the route. This type is an abstract base class for

PrivateTransportManeuverType on page 65 and PublicTransportManeuverType on page 70. It

includes only attributes that are common for any given maneuver type.


Note: In this element, the Length, Shape, and Note refer to the leg immediately followingthe maneuver.

Figure 6: ManeuverType

ManeuverType defines the following attributes:

Attribute Description

id ElementReferenceType on page 91

Key that identifies this element uniquely within the response.

ManeuverType defines the following data elements:

Element Description

Position GeoCoordinateType on page 92

Position where the maneuver starts.


Element Description

Instruction xs:string

Description of the required maneuver, for example, "Turn left onto Minna St."Response format for this description can be either text or HTML as selected inInstructionFormatType on page 45, and using the measurement systemspecified in the request, either metric or imperial.

For an automated unit conversion, we recommend using MetricSystem=metric,which returns values in kilometers and meters instead of yards and miles.

TravelTime xs:duration on page 100

Describes the amount of time for a single maneuver, traffic considered if this hasbeen enabled.

See also: TrafficMode.

Length DistanceType on page 90

Length (in meters) for the leg between this maneuver and the next.

Shape GeoPolylineType on page 93

Shape of the leg between this maneuver and the next.

FirstPoint xs:int

Index into the global geometry array, pointing to the first point of the shapesubsegment associated with this Maneuver. Must be followed by LastPoint.

LastPoint xs:int

Index into the global geometry array, pointing to the last point of the shapesubsegment associated with this Maneuver. Must be preceded by FirstPoint.

Time xs:dateTime

Estimated point in time when the maneuver should occur, based on the selectedtransport mode. Options include:

• Public transport: scheduled arrival or departure time for the line

• Private transport: calculated arrival or departure time for the maneuver.

The time information is given in the time zone of the maneuver's position. See alsoPublic Transport Routing Mode on page 17 for information on differences betweentime handling in each routing mode.

Note RouteNoteType on page 83

Additional information about the route segment following the maneuver, such as"sharp curve ahead", "accessing toll road", etc.

ToLink LinkIdType on page 97

The key of the next outgoing link.

BoundingBox GeoBoundingBoxType on page 94

Coordinates defining the bounding box of the entire maneuver.


PrivateTransportLinkTypeA private transport link is a link traversed in a route using private mode of transportation such as car,

truck, pedestrian.

Figure 7: PrivateTransportLinkType


PrivateTransportLinkType defines the following attributes in addition to those derived from

RouteLinkType:

Element Description

SpeedLimit SpeedType on page 98

Legal speed limit (based on link only, unrelated to vehicle type). Contains thefollowing reserved values:

• 999: indicates that there is no speed restriction for link

• 998:

◦ United States: marked on ramps as from/toward reference speed limit

◦ Europe: marked on ramps as from/toward reference speed limit, if no

posted speed limit or motorway symbol exists

• 0: no speed limit available, value will be hidden in the response.

DynamicSpeedInfo DynamicSpeedInfoType on page 58

Dynamic speed information on the link which can change over time, such as trafficinformation (if enabled) or time-dependent road closures.

Flags RouteLinkFlagType

Flags that describe special characteristics of the link, such as "motorway","tollroad", "ferry", etc.

FreewayExit xs:string

Name of the freeway exit that the link is passing

FreewayJunction xs:string

Name of the freeway junction that the link is passing.

FunctionalClass FunctionalClassType on page 92

The functional class assigned to the link.

RoadNumber xs:string

Number of the road (such as A5, B49, etc.) that the link is passing.

RoadName xs:string

Name of the road the link is passing.

SuccessorLinkIds xs:list

List of LinkIds that can be accessed from the current link. See also LinkIdTypeon page 97.

PredecessorLinkIds xs:list

List of LinkIds that can be used to enter the current link. See also LinkIdType onpage 97.


PrivateTransportManeuverTypeA private transport could be a car, truck, or pedestrian. This type represents a maneuver relevant in

those scenarios, and is derived from the abstract type ManueverType.

Figure 8: PrivateTransportManeuverType

PrivateTransportManeuverType defines the following attributes in addition to those derived

from ManeuverType:


Element Description

Direction DirectionType

Maneuver direction hint. Can be used to display the appropriate arrow icon for themaneuver.

Action PrivateTransportActionType

Code that identifies the action for this maneuver. Does not always indicate adirection.

RoadName xs:string

Name of the road on which the maneuver begins.

SignPost xs:string

Sign text indicating the direction a driver should follow, for example, "FlughafenBerlin-Tegel, Berlin-Zentrum, Berlin-Zehlendorf, Potsdam-Zentrum, A115"

NextRoadName xs:string

Name of the next road in the route that the maneuver is heading toward.

RoadNumber xs:string

Number of the road where the maneuver starts (for example, A5, B49).

NextRoadNumber xs:string

Number of the road (such as A5, B49, etc.) towards which the maneuver is heading.

FreewayExit xs:string

Name of the freeway exit to be taken at the maneuver.

FreewayJunction xs:string

Name of the freeway junction for the current maneuver.


Traffic-enabled time. Estimated time spent on the segment following thismaneuver, based on the TrafficSpeed. The service may also account foradditional time penalties, therefore this may be greater than the link lengthdivided by the traffic speed.


Estimated time spent on the segment following this maneuver, withoutconsidering traffic conditions, as it is based on the BaseSpeed. The service mayalso account for additional time penalties, therefore this may be greater than thelink length divided by the base speed.

RoadShield RoadShieldType on page 74

Information that can be used to look up a visual representation of the road shieldassociated with this maneuver.

StartAngle xs:int


Element Description

Start angle information for the given maneuver, measured in degrees from 0 to359. A value of 0 represents north, while a value of 90 represents east. Anglesincrease clockwise.

PublicTransportLineTypeDefines the information available for a public transport line.

Figure 9: PublicTransportLineType

PublicTransportLineType defines the following attributes:


Table 5: Public Transport Line Type Attributes

Element Description

LineName xs:string

Name of the line

LineForeground xs:string

Color that is to be used as foreground color when drawing the line.

LineBackground xs:string

Color that is to be used as background color when drawing the line.

LineStyle LineStyleType

Style that is to be used when drawing the line.

CompanyName xs:string

Name of the transit line's company

CompanyShortName xs:string

Short name of the transit line's company

CompanyLogo ExternalResourceType on page 91

Logo of the transit line's company

Destination xs:string

Final destination of the transport line

Flags PublicTransportLinkFlagType

Additional attributes classifying the transport line

Type PublicTransportTypeType

Type of the transport line

TypeName xs:string

Name of the transport line's type (such as "ICE", "TGV", etc.).

Note: This type is not officially supported. While it may appear in the

response, it will be empty and is provided soley to avoid compatibility

issues.

Stops PublicTransportStopType on page 73

List of all stops on this public transport line.


PublicTransportLinkTypeA public transport link is a link traversed in a route using public transport.

Figure 10: PublicTransportLinkType

In addition to its base type RouteLinkType, the PublicTransportLinkType defines the following

attributes:


Element Description

NextStopName xs:string

Name of the stop at the end of the link.

Line ElementReferenceType on page 91

Reference key to the PublicTransportLine object. To reduce data volume, thePublicTransport element is not directly embedded in the ManeuverType object, butis swapped out into the Route element.

NextStopId TransitStopIdType on page 99

List of intermediate stops. These stops are not changes. Intermediate stops onlyprovide additional information for the customer and show the customer the route.

PublicTransportManeuverTypeThis type represents a maneuver relevant for public transport such as bus, train. This type is derived

from the abstract type ManueverType.

Two different types of public transport maneuvers are supported: "Enter" and "Leave" (see

enumeration type PublicTransportActionType). A direct change between two transport lines


is represented with two maneuvers: one for the action "Leave" and a subsequent one to "Enter" the

next transport line.

Figure 11: PublicTransportManeuverType


In addition to its base type ManueverType, the PublicTransportManeuverType defines the

following attributes:

Element Description

Action PublicTransportActionType

Identifier for the action to be performed at this maneuver.

StopName xs:string

Name of the stop where the user has to leave (action == "Leave") or enter (action== "Enter") the transport line.

PlatformName xs:string

Platform name where the transport line stops (action == "Leave") or starts from(action == "Enter").

PlatformLevel xs:string

Platform level where the transport line stops (action == "Leave") or starts from(action == "Enter").


Reference key to the PublicTransportLine object. To reduce data volume, thePublicTransport element is not directly embedded in the ManeuverType object, butis swapped out into the Route element.

ToLine ElementReferenceType on page 91

Reference key to the PublicTransportLine object for the target line. This element isonly provided in case of a "change" Maneuver (action == "Change" and if returningof "change" maneuvers has been requested using the "CombineChange" flag inPublicTransportProfile . To reduce data volume, the PublicTransport element is notdirectly embedded in the ManeuverType object, but is swapped out into the Routeelement.

StopId TransitStopIdType on page 99

Permanent DiCi Id of the Transit Stop where the user has to leave (action =="Leave") or enter (action == "Enter") the transport line. This id is related to theDiscover Cities Database.

AccessPointName xs:string

Name of the Access Point where the user has to enter or leave the public transportstation. Only published when the name of the access point differs from thestopname.

AccesPointId TransitAccessIdType on page 99

Permanent Id for the Access Point based on DiCi data.

NextRoadName xs:string

Name of the road towards which the exit should be taken for Action=leave.


PublicTransportStopTypeInstances of PublicTransportStopType Represent stops on a public transport line. Stops are different

from stations as they are bound to a specific public transport line and a direction of travel, indicated

by the line's destination.

Figure 12: PublicTransportStopType

PublicTransportStopType defines the following attributes:

Attribute Description

id ElementReferenceType on page 91

Key that identifies this element uniquely within the response.

PublicTransportStopType defines the following elements:

Element Description

Position GeoCoordinateType on page 92

The position of this stop.


Reference key to the PublicTransportLine object

StopName xs:string

The name of this stop.



Element Description

The time required to travel from this stop to the next one using the publictransport line specified in the ‘Line’ element.

RoadShieldTypeRoadShieldType contains information used to look up road shield imagery.

Figure 13: RoadShield Type

RoadShieldType defines the following attributes:

Element Description

Region xs:string

A string identifying the region where this road shield is used. This may be used todifferentiate roadshield images by country.

Category xs:string

A string identifying the category of the road shield, such as highways.

Label xs:string

A Label identfying the inscription on the road shield, such as containing the roadnumber.

The information provided in RoadShieldType entries may be used to query dedicated services for

road shield imagery to be displayed in UIs or textual descriptions of the route. Such services may be

provided separately.


The examples below demonstrate road shield imagery for the Allen Expressway in Toronto, Ontario,

and Interstate 10 in the United States.

Figure 14: Road Shield Examples

RouteResponseMetaInfoTypeMeta information which is not directly related to the route calculation is wrapped within a separate

element.

Table 6: Route Response MetaInfo elements

Element Description

RequestId xs:string

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

Timestamp xs:string

Time at which the search was performed.

AdditionalData KeyValuePairType on page 96

List of KeyValuePairType elements as genericcontainer to attach additional information tothe request. The defined key/values are:

• Service: [servicename]+ “, “ + [serviceversion]

• Map0, Map1: Information regarding underlying map(s):[map id] + “, “+ [map version]

• Module0, Module1: Information regarding the underlying module(s):[module id] + “, “ +[module version]

Note: Not yet supported.


Element Description

MapVersion xs:string

Gives the version of the underlying map, upon which the route calculations are based.

ModuleVersion xs:string

Gives the version of the module that performed the route calculations.

InterfaceVersion xs:string

Required. Gives the version of the schema definition to enable formats other than XML toidentify elements without using namespaces.


RouteTypeA Route describes a distinct path through the navigable road network between two or more

waypoints. It consists of route legs, each of which is a path between two waypoints.

Figure 15: RouteType

RouteType defines the following attributes:

Element Description

Waypoint WaypointType on page 85

List of waypoints that have been defined when requesting for a route calculation.The first waypoint is defined as the start of the route; the last waypoint marks thedestination. Any points in between the two are considered via points.

Mode RoutingModeType on page 47


Element Description

Settings for route calculation. One mode can be specified for each route.


Shape of the route as a polyline. The accuracy might depend on the resolutionspecified in mpp (meters per pixel) when requesting the route. In some usecases (like web portals), only the route's shape is required without the nestedstructure of a route and detailed knowledge of the links and LinkIds. In this case,the shape does not need to be acquired by traversing the route's links, but can berepresented using this attribute at route level.


Bounding Box of the route.

Leg RouteLegType on page 80

Partition of the route into legs between the different waypoints.

PublicTransportLine PublicTransportLineType on page 67

List of all public transport lines which are used by public transport links andmaneuvers of the route.

Note RouteNoteType on page 83

Notes that are either related to the calculation (violated routing options) or thatrefer the route as a whole. In addition to these notes additional notes can beattached to maneuvers. The maneuver notes are usually related to the routesegment following the maneuver and would be of interest when passing thissegment.

Summary RouteSummaryType on page 84

Overall route distance and time summary.

Generalizations Enumeration Types on page 54

A simplified base polyline with a given tolerance parameter used to reduce thenumber of points. The points in the base polyline are implicitly referenced byindex.

RouteLinkTypeA link is a path segment in the routing network, such as a road. This type is an abstract base class for

PublicTransportLinkType on page 69 and PrivateTransportLinkType on page

63 . It includes the common attributes that every that every link type provides.


In this type, FirstPoint and LastPoint be used as alternate representation to avoid repeating

shapes already provided at the route level.

Figure 16: RouteLinkType

RouteLinkType defines the following attributes:

Element Description

LinkId LinkIdType on page 97

Permanent ID which references a network link. When presented with a minus signas the first character, this ID indicates that the link should be traversed in theopposite direction of its default coding (for example, walking SW on a link that iscoded as one-way traveling NE).


A polyline representation of the parent element (for example, route, route leg, link,etc.).

FirstPoint xs:int

Index into the global geometry array, pointing to the first point of the shapesubsegment for the associated element (for example, maneuver, link). Must befollowed by LastPoint.

LastPoint xs:int

Index into the global geometry array, pointing to the last point of the shapesubsegment for the associated element (for example, maneuver, link). Must bepreceded by FirstPoint.


Element Description


Length of the parent element, always provided in meters.

RemainDistance DistanceType on page 90

Distance from the start of this element to the destination of the route.

RemainTime xs:duration on page 100

Time needed from the start of this element to the destination of the route.Considers any available traffic information, if enabled and the authorized for theuser.

NextLink LinkIdType on page 97

Reference to the next link on the recommended route.

Maneuver ElementReferenceType on page 91

Reference to the maneuver that needs to take place to go from the current link tothe next link in the route.

RouteLegTypeThe service defines a route leg as the portion of a route between one waypoint and the next.

RouteLegType contains information about a route leg, such as the time required to traverse it, its

shape, start and end point, as well as information about any sublegs contained in the leg due to the

presence of passthrough waypoints.


Note: passThrough waypoints do not create explicit route legs, but instead create sublegs.The service provides subleg information within this type if any are present.

Figure 17: RouteLegType

RouteLegType defines the following attributes:

Element Description

Start WaypointType on page 85


Element Description

Route waypoint that is located at the start of this route leg. This waypoint matchesone of the waypoints in the Route.

End WaypointType on page 85

Route waypoint that is located at the end of this route leg. This waypoint matchesone of the waypoints in the Route.


Length of the leg.


The time needed to travel along this route leg. Considers any available trafficinformation, if enabled and the authorized for the user.

Maneuver ManeuverType on page 60

List of all maneuvers which are included in this portion of the route.

Link xs:list

List of all links which are included in this portion of the route. See also LinkIdType on page 97 .


Bounding Box of the leg.


Shape of route leg.

FirstPoint xs:int

Index into the global geometry array, pointing to the first point of the shapesubsegment associated with this leg. Must be followed by LastPoint.

LastPoint xs:int

Index into the global geometry array, pointing to the last point of the shapesubsegment associated with this leg. Must be preceded by FirstPoint.


Time required for this route leg, taking available traffic information into account.


Estimated time spent on this leg, without considering traffic conditions. Theservice may also account for additional time penalties, therefore this may begreater than the leg length divided by the base speed.

Summary RouteSummaryType on page 84

Distance and time summary information for the route leg.

SubLegSummary RouteSummaryType on page 84


Element Description

Distance and time summary information for any sub legs of this route leg. Theservice defines sub legs where passThrough waypoints are used, so the list may beempty if no such waypoints exist within this route leg.

RouteNoteTypeRoute notes are used to store additional information about the route. These notes can either be

related to the calculation itself (like violated routing options) or to the characteristics of the route

(like entering a toll road, passing a border, etc.).

Figure 18: RouteNoteType

RouteNoteType defines the following elements:

Element Description

Type RouteNoteTypeType

Type of the note. Please refer to the enumeration type RouteNoteTypeType foravailable values.

Code RouteNoteCodeType

A code that uniquely identifies the note. This code can be used to decide how todisplay the note (such as with a warning icon). Please refer to the enumeration typeRouteNoteCodeType for available values.

Text xs:string


Element Description

A short text describing the note. Please note that this attribute is not subject tointernationalization and should therefore not be used in user displays.

AdditionalData KeyValuePairType on page 96

Container for additional data to be stored along with the note.

RouteSummaryTypeThis type provides summary information for the entire route. This type of information includes travel

time, distance, and descriptions of the overall route path.

Figure 19: RouteSummaryType

RouteSummaryType defines the following attributes:

Element Description

Distance DistanceType on page 90

Indicates total travel distance for the route, in meters.


Contains the travel time estimate for this element, considering traffic andtransport mode. Based on the TrafficSpeed. The service may also account foradditional time penalties, so this may be greater than the element length dividedby the TrafficSpeed.


Contains the travel time estimate for this element, considering transport modebut not traffic conditions. Based on the BaseSpeed. The service may also accountfor additional time penalties, therefore this may be greater than the elementlength divided by the BaseSpeed.


Total travel time not considering traffic but taking the transport mode intoaccount.


Element Description


Total travel time optionally considering traffic depending on the requestparameters.

WaypointTypeWaypoints are points (including start and end points) along the route, based on input specified in

the route request. They can also be defined as passThrough, such as a case where the road changes

names and no stopover action is required.

If the the request does not pass a coordinate when specifying the waypoint, the originalPosition

attribute will not be filled.

Figure 20: WaypointType

WaypointType defines the following elements:

Element Description

LinkId LinkIdType on page 97

ID of the link on the navigable network associated with the waypoint.

MappedPosition GeoCoordinateType on page 92


Element Description

If this waypoint is a start point, this will be mapped to the beginning of the link. Ifused as destination point or via point, it will be mapped to the end of the link.

OriginalPosition GeoCoordinateType on page 92

Original position as it was specified in the corresponding request. The value willdepend on request construction:

• If using a NavigationWaypointParameterType, the service will set

OriginalPosition as the display position (if specified) or as the navigation

position selected by the routing engine (if not specified in the request).

• If using a GeoWaypointParameterType, the service will set the

OriginalPosition as the position specified in the request.

• If using a PositioningWaypointParameterType or any other cases, the

service will set the OriginalPosition as empty.

Type WaypointParameterTypeType

Defines the type of the waypoint, either stopOver or passThrough.

StopId TransitStopIdType on page 99

The DiscoverCities StopId of the Public Transport Stop as specified in thecorresponding request.

Spot xs:double

Contains the relative position of the mapped location along the link, as thefractional distance between the link's reference node and the non-reference node.Ranges in value from 0 to 1.

SideOfStreet SideOfStreetType

Indicates whether the waypoint is on the left or right side of the link, when headingfrom the reference node to the non-reference node.

MappedRoadName xs:string

Displays the name of the street to which the request waypoint was mapped.

Label xs:string

A label identifying this waypoint, generated by the routing service. Label is eithera street name or a public transport stop, depending on the transport mode of therequest.

UserLabel xs:string

Used to identify a waypoint point with a custom name. Copied verbatim asspecified in the request.

ShapeIndex xs:int

Specifies the index of this waypoint, based on the global shape array that isprovided at the route level.


Base Data TypesBase Data Types provide information that underlies the routing process, such as data about the

environment where routing is being conducted. These fall into the categories below:

• measurements (for example, speed, weight, distance)

◦ SpeedType on page 98

◦ DistanceType on page 90

◦ WeightType on page 90

◦ HeadingType on page 95

◦ AccuracyType on page 88

◦ AngleType on page 88

◦ FunctionalClassType on page 92

• geometry types (for example, bounding box, corridor)

◦ GeoCoordinateType on page 92

◦ CoordinatesArrayType on page 89

◦ GeoBoundingBoxType on page 94

• location-based information (for example, latitude, longtitude, country, language)

◦ LatitudeType on page 97

◦ LongitudeType on page 97

◦ AltitudeType on page 88

◦ LanguageCodeType on page 96

◦ CountryCodeType on page 90

• general (ID types, outside resources, additional information containers)

◦ KeyValuePairType on page 96

◦ ElementReferenceType on page 91

◦ ExternalResourceType on page 91

◦ LinkIdType on page 97

◦ TransitSystemIdType on page 98

◦ TransitStopIdType on page 99

◦ TransitAccessIdType on page 99

◦ SideOfStreetType on page 98

◦ TextSemanticsType on page 98

• standard XML schema types, including how the Routing API handles these elements in for JSONformat requests

◦ xs:dateTime on page 99

◦ xs:duration on page 100

◦ xs:list on page 101

◦ xs:sequence on page 102

AccuracyTypeThe accuracy type is used to specify the accuracy level of measured coordinates.

The accuracy level is specified in meters and must be a non-negative real number.

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

• Must satisfy: 0 < value

• Unit: meters

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

Examples

0.510

AltitudeTypeThe altitude specifies the elevation of a point above mean sea level.

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

• Unit: meters


Examples

300-12512.50

AngleTypeAngle in degrees.

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

• Must satisfy: -360 ≤ value ≤ 360

• Unit: degrees from reference node

Examples

48-57

CoordinatesArrayTypeIn many use cases, coordinates appear in large series. However, using a sequence of many

Coordinate typed elements in data structures might bloat the document instances.

To provide a more compact format, the CoordinatesArray type allows concatenating serialized

coordinates within a single data element.

The CoordinatesArray is list type with items of type xs:string, where the following restrictions apply:

• Item separator: space character (according to the xs:list definition)

• Allowed item types: Coordinate, in query parameter representation

The list is ordered, but the order does not have any defined semantics. If you wish to be more distinct

regarding the semantics of the listed coordinates, you might find the GeoPolylineType on page 93

or GeoPolygonType on page 91 type useful.

XML Representation

The following example illustrates how the CoordinatesArray looks like for a list of two 2#dimensional

coordinates:

<Foo>37.7914050,-122.3987030 37.7866569,-122.4026513</Foo>

Query Parameter Representation

According to the standard representation format for list types, the CoordinatesArray would be

represented in query strings as:

<Coordinate[]>

Notes on representation formats: Coordinate - see representation format for GeoCoordinateType

The XML example would be represented as query string as:

37.7914050,-122.3987030;37.7866569,-122.4026513


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

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

WeightTypeThis type can be used whenever weights need to be represented (for example, when defining truck

restrictions on links).

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

• Must satisfy: 0 ≤ value

• Unit: t (metric tons)



Valid examples:

5.123

5

GeoPolygonTypeWhile the CoordinatesArrayType on page 89 merely defines an ordered list of coordinates, the

PolygoneType can be used to express that the subsequent connection between the points form a

polygon. In contrast to the GeoPolygonType on page 91, it is assumed that the last coordinate

within the list is connected with the first coordinate and thus constructs an enclosed geometry.

The PolylineType directly derives from the CoordinatesArrayType and can be represented in the same

manner.

ElementReferenceTypeThis type is used whenever an element needs to be cross-referenced. ElementReferenceType is an

xs:string with no further restrictions.

The Common Data Model explicitly does not use the xs:ID construct to make element referencing

transparent to other representation formats than XML.

ExternalResourceTypeReference to an external resource (for example, a bitmap). The client is responsible for retrieving the

referenced resource. Contains the following:

• ResourceType

The semantics of the resource.

• Filename

Filename of the resource

Examples

<CompanyLogo><ResourceType>vendorIcon</ResourceType><Filename>727e0c0e687629564b2f83f465f74626</Filename></CompanyLogo>

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

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

• Must satisfy: 1 ≤ value < 5

The value represents one of the five levels:

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

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

• 3: providing a high volume of traffic movement

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

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

Examples

123

GeoCoordinateTypeThe GeoCoordinateType represents a geographical position.

Figure 21: GeoCoordinateType

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.


Whenever a coordinate needs to be represented in query strings, use the following format:

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

GeoPolylineTypeWhile the CoordinatesArrayType on page 89 merely defines an ordered list of coordinates, the

PolylineType can be used to express that the subsequent connection between the points form a

polyline.

The PolylineType directly derives from the CoordinatesArrayType and can be represented in

the same manner.


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

derived from the abstract base type GeoAreaType.

Figure 22: GeoBoundingBoxType

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

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

◦ Longitude

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

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

If possible (in other words, if there is no risk of name clashes) the preferred name for the parameter

of a BoundingBoxType element is "bbox".

Example:

bbox=37.7902858,-122.4027371;37.7890649,-122.3993039

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

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

used whenever directions need to be represented.

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

• Must satisfy: 0 ≤ value < 360

• Unit: decimal degrees

• Measured: clockwise starting at 0 degrees at true North


Examples

90.1265.130

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.

Figure 23: KeyValuePairType

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.

LanguageCodeTypeThis type is used whenever a language of a value needs to be referenced.

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

• Format: Language code following RFC5646


Examples

deen-US

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

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


• Unit: decimal degrees

• Reference System: WGS 84


Examples

45.1234567-12.345678945.123 -12.3

LinkIdTypeA network link can be identified using the LinkIdType as functional key.

It is used by different complex types (for example, RouteLinkType and MapLinkType).

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

• Must match the following regular expression: [-]\d+

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

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


• Unit decimal degrees

• Reference System: WGS 84




Valid examples:

90.1234567-120.345678990.123 -120.3

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

The following enumeration values are available for SideOfStreetType:

• left

• right

• neither

SpeedTypeThis type can be used whenever speed information needs to be represented.

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

• Unit: m/s


Examples

90.1265.130

TextSemanticsTypeAvailable types of text semantics used in type AlternativeValue. Enumeration [synonym,

exonym, unclassified].

TransitSystemIdTypeTransitSystemIdType is a xs:string type that matches a specific Transit System ID in the Discover

Cities Transit database.


TransitStopIdTypeTransitStopIdType is a xs:string type that matches a specific ID in the Discover Cities Transit

database.

TransitAccessIdTypeTransitAccessIdType is a xs:string type that matches a specific ID in the Discover Cities Transit

database.

xs:dateTimeThe lexical representation of xs:dateTime consists of finite-length sequences of characters of the

following form:

YYYY + "-" + MM + "-" + DD + "T" + hh + ":"+ mm + ":" + ss + ("." + s)? + (zzzzzz)?

Syntax Description

YYYY is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits,

leading zeros are prohibited, and '0000' is prohibited

MM is a two-digit numeral that represents the month

DD is a two-digit numeral that represents the day

hh is a two-digit numeral that represents the hour The value 24 is permitted if the minutes and seconds

represented are zero, and the dateTime value so represented is the first instant of the following day (the hour

property of a dateTime object in the value space cannot have a value greater than 23)

mm is a two-digit numeral that represents the minute

ss is a two-integer-digit numeral that represents the whole seconds

s represents the fractional seconds (optional)

zzzzzz represents the timezone

The timezone portion zzzzzz is represented as follows:

(("+" | "-") + hh + ":"+ mm) | "Z"


Syntax Description

"+"|"-" "+" indicates a non-negative duration,

"-" indicates a non-positive duration.

hh is a two-digit numeral (with leading zeros as required) that represents the hours

mm is a two-digit numeral that represents the minutes

"Z" "Z" represent the zero-length duration timezone, UTC "Z" is the canonical representation for UTC dateTime

values.

DateTime Example

2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as

well as Eastern Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than

2002-10-10T12:00:00Z.

xs:durationThe lexical representation for duration is the ISO 8601 extended format:

"-"? + "P" + (nY + "Y")? + (nM + "M" )? + (nD + "D" )? + ("T" (nH + "H")? + (nM + "M")? + (nS + "S")?)?

Syntax Description

"-" Optional minus sign to represent negative durations. If the sign is omitted a positive duration is indicated.

nY represents the number of years. Must be an unsigned integer.

nM represents the number of months. Must be an unsigned integer.

nD represents the number of days. Must be an unsigned integer.

nH represents the number of hours. Must be an unsigned integer.

nM represents the number of minutes. Must be an unsigned integer.

nS represents the number of seconds, which can include decimal digits represent fractions of seconds.

Duration Example

P1Y2M3DT10H30M indicates a duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes.

-P120D indicates a duration of minus 120 days.

xs:listXML Schema provides a list type allowing more than one item within a single XML element. Items are

separated by space.

The following example defines a list element named "Foo" which contains string elements.

<xs:simpleType name="MyListType"> <xs:list itemType="xs:string"/></xs:simpleType><xs:element name="Foo" type="MyListType">

A valid instantiation of the "Foo" element would be

<Foo>ABC DEF GHI</Foo>

In this example, the "Foo" element contains the three items "ABC", "DEF", and "GHI".

In representation formats other than XML, the space as separator sometimes becomes unhandy.

Therefore, a standard representation format for list types is defined for each representation format

below.


In query strings, items of list types are separated by one of the following characters:

"," (comma) is used at top level

<Foo[0]> + "," + <Foo[1]> + "," + <Foo[2]> + "," + …

";" (semicolon) is used at second level, or if comma is already used in the representation of the list

items

<Foo[0]> + ";" + <Foo[1]> + ";" + <Foo[2]> + ";" + …

"!" (exclamation point) is used at third level, or if comma and semicolon are already used in the

representation of the list items

<Foo[0]> + "!" + <Foo[1]> + "!" + <Foo[2]> + "!" + …

The following syntax is introduced as shortcut to represent list types:

<Foo[]>

Note: List types and element sequences are represented in the same manner (see alsoxs:sequence on page 102).

JSON Representation

List types are represented as arrays:

[<list[0]>, <list[1]>, <list[2]>, …]

xs:sequenceA schema can define elements which can appear more than once. The following example defines an

element named "Bar" which can be included n times.

<xs:element name="Bar" type="xs:string" maxOccurs="unbounded"/>

A valid instantiation of the "Bar" element would be

<Bar>ABC</Bar><Bar>DEF</Bar><Bar>GHI</Bar>

Element sequences are described in all API documentations with an "[]" as suffix like this:

Bar [] sequence of strings

In representation formats other than XML, listing the same element more than once is inconvenient,

so a standard representation format for sequences is defined for each representation format below.


In query strings, items of list types are separated by one of the following characters:

"," (comma) is used at top level

<Bar[0]> + "," + <Bar[1]> + "," + <Bar[2]> + "," + …

";" (semicolon) is used at second level, or if comma is already used in the representation of the list

items

<Bar[0]> + ";" + <Bar[1]> + ";" + <Bar[2]> + ";" + …

"!" (exclamation point) is used at third level, or if comma and semicolon are already used in the

representation of the list items

<Bar[0]> + "!" + <Bar[1]> + "!" + <Bar[2]> + "!" + …

When applying this rule to the above example, the result would be: ABC,DEF,GHI

The following syntax is introduced as shortcut to represent element sequences:

<Bar[]>

Note: list types and element sequences are represented in the same manner. See also xs:liston page 101)

JSON Representation

Element sequences will be represented as arrays:

[<list[0]>, <list[1]>, <list[2]>,…]

LinkIdTypeA network link can be identified using the LinkIdType as functional key.

It is used by different complex types (for example, RouteLinkType and MapLinkType).

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

• Must match the following regular expression: [-]\d+

Error Data TypesError details are transferred to the client using a generic error structure, which is returned instead of

the actual response structure.

Namespace http://www.navteq.com/lbsp/Errors/1

Schema location(Source) http://route.api.here.com/xsd/LBSP-Errors.xsd


XSD Version 1.0

Figure 24: ServiceErrorType

The error type defines the following attributes:

@type Errors are categorized into one of the following groups:

• ApplicationError

Errors that are thrown since the business logic has detected some error

• SystemError

Errors that are thrown due to technical reasons

• PermissionError

Errors that are thrown to reject incoming requests due to invalid credentials

or missing entitlements

@subtype Defined name of the concrete error, such as "InvalidInputData" or

"ExceededUsageLimit".

Details Clear text error message

RequestId Arbitrary value to trace back the request. This value is copied from the request

which caused the error.

AdditionalData Generic container to include structured details regarding the error. Each concrete

error sub type defines the semantics of the values in the container.

Errors are returned in the same format (XML, JSON, JSONP) as the expected response.

All defined errors are grouped into one of the three basic error types defined below:


ApplicationError Errors that are thrown since the business logic has detected some error

SystemError Errors that are thrown due to technical reasons

PermissionError Errors that are thrown to reject incoming requests due to invalid

credentials or missing entitlements

The error type name is mapped to the ServiceError.type attribute. Services may define their

own, more specific errors based on these three error types. The name of the more specific error type

is then mapped to the ServiceError.subtype attribute.

However, the basic error types may also be used for concrete errors if there is no sub type that

better fits the error situation. In that case, the ServiceError.subtype attribute is omitted.

The usage of the ServiceError.AdditionalData element is not defined for the basic error types. Error

sub types may define their own values.

InvalidCredentialsThis error is returned if the specified token was invalid or no contract could be found for this token.

The following field mapping applies:

Field Value

ServiceError.type “PermissionError”

ServiceError.subtype “InvalidCredentials”

ServiceError.AdditionalData Entry 1:

• Key: “token”

• Value: token specified in the request

InsufficientRightsThis error is returned if the user's contract exists for the given token but does not have the required

entitlements.


Field Value


ServiceError.subtype “InsufficientRights”



Field Value



Entry 2:

• Key: “missing_entitlement”

• Value: entitlement that is missing

ContractViolatedThis error is returned if the user's contract exists for the given app_id but is not yet active or has

already expired.


Field Value


ServiceError.subtype “ContractViolate”

ExceededUsageLimitThis error is returned if the contract associated with the app_code has reached the usage limit for a

certain entitlement.


Field Value


ServiceError.subtype “ExceededUsageLimit”




Entry 2:

• Key: “entitlement”

• Value: entitlement that has reached usage limit

Entry 3:

• Key: “usage_limit”


Field Value

• Value: Usage limit

InvalidInputDataThis error is returned if the specified request parameters contain invalid data, such as due to wrong

parameter syntax or invalid parameter combinations.


Field Value

ServiceError.type “ApplicationError”

ServiceError.subtype “InvalidInputData”

ServiceError.AdditionalData One entry for each parameter that caused the error:

• Key: name of the query parameter

• Value: value specified for the query parameter

WaypointNotFoundThis error indicates that one of the requested waypoints (start/end or via point) could not be found in

the routing network.


Field Value

ServiceError.type “ApplicationError""

ServiceError.subtype “WaypointNotFound”

ServiceError.AdditionalData One entry for each waypoint which could not be found:

• Key: waypoint[n]

• Value: as specified in the request (same representation)

NoRouteFoundThis error indicates that no route could be constructed based on the input parameter.



Field Value


ServiceError.subtype “NoRouteFound”

ServiceError.AdditionalData -

InvalidRouteIdThis error indicates that the route could not be reconstructed based on the given Route ID.


Field Value


ServiceError.subtype “InvalidRouteId”


• Key: “routeId”

• Value: Route ID that is invalid

LinkIdNotFoundThis error indicates that a link ID passed as input parameter could not be found in the underlying map

data.


Field Value


ServiceError.subtype “LinkIdNotFound”

ServiceError.AdditionalData One entry for each link which could not be found:

• Key: linkId[n]

• Value: link ID which could not be found


PositionOffRouteThis error is returned in case a position is too far away from the route. The threshold to consider a

position to be off route is 500m.


Field Value


ServiceError.subtype “PositionOffRoute”

ServiceError.AdditionalData One entry for each link which could not be found:

• Key: position

• Value: geo coordinate of position as [lat],[long](,[alt])

HTTP Status CodesRouting API supports the standard HTTP status codes

Error code Description

200 OK Indicates success, but may also be returned when an invalid resource name and/or an invalid

parameter combination has been used in the request.

400 Bad request Invalid parameter value in the request, for example zoom out of range.

401 Unauthorized Invalid authentication.

403 Forbidden Incorrect app_code or app_id in the request. See Acquiring Credentials on page 13 for

more information.

404 Not found Unsupported parameter in the request.

500 Internal error There is a server configuration issue.

503 Service Unavailable Indicates that the service is temporarily unavailable due to system overload or maintenance.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4

developer's guide routing api -...

Documents