Routing API. Developer's Guide. Version

Transcription

1 Routing API Developer's Guide Version

2 Routing API Developer's Guide 2 Contents Contents Legal Notices...4 Document Information... 5 Chapter 1: Overview... 6 What is the Routing API?... 7 Why use the Routing API?... 8 Customization Options... 8 Routing Feature Availability...8 Chapter 2: Quick Start...10 Requesting a Simple Route...11 Getting Route Information...11 Chapter 3: User Guide...12 Acquiring Credentials...13 Constructing a Request GET request...13 POST request...14 Additional Comments...16 Customer Integration Testing...18 Key Concepts...18 Private Transport Routing Schema Evolution...21 Service Support Examples...22 Calculate Route Examples...22 Chapter 4: API Reference...25

3 Routing API Developer's Guide 3 Contents Resources and Parameters...26 Calculate Route Get Link Info Request...30 Get Route...34 Calculate Isoline Calculate Reverse Flow...38 Common Parameter Types...40 Response Data Types...53 CalculateRouteResponseType...54 GetRouteResponseType GetLinkInfoResponseMetaInfoType...56 GetRouteResponseType CalculateIsolineResponseType...58 Routing Data Types...59 Base Data Types Error Data Types HTTP Status Codes...120

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

5 Routing API Developer's Guide 5 Document Information Document Information Product Name: Routing API Version: Version Document Name: Id: Status: Date: Routing API Developer's Guide f5badc FINAL 2013-Nov-13, 17:03 (GMT)

6 Routing API Developer's Guide 6 Overview Chapter 1 Overview Topics: What is the Routing API? Why use the Routing API? Routing Feature Availability 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.

7 Routing API Developer's Guide 7 Overview 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. Update a previously calculated route. Calculate a route isoline. 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 fleet truck attributes Legal restrictions for trucks (No trucks allowed, Turn restrictions for trucks) Physical restrictions for Trucks (Weight, Height, Width and Length) Hazmat restrictions for trucks (All trucks with hazardous goods forbidden, All trucks with explosive and inflammable, goods forbidden, All trucks with natural goods)

8 Routing API Developer's Guide 8 Overview Why use the Routing API? HERE Routing API can be used in a variety of consumer and enterprise applications including Fleet Tracking applications Navigation and traffic web portals Navigation and routing on mobile devices Logistics (tour optimization) Freight and vehicle exchange portals Customization Options You 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, truck, or pedestrian selecting a route type such as fastest, shortest, or scenic deciding whether to consider current traffic and traffic patterns, seasonal closures, speed categories 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 road attributes in the route calculation, for example, toll road, motorway, boat and rail ferries Routing Feature Availability There are two versions of HERE Routing API, both provide core routing functionality. 6.2 API is the legacy API and is referred to as LBSP (Location Based Services Platform) 7.2 API is the newer API and is referred to as NLP (Nokia Location Platform) Always use Routing API 7.2 unless you require functionality available only in 6.2 from this table: Table 1: Routing Feature Availability Matrix Feature Version 6.2 Version 7.2 Public Transport Routing - + Car Routing + + Pedestrian Routing + +

9 Routing API Developer's Guide 9 Overview Feature Version 6.2 Version 7.2 Truck Routing + - GetRoute - Update a route along a current route. GetLinkInfo - Retrieve specific link information, such as nearest links to a waypoint. Calculate Isoline- Retrieve a polyline that connects the end points of multiple routes. Calculate Reverse Flow- Retrieve a set of links from which a given destination point is reachable in a specified travel time or travel distance Matrix Routing + 1:N Pedestrian only. Where + indicates that a given feature is available.

10 Routing API Developer's Guide 10 Quick Start Chapter 2 Quick Start Topics: Requesting a Simple Route Getting Route Information The articles in this section provide information to help you start using the HERE Routing API.

11 Routing API Developer's Guide 11 Quick Start Requesting a Simple Route To 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 into account. 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. &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo!52.5,13.4 &waypoint1=geo!52.5,13.45 &mode=fastest;car;traffic:disabled Getting Route Information Use a getroute request to retrieve more information about a previously calculated route by specifying the routeid from a previously calculated route response, in this case the route from the Requesting a Simple Route on page 11 example and making sure to use the same mode parameter (mode=fastest;car;traffic:disabled). &app_code=ajknxv84fjrb0kihaws0tg &routeid=rem01w8aaaaaaaaaaebkqm3mzmzmzcpaaaaaop8_skaaaabaxswqqaaaaaaaapb_ AAAAAAAA8H9Lxc38AAAAAAAAKQGZmZmZmZmrAAEAAABV_ygBAQAAgIObqwABAAAAAADA_wEAAAAAAMD_ccC_D &mode=fastest;car;traffic:disabled

12 Routing API Developer's Guide 12 User Guide Chapter 3 User Guide Topics: 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.

13 Routing API Developer's Guide 13 User Guide Acquiring Credentials All users of HERE APIs must obtain authentication and authorization credentials and provide them as values for the parameters app_id and app_code. The credentials are assigned per application. To obtain the credentials for an application, please visit for more details. Constructing a Request A request to the Routing API includes the basic elements shown in the following table and, in addition, it may contain resource-specific parameters. Table 2: Basic request elements Element Value/Example Base URL Path Resource Format /routing/6.2/ calculateroute getroute getlinkinfo calculateisoline Supported formats: json xml Production environment CIT environment: see Customer Integration Testing on page 18 All support GET and calculateroute also POST, specify request details via query parameters Application Code &app_code=ajknxv84fjrb0kihaws0tg Substitute your own unique app_code Application Id &app_id=demoappid gal Substitute your own unique app_id GET request Here is an example of a routing request, which uses the HTTP GET method:

14 Routing API Developer's Guide 14 User Guide?app_id=DemoAppId GAL &app_code=ajknxv84fjrb0kihaws0tg &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: &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo!52.5,13.4 &waypoint1=geo!52.5,13.45 &mode=fastest;car;traffic:disabled POST request The Routing API also supports HTTP-POST to perform a route calculation. A tool called wget is commonly used but there are also various browser add-ons like Poster tht allow you to do POSt request (by default most browsers don't support POST in their user interfaces). Two content types are supported for POST: TXT You can specify waypoint data in text format. TXT mimics the format you would put onto a URL, with parameters defined by '&' and values preceded by '='. XML You can specify waypoint data in XML format. An issue with REST requests is that there is a length limitation for URLs. If a route has more than 100 waypoints, you can run into this limitation. Using POST to specify the waypoint data overcomes this problem. The default limit for the number of waypoints is 200 when you use POST mode. (If you increase this limit, your performance will be negatively affected. However, you can increase this limit if you need to.) Example wget Command Using wget with input parameters in XML file: wget --verbose --server-response --header="accept-encoding: gzip,deflate" --header="content-type: application/xml;charset=utf-8" -O response.xml --postfile=request.xml

15 Routing API Developer's Guide 15 User Guide Using wget with input parameters in TXT file: wget --verbose --server-response --header="accept-encoding: gzip,deflate" --header="content-type: application/x-www-form-urlencoded" -O response.xml --postfile=request.txt Example of POST XML Input File XML file format corresponds to JAXB objects from XSD file. Much more easily is to use TXT file instead of XML file. <ns2:calculateroute xmlns:ns2=" <Request> <CalculateRouteRequestMetaInfo> <RequestID> </RequestID> <VerboseMode>1</VerboseMode> </CalculateRouteRequestMetaInfo> <RepresentationOptions> <Language>de-DE</Language> <RepresentationMode>overview</RepresentationMode> <RouteAttributes>waypoints summary legs</routeattributes> <LegAttributes>maneuvers waypoint length traveltime</legattributes> <ManeuverAttributes>position length traveltime</maneuverattributes> <LinkAttributes>shape speedlimit dynamicspeedinfo address</linkattributes> </RepresentationOptions> <!-- &waypoint0=geo! , > <Waypoint xsi:type="ns4:geowaypointparametertype" xmlns:ns4=" xmlns:xsi=" <Position> <Latitude> </Latitude> <Longitude> </Longitude> </Position> </Waypoint> <!-- &waypoint1=geo! , > <Waypoint xsi:type="ns4:geowaypointparametertype" xmlns:ns4=" xmlns:xsi=" <Position> <Latitude> </Latitude> <Longitude> </Longitude> </Position> </Waypoint>... <!-- &waypoint10=geo! , > <Waypoint xsi:type="ns4:geowaypointparametertype" xmlns:ns4=" xmlns:xsi=" <Position> <Latitude> </Latitude> <Longitude> </Longitude> </Position> </Waypoint> <Departure> T12:00:00-05:00</Departure> <Mode> <Type>fastestNow</Type> <TransportModes>car</TransportModes> <TrafficMode>disabled</TrafficMode> </Mode> </Request>

16 Routing API Developer's Guide 16 User Guide </ns2:calculateroute> Example of POST Text Input File TXT file format is same as url string for parameters from normal request. app_id=demoappid gal &app_code=ajknxv84fjrb0kihaws0tg &verbosemode=0 &waypoint0=link! %2c !%2b &waypoint1=geo! , &waypoint2=link! %2c !%2b &departure= t12%3a54%3a17%2b01%3a00 &language=en_us &routeattributes=wp,sm,sc,sh,bb,lg,no &maneuverattributes=all &instructionformat=text &mode=fastest;car;traffic:enabled; &jsonattributes=1 &jsoncallback=responsecallback Additional Comments Some parameters need to included into the POST URI, rather than into the post-content: 1. jsoncallback 2. jsonattributes 3. app_id 4. app_code These parameters are handled on a framework level. Support for POST was introduced on routing application level. Below an example of request with these parameters: wget --verbose --server-response --header="accept-encoding: gzip,deflate" --header="content-type: application/xml;charset=utf-8" -O response.xml app_id=demoappid gal&app_code=ajknxv84fjrb0kihaws0tg&jsonattributes=1 &jsoncallback=responsecallback --post-file=request.xml

17 Routing API Developer's Guide 17 User Guide Firefox Add-on Poster Poster is a Mozilla Firefox add-on that allows you to easily create and submit a HTTP-POST request to the Routing API. The tool provides a convenient user interface. The image below shows Poster using a text file as input as shown in Example of POST Text Input File on page 16 Figure 1: Poster

18 Routing API Developer's Guide 18 User Guide Customer Integration Testing HERE is committed to maintain the best possible production service for all customers. Given that the production environment is live and common to all API users, we request that you use the alternative Customer Integration Testing (CIT) environment when evaluating our products, running tests, making changes in your code and altering the way you access our APIs. The CIT environment also allows you to test your software against a newer version of the service before HERE brings that version into production. CIT offers a fully functional environment for customers to use for development and testing, but it does not support high loads or performance testing in general. Note that the same application id can be used in both environments, but CIT may require a dedicated application code. If this is the case, please contact us as described under Service Support on page 22. The CIT environment is not intended for general production use. Key Concepts This section provides key concepts that underlie the HERE Routing API. Private Transport Routing This topic provides generic usage instructions and guidelines for Private Transport Routing functionality. Private Transport Routing Mode Routing 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 a vehicle or pedestrian (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]

19 Routing API Developer's Guide 19 User Guide 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 Types The 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 is the most commonly used routing type. fastestnow: routing favors the least amount of travel time, always considers traffic directdrive: routing favors the least amount of travel time, disregards traffic shortest: routing favors the least amount of travel distance, disregards traffic scenic: routing favors scenery features, can consider traffic if enabled. Transport Mode The 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. Each transport mode applies different considerations, as described: car: routing for cars, adheres to link rules and restrictions (for example, speed limits, direction of travel, etc.), can consider traffic if enabled pedestrian: routing for pedestrians, considers pedestrian maneuverability of links, disregards traffic truck: routing for fleet trucks, considers link weight restrictions, can consider traffic if enabled Traffic-Enabled Routing Enabling 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.

20 Routing API Developer's Guide 20 User Guide Note: This feauture may be subject to premium pricing. For details please contact your sales representative. Routing Mode Parameter Combinations This section provides valid parameter combinations for routing mode, used in private transport routing. Transport Type car Mode Combinations Traffic-enabled: mode=fastestnow;car mode=fastest;car;traffic:enabled mode=scenic;car;traffic:enabled Traffic not enabled: mode=fastest;car;traffic:disabled mode=directdrive;car mode=shortest;car mode=scenic;car;traffic:disabled pedestrian mode=fastest;pedestrian mode=scenic;pedestrian mode=shortest;pedestrian truck Traffic-enabled: mode=fastestnow;truck mode=fastest;truck;traffic:enabled mode=scenic;truck;traffic:enabled Traffic not enabled: mode=fastest;truck;traffic:disabled mode=directdrive;truck mode=shortest;truck mode=scenic;truck;traffic:disabled Attribute Switches Attribute 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.

21 Routing API Developer's Guide 21 User Guide 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 42. Schema Evolution The 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.

22 Routing API Developer's Guide 22 User Guide Service Support If you need assistance with this or other HERE products, please contact your HERE representative or Technical Customer Support via at Examples This section provides examples of Routing API requests. Calculate Route Examples This section provides examples of calculate route requests. Private Transport This topic describes example scenarios for private transport routing. Requesting a Route Avoiding an Area To 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 ( , ) at Unter den Linden in Berlin to the Staatsoper in Berlin ( , ) avoiding passing the Deutsche Guggenheim ( , ) by specifying a rectangle that contains it (top left , and bottom right , ), and also the fastest route for a car without taking traffic conditions into account. &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo! , &waypoint1=geo! ,

23 Routing API Developer's Guide 23 User Guide &mode=fastest;car;traffic:disabled &avoidareas= , ; , Requesting a Route Using a Different Routing Modes You can specify different route calculation modes in a request, to compare the calculated route outcomes. We recommend only using this functionality when the route is small, as it may cause increased response times from the service. Example The following request is an example for two route calculations, each using a different routing mode. One route will be calculated using the fastest mode for a car (considering traffic information, avoiding motorways), the other is calculated using the pedestrian mode. &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo! , &waypoint1=geo! , &mode0=fastest;car;traffic:enabled;motorway:-1 &mode1=fastest;pedestrian The CalculateRoute service returns two routes. Figure 2: Route using the Fastest mode for car Figure 3: Route using the Pedestrian mode Requesting a Route via a Third Coordinate To 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 ( , )

24 Routing API Developer's Guide 24 User Guide to the Staatsoper in Berlin ( , ) via the Deutsche Guggenheim ( , ). &app_code=ajknxv84fjrb0kihaws0tg &mode=fastest;car;traffic:disabled &waypoint0=geo! , &waypoint1=geo!stopover! , &waypoint2=geo! ,

25 Routing API Developer's Guide 25 Chapter 4 API Reference Topics: 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.

26 Routing API Developer's Guide 26 Resources and Parameters This section provide a comprehensive reference to the query parameters supported by the Routing API. Calculate Route Get Route Get Link Info Calculate Isoline Where {format} is either json or xml. All results returned in xml format have the following properties: Namespace: Schema location:

27 Routing API Developer's Guide XSD Version 4.2 Calculate Route Use 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/6.2/calculateroute.{format}?<parameter>=<value>... Parameter app_id A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_id assigned to you, please see Acquiring Credentials on page 13. app_code A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_idassigned to 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. When used in a getroute request, the mode of transport must be the same as in the original request. See also RoutingModeType on page 50 Type;TransportModes;TrafficMode;Feature &mode=fastest;car;traffic:disabled;motorway:2 requestid avoidareas 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. Areas which the route must not cross. Array of BoundingBox. avoidareas= , ; , ;

28 Routing API Developer's Guide 28 Parameter avoidlinks Links which the route must not cross. List of LinkIdType. LinkIdType is a xs:string with the following regular expression restrictions: [-]\d+ avoidlinks= departure Time when travel is expected to start. Traffic patterns and incidents are taken into account when calculating the route. You can use now to specify the current time. Specify either DepartureTime or ArrivalTime, not both.xs:datetime departure= t17: 00:00+02:00Z alternatives metricsystem viewbounds resolution instructionformat language jsonattributes Number of alternative routes calculated. xs:integer The default is the metric system associated with the language settings. xs:string. Enum [imperial metric] If the view bounds are given in the request only shapes and links which fit into these bounds will 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 of BoundingBox. viewbounds= , ; , Integer resolution of the view in meters per pixel, and optional snap resolution in meters per pixel. Snap resolution lets the routing service to pick links with waypoints that are visible in the client display resolution. This information allows the route shape in the response to reflect the client's resolution. resolution=viewresolution:snapresolution resolution=300:0,01 Defines the representation format of the maneuver's instruction text. InstructionFormatType on page 47 instructionformat=enum [ txt html native] A single language from the following list. [en-uk en-us fr-fr de-de es-es it-it] Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation on page 53. jsonattributes=2 jsoncallback representation routeattributes Specifies the name of a user-defined function used to wrap the JSON response. Define which elements are included in the response as part of the data representation of the route. See also RouteRepresentationModeType on page 42. Enum[overview display dragndrop navigation linkpaging turnbyturn] Define which atrributes are included in the response as part of the data representation of the route. Defaults to waypoints, summary, legs, lines. See also RouteAttributeType on page 43. Enum[waypoints summary summarybycountry shape boundingbox legs notes ]

29 Routing API Developer's Guide 29 Parameter legattributes maneuverattributes linkattributes gen Define which attributes are included in the response as part of the data representation of the route legs. Defaults to maneuvers, waypoint, length, traveltime. See also RouteLegAttributeType on page 43. Enum [waypoint maneuvers links length traveltime Define which attributes are included in the response as part of the data representation of the route maneuvers. Defaults to position, length, traveltime. See also ManeuverAttributeType on page 44 Enum[ position shape traveltime length time link roadname nextroadname roadnumber nextroadnumber signpost notes action direction freewayexit freewayjunction basetime traffictime ] Define which attributes are included in the response as part of the data representation of the route links. Defaults to shape, speedlimit, dynamicspeedinfo, address. See also RouteLinkAttributeType on page 45. Enum[shape, length speedlimit dynamicspeedinfo incidents truckrestrictions flags address roadnumber roadname freewayexit freewayjunction timezone nextlink TMCCodes jamfactor jamfactortrend confidence remaintime remaindistance maneuver functionalclass speedcategory ] xs:int Generation parameter used to influence which information to return in enumeration values. gen=0 default behavior gen=1 Returns additional link flag type builtuparea and TruckRestrictions allhazardousgoods. tunnelcategory Specify the tunnel category to restrict the truck route to. Enum [B C D E] tunnelcategory=c Example Request &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo!52.5,13.4 &waypoint1=geo!52.5,13.45 &mode=fastest;car;traffic:disabled &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo!123.45,-34.45;12.7;300 &waypoint1=link!-3456 &waypoint2=geo!123.45,-34.45;12.7;300 &waypoint3=link!-12345

30 Routing API Developer's Guide 30 &avoidareas= , ; , &mode=fastest;car &departure= t17:00:00z &locale=en-us &linkattributes=shape;dynamicspeedinfo &requestid=<your_tracking_id> Example Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <rtcr:calculateroute xmlns:rtcr=" CalculateRoute/4"> <Response> <MetaInfo> <Timestamp> T14:49:50.645Z</Timestamp> <MapVersion> </MapVersion> <ModuleVersion> _CD-336_1</ModuleVersion> <InterfaceVersion>2.4.31</InterfaceVersion> </MetaInfo> <Route> <Waypoint> <LinkId> </LinkId> <MappedPosition> <Latitude> </Latitude> <Longitude> </Longitude> </MappedPosition> <OriginalPosition> <Latitude>52.5</Latitude> <Longitude>13.4</Longitude> </OriginalPosition> <Type>stopOver</Type> <Spot> </Spot> <SideOfStreet>left</SideOfStreet> <MappedRoadName>Neuenburger Straße</MappedRoadName> <Label>Neuenburger Straße</Label> Get Link Info Request Use the getlinkinfo resource to return detailed information about a route. The required parameters for this resource are app_id and app_code and either linkids or a routeid specifying a particular route.../routing/6.2/getlinkinfo.{format}?<parameter>=<value>... Parameter app_id A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application.

31 Routing API Developer's Guide 31 Parameter app_code mode requestid metricsystem viewbounds resolution instructionformat language jsonattributes You must include an app_id and app_code with every request. To get an app_id assigned to you, please see Acquiring Credentials on page 13. A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_idassigned to you, please see Acquiring Credentials on page 13. The routing mode determines how the route is calculated. When used in a getroute request, the mode of transport must be the same as in the original request. See also RoutingModeType on page 50 Type;TransportModes;TrafficMode;Feature &mode=fastest;car;traffic:disabled;motorway:2 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. The default is the metric system associated with the language settings. xs:string. Enum [imperial metric] If the view bounds are given in the request only shapes and links which fit into these bounds will 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 of BoundingBox. viewbounds= , ; , Integer resolution of the view in meters per pixel, and optional snap resolution in meters per pixel. Snap resolution lets the routing service to pick links with waypoints that are visible in the client display resolution. This information allows the route shape in the response to reflect the client's resolution. resolution=viewresolution:snapresolution resolution=300:0,01 Defines the representation format of the maneuver's instruction text. InstructionFormatType on page 47 instructionformat=enum [ txt html native] A single language from the following list. [en-uk en-us fr-fr de-de es-es it-it] Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation on page 53. jsonattributes=2 jsoncallback representation Specifies the name of a user-defined function used to wrap the JSON response. Define which elements are included in the response as part of the data representation of the route. See also RouteRepresentationModeType on page 42. Enum[overview display dragndrop navigation linkpaging turnbyturn]

32 Routing API Developer's Guide 32 Parameter routeattributes maneuverattributes linkattributes maxfunctionalclass Define which atrributes are included in the response as part of the data representation of the route. Defaults to waypoints, summary, legs, lines. See also RouteAttributeType on page 43. Enum[waypoints summary summarybycountry shape boundingbox legs notes ] Define which attributes are included in the response as part of the data representation of the route maneuvers. Defaults to position, length, traveltime. See also ManeuverAttributeType on page 44 Enum[ position shape traveltime length time link roadname nextroadname roadnumber nextroadnumber signpost notes action direction freewayexit freewayjunction basetime traffictime ] Define which attributes are included in the response as part of the data representation of the route links. Defaults to shape, speedlimit, dynamicspeedinfo, address. See also RouteLinkAttributeType on page 45. Enum[shape, length speedlimit dynamicspeedinfo incidents truckrestrictions flags address roadnumber roadname freewayexit freewayjunction timezone nextlink TMCCodes jamfactor jamfactortrend confidence remaintime remaindistance maneuver functionalclass speedcategory ] Restrict the list of links to those of a particular functional class or less. See also FunctionalClassType on page 101. tmccodes List of TMC codes of the links to be returned. See also TMCCodeType on page 108 quadkey All links inside the bounding box are returned. Array of BoundingBox. quadkey= , ; , linkids routeid waypoint Return detailed information for this list of link IDs. Return detailed information for the route corresponding to this RouteId. 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 Example Request &app_code=ajknxv84fjrb0kihaws0tg &waypoint= , &linkattributes=all

33 Routing API Developer's Guide 33 Example Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <rtgl:getlinkinfo xmlns:rtgl=" GetLinkInfo/4"> <Response> <MetaInfo> <MapVersion>2012Q4</MapVersion> <ModuleVersion>0.2</ModuleVersion> <InterfaceVersion>4.2</InterfaceVersion> <Timestamp> T14:30:51.263Z</Timestamp> </MetaInfo> <Link xmlns:xsi=" xmlns:rtc=" xsi:type="rtc:privatetransportlinktype"> <LinkId> </LinkId> <Shape> , , , , , </Shape> <Length>281.0</Length> <SpeedLimit>999.0</SpeedLimit> <DynamicSpeedInfo> <TrafficSpeed>24.75</TrafficSpeed> <TrafficTime>11.4</TrafficTime> <BaseSpeed>33.33</BaseSpeed> <BaseTime>8.4</BaseTime> <JamFactor>2.41</JamFactor> <JamFactorTrend>1.0</JamFactorTrend> <Confidence>0.87</Confidence> </DynamicSpeedInfo> <Flags>motorway</Flags> <TMCCodes>D01P12165</TMCCodes> <FunctionalClass>1</FunctionalClass> <Address> <Label>A66</Label> <Country>DE</Country> <State>Hessen</State> <County>Main-Taunus-Kreis</County> <City>Hochheim am Main</City> <Street>Rhein-Main-Schnellweg</Street> </Address> <RoadNumber>A66</RoadNumber> <Timezone>+0200</Timezone> <TruckRestrictions> <Height>4.0</Height> </TruckRestrictions> <RoadName>Rhein-Main-Schnellweg</RoadName> <SpeedCategory>SC1</SpeedCategory> </Link> </Response> </rtgl:getlinkinfo>

34 Routing API Developer's Guide 34 Get Route Use the getroute resource to request a previously calculated route by providing the RouteId.../routing/6.2/getroute.{format}?routeid=<ROUTEID>&<parameter>=<value>... Parameter requestid routeid pos 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. Return detailed information for the route corresponding to this RouteId. Current position. pos=geo!52.5,13.4 mode departure The routing mode determines how the route is calculated. When used in a getroute request, the mode of transport must be the same as in the original request. See also RoutingModeType on page 50 Type;TransportModes;TrafficMode;Feature &mode=fastest;car;traffic:disabled;motorway:2 Time when travel is expected to start. Traffic patterns and incidents are taken into account when calculating the route. You can use now to specify the current time. Specify either DepartureTime or ArrivalTime, not both.xs:datetime departure= t17: 00:00+02:00Z metricsystem viewbounds resolution instructionformat The default is the metric system associated with the language settings. xs:string. Enum [imperial metric] If the view bounds are given in the request only shapes and links which fit into these bounds will 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 of BoundingBox. viewbounds= , ; , Integer resolution of the view in meters per pixel, and optional snap resolution in meters per pixel. Snap resolution lets the routing service to pick links with waypoints that are visible in the client display resolution. This information allows the route shape in the response to reflect the client's resolution. resolution=viewresolution:snapresolution resolution=300:0,01 Defines the representation format of the maneuver's instruction text. InstructionFormatType on page 47 instructionformat=enum [ txt html native]

35 Routing API Developer's Guide 35 Parameter language jsonattributes A single language from the following list. [en-uk en-us fr-fr de-de es-es it-it] Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation on page 53. jsonattributes=2 jsoncallback representation routeattributes maneuverattributes linkattributes legattributes hastrailer shippedhazardousgoods permittedgrossweight limitedweight weightperaxle trailerweight Specifies the name of a user-defined function used to wrap the JSON response. Define which elements are included in the response as part of the data representation of the route. See also RouteRepresentationModeType on page 42. Enum[overview display dragndrop navigation linkpaging turnbyturn] Define which atrributes are included in the response as part of the data representation of the route. Defaults to waypoints, summary, legs, lines. See also RouteAttributeType on page 43. Enum[waypoints summary summarybycountry shape boundingbox legs notes ] Define which attributes are included in the response as part of the data representation of the route maneuvers. Defaults to position, length, traveltime. See also ManeuverAttributeType on page 44 Enum[ position shape traveltime length time link roadname nextroadname roadnumber nextroadnumber signpost notes action direction freewayexit freewayjunction basetime traffictime ] Define which attributes are included in the response as part of the data representation of the route links. Defaults to shape, speedlimit, dynamicspeedinfo, address. See also RouteLinkAttributeType on page 45. Enum[shape, length speedlimit dynamicspeedinfo incidents truckrestrictions flags address roadnumber roadname freewayexit freewayjunction timezone nextlink TMCCodes jamfactor jamfactortrend confidence remaintime remaindistance maneuver functionalclass speedcategory ] Define which attributes are included in the response as part of the data representation of the route legs. Defaults to maneuvers, waypoint, length, traveltime. See also RouteLegAttributeType on page 43. Enum [waypoint maneuvers links length traveltime Boolean. Truck routing only, specifies that the vehicle has a trailer. Truck routing only, list of harzardous goods in the vehicle. Truck routing only, permitted vehicle gross weight. Truck routing only, limited vehicle weight. Truck routing only, vehicle weight per axle. Truck routing only, weight of the vehicle trailer. Only valid if hastrailer=1

36 Routing API Developer's Guide 36 Parameter height width length Truck routing only, vehicle height in meters. Truck routing only, vehicle width in meters. Truck routing only, vehicle length in meters. Example Request &app_code=ajknxv84fjrb0kihaws0tg &routeid=zak128jss90jn1729 &avoidareas= , , , &mode=fastest;car &maneuverattributes=position,link &linkattributes=shape,dynamicspeedinfo &requestid=<your_tracking_id> Calculate Isoline Use the calculateisoline resource to request a polyline that connect the end points of all routes leaving from one defined center with either a specified length or a specified travel time.../routing/6.2/calculateisoline.{format}?<parameter>=<value>... Parameter app_id A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_id assigned to you, please see Acquiring Credentials on page 13. app_code A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_idassigned to you, please see Acquiring Credentials on page 13. requestid start 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. Center of the isoline request. Waypoint type. start=geo!52.5,13.4 distance There is no limitation for distance of isoline, but if you specify more than 500 km, the quality and performance of the isoline will decrease. Distance type. Specify either distance or time, not both. distance=1000,2000,3000

37 Routing API Developer's Guide 37 Parameter time There is no limitation for time of isoline, but if you specify more than 5 hours, the quality and performance of the isoline will decrease. Duration type. Specify either distance or time, not both. time=pt0h05m avoidareas Areas which the route must not cross. Array of BoundingBox. avoidareas= , ; , ; avoidlinks Links which the route must not cross. List of LinkIdType. LinkIdType is a xs:string with the following regular expression restrictions: [-]\d+ avoidlinks= mode departure The routing mode determines how the route is calculated. When used in a getroute request, the mode of transport must be the same as in the original request. See also RoutingModeType on page 50 Type;TransportModes;TrafficMode;Feature &mode=fastest;car;traffic:disabled;motorway:2 Time when travel is expected to start. Traffic patterns and incidents are taken into account when calculating the route. You can use now to specify the current time. Specify either DepartureTime or ArrivalTime, not both.xs:datetime departure= t17: 00:00+02:00Z jsonattributes Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation on page 53. jsonattributes=2 jsoncallback hastrailer shippedhazardousgoods permittedgrossweight limitedweight weightperaxle trailerweight height width Specifies the name of a user-defined function used to wrap the JSON response. Boolean. Truck routing only, specifies that the vehicle has a trailer. Truck routing only, list of harzardous goods in the vehicle. Truck routing only, permitted vehicle gross weight. Truck routing only, limited vehicle weight. Truck routing only, vehicle weight per axle. Truck routing only, weight of the vehicle trailer. Only valid if hastrailer=1 Truck routing only, vehicle height in meters. Truck routing only, vehicle width in meters.

38 Routing API Developer's Guide 38 Parameter length Truck routing only, vehicle length in meters. Example request A polyline built up of destinations reachable by a two and a half hour drive. &app_code=ajknxv84fjrb0kihaws0tg &start=geo!123.45,-34.45;12.7;300 &time=pt2h30m &mode=fastest;car &departure= t17:00:00z &requestid=<your_tracking_id> Calculate Reverse Flow Use the reverseflow resource to find a set of places from which a given destination point is reachable in a set time or from a set distance.../routing/6.2/reverseflow.{format}?<parameter>=<value>... Parameter app_id app_code requestid destination A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_id assigned to you, please see Acquiring Credentials on page 13. A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. To get an app_idassigned to you, please see Acquiring Credentials on page 13. 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. Destination of the reverse flow calculation. Waypoint type. destination=geo!52.5,13.4 distance Total travel distance, must be less than 10 km. Distance type. Specify either distance or time, not both. distance=1000,2000,3000

39 Routing API Developer's Guide 39 Parameter time Total travel time, must be less than 10 minutes. Duration type. Specify either distance or time, not both. time=pt0h05m avoidareas Areas which the route must not cross. Array of BoundingBox. avoidareas= , ; , ; avoidlinks Links which the route must not cross. List of LinkIdType. LinkIdType is a xs:string with the following regular expression restrictions: [-]\d+ avoidlinks= mode departure The routing mode determines how the route is calculated. When used in a getroute request, the mode of transport must be the same as in the original request. See also RoutingModeType on page 50 Type;TransportModes;TrafficMode;Feature &mode=fastest;car;traffic:disabled;motorway:2 Time when travel is expected to start. Traffic patterns and incidents are taken into account when calculating the route. You can use now to specify the current time. Specify either DepartureTime or ArrivalTime, not both.xs:datetime departure= t17: 00:00+02:00Z jsonattributes Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation on page 53. jsonattributes=2 jsoncallback hastrailer shippedhazardousgoods permittedgrossweight limitedweight weightperaxle trailerweight height width length Specifies the name of a user-defined function used to wrap the JSON response. Boolean. Truck routing only, specifies that the vehicle has a trailer. Truck routing only, list of harzardous goods in the vehicle. Truck routing only, permitted vehicle gross weight. Truck routing only, limited vehicle weight. Truck routing only, vehicle weight per axle. Truck routing only, weight of the vehicle trailer. Only valid if hastrailer=1 Truck routing only, vehicle height in meters. Truck routing only, vehicle width in meters. Truck routing only, vehicle length in meters.

40 Routing API Developer's Guide 40 Example request &app_code=ajknxv84fjrb0kihaws0tg destination=geo! , &distance=200 &mode=shortest;car &linkattributes=all &requestid=<your_tracking_id> Common Parameter Types WaypointParameterType Specify 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 geo geo! Indicates that the parameter contains a geographical position. [Type] Enum[stopOver! passthrough!] 180 degree turns are allowed for stopover but not for passthrough. Waypoints defined through a drag-ndrop action should be marked as passthrough. PassThrough waypoints will not appear in the list of maneuvers. Position [TransitRadius] Latitude, Longitude, [Altitude]; , ,25; TransitRadius 200 Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. Matching Links are selected within the specified TransitRadius, in meters. For example to drive past a city without

41 Routing API Developer's Guide 41 Parameter component Structure necessarily going into the city center you can specify the coordinates of the center and a TransitRadius of 5000m. 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 street street! Indicates that parameters contains a street position. [Type] Enum[stopOver! passthrough!] 180 degree turns are allowed for stopover but not for passthrough. Waypoints defined through a drag-ndrop action should be marked as passthrough. PassThrough waypoints will not appear in the list of maneuvers. [DisplayPosition] StreetPosition Latitude, Longitude, [Altitude]; ,56.778,567; Latitude, Longitude, [Altitude], [StreetName] Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. WGS-84 degrees between -90 and 90. Altitude in meters. There can be multiple street 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-

42 Routing API Developer's Guide 42 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 URL component Structure link street! Indicates that request contains a link position. [Type] [DisplayPosition] LinkPosition Enum[stopOver! passthrough!] Latitude, Longitude, [Altitude]; ,56.778,567; LinkId, [Spot], SideOfStreet ,0.1342,right 180 degree turns are allowed for stopover but not for passthrough. Waypoints defined through a drag-n-drop action should be marked as passthrough. PassThrough waypoints will not appear in the list of maneuvers. Latitude WGS-84 degrees between -90 and 90. Longitude WGS-84 degrees between -180 and 180. Altitude in meters. Id of the Link position, Relative position of the location along the link between 0 and 1, left or right side of the street. There can be multiple street positions in one parameter. RouteRepresentationOptionsType In 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: RouteRepresentationModeType Enumeration overview Overview mode only returns the Route and the RouteSummary object

43 Routing API Developer's Guide 43 Enumeration display dragndrop navigation linkpaging turnbyturn Display mode that allows to show the route with all maneuvers. Links won't be included in the response 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 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. Paging mode that will be used when incrementally loading links while navigating along the route. The response will be limited to link information. 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 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. summarybycountry sc Indicates whether a country-based 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. RouteLegAttributeType Enumeration Short value waypoint wp Indicates whether the waypoint shall be included in the route leg.

44 Routing API Developer's Guide 44 Enumeration Short value 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 ManeuverAttributeType Enumeration Short value 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.

45 Routing API Developer's Guide 45 Enumeration Short value 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 included in the maneuvers. roadtemplate rt Indicates whether the template for route display should be included in the maneuvers. signpost sp Indicates whether the sign post information should be included in the maneuvers. 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. indices ix Indicates whether shape index information (FirstPoint, LastPoint) should be included in the maneuvers instead of copying shape points to the maneuver. waittime wt Indicates whether wait time information should be included in public transport maneuvers. RouteLinkAttributeType Enumeration Short value Shape sh Indicates whether the link should include its geometry

46 Routing API Developer's Guide 46 Enumeration Short value 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.

47 Routing API Developer's Guide 47 Enumeration Short value 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. indices ix Indicates whether shape index information (FirstPoint, LastPoint) should be included in links instead of copying shape points. RouteResponseAttributeType Enumeration maneuvers links Indicates whether maneuvers should be provided in the response. Indicates whether route links should be provided in the response. InstructionFormatType Representation formats for instruction texts. text returns the instruction as a plain text string

48 Routing API Developer's Guide 48 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 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) transit Transit type train line transit line S5 company Transit line company RMV arrivalsummary distancedescription company exit Class to markup summaries in last instructions per leg. The instruction text for this class may include other spans for different classes Provides information on travel distances in instruction texts. part of transit line name roundabout exit number The trip takes 4 miles and 10 mins. Go for 43 miles next-street name of next street heading towards...

49 Routing API Developer's Guide 49 Examples of HTML with CSS Classes "Take exit as. Frankfurt-Friedberger Landstr. tothe left onto a661 towardsoberursel, Friedberg, Kassel, Bad Homburg, 661. Go for 5.5 miles." Turn right onto 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 knobelsdorffstraße. the trip takes 4 miles and 10 mins.<instruction> The trip takes 4 miles and 10 mins. BoundingBoxType A 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 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= , ; , 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.

50 Routing API Developer's Guide 50 Parameter component Latitude, Longitude, [Altitude] bbox= , ; , RoutingModeType The 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 50. ENUM [fastest shortest scenic fastestnow directdrive]; [TransportModes] Specify which mode of transport to calculate the route for. See alsotransportmodetype on page 51. ENUM [car pedestrian truck bicycle]; [TrafficMode] Specify whether to take traffic into account. See also TrafficModeType on page 51. traffic: Enum [enabled disabled default] [Feature] Route feature weightings to be applied when calculating the route. As many as required. When used in a calculateisoline or reverseflow request, only strict excludes (ie motorway:-3) are relevant. See also RouteFeatureWeightType on page 52. RouteFeatureType: RouteFeatureWeightType motorway:-2; &mode=fastest;car;traffic:disabled;motorway:2 RoutingTypeType RoutingType 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.

51 Routing API Developer's Guide 51 Enumeration fastest shortest scenic fastestnow directdrive 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. Route calculation from start to destination disregarding any traffic conditions. In this mode, the distance of the route is minimized. Route calculation that favors scenic routes and landscapes. This value is a convenience value that is equivalent to routing type "fastest"combined with traffic mode enabled and considering the departure time. If departure time is omitted, the current time ( now ) is assumed. This value is a convenience value that is equivalent to routing type "fastest" combined with traffic mode disabled" and considering the departure time. If departure time is omitted, the current time ( now ) is assumed. TrafficModeType Enumeration enabled disabled default Take the dynamic traffic conditions into account (current traffic, traffic patterns, short term closures, long term closures) Do not take dynamic traffic conditions into account (only apply time restrictions and seasonal closures) 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. TransportModeType Depending on the transport mode special constraints, speed attributes and weights are taken into account during route calculation. Enumeration car pedestrian truck Route calculation for cars. 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. Route calculation for trucks. This mode will consider truck limitations on links and will use different speed assumptions when calculating the route.

52 Routing API Developer's Guide 52 RouteFeatureType The 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. Parameter tollroad motorway boatferry railferry publictransport tunnel dirtroad park HOVLane stairs Identifier for toll roads Identifier for motorways Identifier for boat ferries Identifier for rail ferries Identifier for public transport Identifier for tunnels Identifier for dirt roads Identifier for links through parks Identifier for high-occupancy vehicle (HOV) lanes Identifier for stairs. This route feature is only applicable for pedestrian routing. RouteFeatureWeightType Route feature weights are used to define weighted conditions on special route features like tollroad, motorways, etc. Enumeration -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.

53 Routing API Developer's Guide 53 JSON Representation The jsonattribute parameter controls the JSON response represntation. Combine different values by adding the respective values. Value 1 Lower case first character of identifiers, this is default behaviour. 2 Include null elements in JSON output. The default is to suppress null elements 8 Include _type element in JSON output for classes with abstract parent classes, this is 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: &app_code=ajknxv84fjrb0kihaws0tg &waypoint0=geo! , &waypoint1=geo! , &jsonattributes=39 &mode=fastest;car; Response Data Types Articles 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)

54 Routing API Developer's Guide 54 vehicle information (for example, maneuvering capabilities) route information (for example, start and end point of the route, route sections, waypoints along the 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. CalculateRouteResponseType CalculateRouteResponseType 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 27 for details on associated request elements. Data elements may be hidden if they contain no data. Figure 4: CalculateRouteResponseType CalculateRouteResponseType defines the following attributes:

55 Routing API Developer's Guide 55 Table 4: Response Elements Element MetaInfo RouteResponseMetaInfoType on page 75 Route RouteType on page 77 Language LanguageCodeType on page 105 Provides details about the request itself, such as the time at which it was processed, a request id, or the map version on which the calculation was based. Contains the calculated path across a navigable link network, as specified in the request. Routes contain navigation instructions for a single trip as: waypoints (fixed locations) and route legs (sections of the route between waypoints). Each response may also include information about the route itself, such as its overall shape, map location, or a summary description. Indicates the language used for all textual information related to the route. If the requested language is unavailable, the service defaults to American English (en-us). GetRouteResponseType GetRouteResponseType contains response data, structured to match a particular request for the GetRoute operation. Refer to Get Route on page 34 for details on associated request elements. In this request, the Route element reflects an updated calculation for the original destination(s), based on the submitted request position. Figure 5: GetRouteResponseType GetRouteResponseType defines the following attributes: Table 5: Response Elements Element MetaInfo RouteResponseMetaInfoType on page 75 Provides details about the request itself, such as the time at which it was processed, a request id, or the map version on which the calculation was based.

56 Routing API Developer's Guide 56 Element Progress TravelProgressType on page 86 Route RouteType on page 77 This element displays progress data along a route that has been calculated previously. Based on a position provided in the GetRoute request, the Progress element displays a verified current position, remaining time, and remaining distance for route. Contains the calculated path across a navigable link network, as specified in the request. Routes contain navigation instructions for a single trip as: waypoints (fixed locations) and route legs (sections of the route between waypoints). Each response may also include information about the route itself, such as its overall shape, map location, or a summary description. GetLinkInfoResponseMetaInfoType Meta information which is not directly related to GetLinkInfo service is wrapped within a separate element. Table 6: Get Link Response MetaInfo elements Element RequestId xs:string Mirrored RequestId value from the request structure. Used to trace requests. Timestamp xs:datetime Time at which the search was processed. GetRouteResponseType GetRouteResponseType contains response data, structured to match a particular request for the GetRoute operation. Refer to Get Route on page 34 for details on associated request elements.

57 Routing API Developer's Guide 57 In this request, the Route element reflects an updated calculation for the original destination(s), based on the submitted request position. Figure 6: GetRouteResponseType GetRouteResponseType defines the following attributes: Table 7: Response Elements Element MetaInfo RouteResponseMetaInfoType on page 75 Progress TravelProgressType on page 86 Route RouteType on page 77 Provides details about the request itself, such as the time at which it was processed, a request id, or the map version on which the calculation was based. This element displays progress data along a route that has been calculated previously. Based on a position provided in the GetRoute request, the Progress element displays a verified current position, remaining time, and remaining distance for route. Contains the calculated path across a navigable link network, as specified in the request. Routes contain navigation instructions for a single trip as: waypoints (fixed locations) and route legs (sections of the route between waypoints). Each response may also include information about the route itself, such as its overall shape, map location, or a summary description.

58 Routing API Developer's Guide 58 CalculateIsolineResponseType The Routing API returns a top-level element, CalculateIsolineResponse, as the answer to a CalculateIsolineRequest. Figure 7: CalculateIsolineResponseType

59 Routing API Developer's Guide 59 Table 8: Response elements Element MetaInfo RouteResponseMetaInfoType on page 75 Center GeoCoordinateType on page 102 Isoline GeoPolylineType on page 102 Provides details about the request itself, such as the time at which it was processed, a request id, or the map version on which the calculation was based. Center of the resulting isolines. The center is the coordinate representation in the routing network of the start waypoint defined in the request. This is supported only if the Start in a request is defined by GeoWaypointType or one LinkID. List of lines that connect the end points of routes with the specified length/ duration from the center. Each length/duration entry in the request corresponds to one isoline in the response (with maintained order). Routing Data Types These types directly enable the routing process. They are used by CalculateRoute, GetRoute, GetLinkInfo, and CalculateIsoline. Routing Data Types fall into these categories: Enumeration Types on page 60, which are simple, routing-related types that are restricted to a 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 71 DynamicSpeedInfoType on page 65 TruckRestrictionsType on page 88 vehicle information (for example, maneuvering capabilities) ManeuverType on page 67 PrivateTransportManeuverType on page 74 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 89 RouteSummaryType on page 83 RouteSummaryByCountryType on page 85 RouteSummaryByCountryType on page 85 Enumeration Types on page 60

60 Routing API Developer's Guide 60 TravelProgressType on page 86 RouteNoteType on page 82 Enumeration Types Type IncidentTypeType Defines identifiers for different incidents. Enum [accident, congestion, disabledvehicle, roadhazard, construction, plannedevent, masstransit, othernews, weatheralert] LineStyleType Line style used to draw a line. Enum [solid, dotted, dash] PlaceEquipmentType Defines identifiers for equipment available at a place. Enum [stairs, elevator, escalator, barrierfree, shelter, restroom, shopping, restaurant, baggageroom, bikedepot, bikeaccepted, parking] RouteLinkFlagType Defines a list of special characteristics that may apply to a link. Enum [boatferry, dirtroad, fourwheeldrive, gatedarea, HOVLane, motorway, nothroughroad, park, privateroad, railferry, scenic, stairs, station, tollroad, tunnel, unpaved] boatferry: Link can only be traversed by using a boat ferry dirtroad: Link is part of a dirt road fourwheeldrive: Link is part of a road that is suitable only for vehicles with four-wheel drive gatedarea: Link is part of a gated area HOVLane: Link can only be traversed by using high-occupancy vehicle (HOV) lanes 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 park: Link is part of a park privateroad: Link is part of a private road railferry: Link can only be traversed by using a rail ferry scenic: Link is part of a road that has been marked as scenic stairs: Link can only be traversed by using stairs station: Link is located at a station tollroad: Link is part of a toll road tunnel: Link passes through a tunnel unpaved: Link is part of an unpaved road

61 Routing API Developer's Guide 61 Type 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 [ routingoptionviolated, passingplace, roadnamechanged, sharpcurveahead, linkfeatureahead, timedependentrestriction] 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 in the additional data container of the corresponding note. passingplace: Indicates that a special place (city, country border, POI, etc.) will be passed in the segment following the maneuver. The service provides the name and type of the place in the additional data container of the corresponding note. roadnamechanged: Indicates that road name and/or route number will change at the given position without an additional maneuver taking place. The service provides the new street name and/or route number in the additional data container of the corresponding note. sharpcurveahead: Indicates that a sharp curve is ahead of the maneuver's position. linkfeatureahead: Indicates that a special link characteristic will be met after the maneuver. The service provides the identifier for the link characteristic (see enumeration type LinkFlag) in the additional data container of the corresponding note. timedependentrestriction: Indicates time dependent restrictions for the segment following the maneuver, such as "road closed in winter". The service provides the validity period of this restriction in the corresponding note. HazardousGoodTypeType Defines names for different types of hazardous goods. explosive: Explosive material gas: Gas flammable: Flammable material combustible: Combustible material organic: Organic material poison: Poison

62 Routing API Developer's Guide 62 Type radioactive: Radio-active material corrosive: Corrosive material poisonousinhalation: Goods which are poisonous upon inhalation harmfultowater: Goods which are harmful to water other: Other types of hazardous goods ResourceTypeType Defines a list of supported resource type identifiers. Enum[junctionView, signasreal, directionarrow, advertising, routetemplate] junctionview: Identifier for the bitmap representing the Junction View signasreal: Identifier for the bitmap representing the sign-as-real information 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 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. WaypointParameterEntityTypeType Defines identifiers for different waypoint entity types. A waypoint entity could be an airport an intersection or a full address. The types are used to specify the concrete entity type in waypoint parameters. Enum [airport, intersection, intersectioninternal, fulladdress] airport: Short form ap. A waypoint entity type denoting an airport.

63 Routing API Developer's Guide 63 Type intersection: Short form in. A waypoint entity type denoting an intersection of two streets. The EntityDetails element in the corresponding Waypoint instance should contain the names of the intersecting streets seperated by an ampersand sign. Note that the ampersand needs to be properly URL encoded. intersectioninternal: Short form ii. A waypoint entity type denoting an intersection. The EntityDetails element in the corresponding Waypoint instance must contain the encodeded details about the intersection. fulladdress: Short form fa. A waypoint entity type denoting a full address. The EntityDetails element in the corresponding Waypoint instance must contain the encodeded details about the intersection. 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" 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"

64 Routing API Developer's Guide 64 Type 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" leftroundaboutexit8: roundabout maneuver (left-hand traffic), such as "Take the 8th exit of the roundabout onto" leftroundaboutexit9: roundabout maneuver (left-hand traffic), such as "Take the 9th exit of the roundabout onto" leftroundaboutexit10: roundabout maneuver (left-hand traffic), such as "Take the 10th exit of the roundabout onto" leftroundaboutexit11: roundabout maneuver (left-hand traffic), such as "Take the 11th exit of the roundabout onto" leftroundaboutexit12: roundabout maneuver (left-hand traffic), such as "Take the 12th exit of the roundabout 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"

65 Routing API Developer's Guide 65 Type 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" rightroundaboutexit8: roundabout maneuver (right-hand traffic), such as "Take the 8th exit of the roundabout onto" rightroundaboutexit9: roundabout maneuver (right-hand traffic), such as "Take the 9th exit of the roundabout onto" rightroundaboutexit10: roundabout maneuver (right-hand traffic), such as "Take the 10th exit of the roundabout onto" rightroundaboutexit11: roundabout maneuver (right-hand traffic), such as "Take the 11th exit of the roundabout onto" rightroundaboutexit12: roundabout maneuver (right-hand traffic), such as "Take the 12th exit of the roundabout onto" SpeedCategoryType General speed trend of a road based on posted or implied speed limit. Note: Speed Category values consider factors besides legal speed limit (for example, physical restriction or access characteristics), and thus can differ from Speed Limit values, which represent the legal speed limits only. Enum [SC1, SC2, SC3, SC4, SC5, SC6, SC7, SC8] SC1: >130 km/h / >80 MPH SC2: km/h / MPH SC3: km/h / MPH SC4: km/h / MPH SC5: km/h / MPH SC6: km/h / MPH SC7: km/h / 6-20 MPH SC8: <11 km/h / <6 MPH DynamicSpeedInfoType To 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:

66 Routing API Developer's Guide 66 time-dependant road closures and maneuvers (such as seasonal closures, reversible lanes, timedependent truck restrictions) real-time traffic information and incidents pattern-based traffic prediction, if the calculation is for a future time DynamicSpeedInfoType is an xs:sequence type with the following data elements. Figure 8: DynamicSpeedInfoType Element TrafficSpeed SpeedType on page 108 TrafficTime xs:duration on page 111 BaseSpeed SpeedType on page 108 BaseTime xs:duration on page 111 Traffic-enabled speed, which is the estimated speed considering traffic-relevant constraints. Contains the travel time estimate for this element, considering traffic and transport mode. Based on the TrafficSpeed. The service may also account for additional time penalties, so this may be greater than the element length divided by the TrafficSpeed. Estimated speed without considering any traffic-related constraints. Contains the travel time estimate for this element, considering transport mode but not traffic conditions. Based on the BaseSpeed. The service may also account for additional time penalties, therefore this may be greater than the element length divided by the BaseSpeed. JamFactor xs:double

67 Routing API Developer's Guide 67 Element The number between 0.0 and 10.0 indicating the expected quality of travel, where 0 is high quality and 10.0 is poor quality or high level of traffic jam indicates that the service could not calculate Jam Factor. JamFactorTrend xs:duration on page 111 Confidence xs:duration on page 111 The number between -1.0 and +1.0 indicating the trend of the jam factor over a period of time, where -1.0 is a trend of high quality travel and 1.0 is a trend of poor quality travel. Level of confidence that Traffic.com has in the flow data, as a value from 0.0 to 1.0 where 1.0 is the highest level of confidence (indicating dense sensor coverage) and 0.0 is the lowest level of confidence (in other words, completely estimated). The confidence value of the predicted flow considers the current flow confidence. GeneralizationType The service returns GeneralizationType in route responses for requests carrying the generalizationtolerances parameter. The default is to not return any GeneralizationType. Figure 9: GeneralizationType Element 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 given generalization tolerance. ManeuverType A 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 74. It includes only attributes that are common for any given maneuver type.

68 Routing API Developer's Guide 68 Note: In this element, the Length, Shape, and Note refer to the leg immediately following the maneuver. Figure 10: ManeuverType ManeuverType defines the following attributes: Attribute id ElementReferenceType on page 100 Key that identifies this element uniquely within the response.

69 Routing API Developer's Guide 69 ManeuverType defines the following data elements: Element Position GeoCoordinateType on page 102 Position where the maneuver starts. Instruction xs:string of the required maneuver, for example, "Turn left onto Minna St." Response format for this description can be either text or HTML as selected in InstructionFormatType on page 47, and using the measurement system specified 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. PlaceEquipment xs:list TravelTime xs:duration on page 111 List of obstacles at the maneuver, where items in the list can be any of PlaceEquipmentType enumerations. Describes the amount of time for a single maneuver, traffic considered if this has been enabled. See also: TrafficMode. Length DistanceType on page 99 Length (in meters) for the leg between this maneuver and the next. Shape GeoPolylineType on page 102 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 shape subsegment 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 shape subsegment associated with this Maneuver. Must be preceded by FirstPoint. Time xs:datetime Note RouteNoteType on page 82 Estimated point in time when the maneuver should occur, based on the selected transport mode. Options include: Private transport: calculated arrival or departure time for the maneuver. The time information is given in the time zone of the maneuver's position. Additional information about the route segment following the maneuver, such as "sharp curve ahead", "accessing toll road", etc. NextManeuver ElementReferenceType on page 100

70 Routing API Developer's Guide 70 Element Reference to the next maneuver on the recommended route. ToLink LinkIdType on page 106 The key of the next outgoing link. BoundingBox GeoBoundingBoxType on page 103 Coordinates defining the bounding box of the entire maneuver.

71 Routing API Developer's Guide 71 PrivateTransportLinkType A private transport link is a link traversed in a route using private mode of transportation such as car, truck, pedestrian. Figure 11: PrivateTransportLinkType

72 Routing API Developer's Guide 72 PrivateTransportLinkType defines the following attributes in addition to those derived from RouteLinkType: Element SpeedLimit SpeedType on page 108 Legal speed limit (based on link only, unrelated to vehicle type). Contains the following 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 65 Dynamic speed information on the link which can change over time, such as traffic information (if enabled) or time-dependent road closures. ExternalResource ExternalResourceType on page 100 Series of references to external resources (for example, bitmaps). The client is responsible for downloading the referenced resource. 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. TMCCodes TMCCodeType on page 108 List of TMCCodes that cover the link. FunctionalClass FunctionalClassType on page 101 The functional class assigned to the link. Address AddressType on page 93 Address of the street the link is passing. RoadNumber xs:string Number of the road (such as A5, B49, etc.) that the link is passing. Timezone xs:string Timezone in which the link is located. Includes daylight savings information.

73 Routing API Developer's Guide 73 Element Incident IncidentType on page 109 An incident describes a temporary event on a route network link. It typically refers to a real world incident (accident, road construction, weather condition, etc.) on a street or street segment. See also IncidentTypeType. CorridorLevel xs:int The corridor level defines a logical distance from the base route. Any time a "faulty" maneuver is detected the level is increased by 1. The base route has a constant corridor level of 0. Stubs xs:list Reference keys to other links within the corridor, which are not part of the recommended route, but can be entered from this link. See also LinkIdType on page 106. 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 LinkIdType on page 106. PredecessorLinkIds xs:list List of LinkIds that can be used to enter the current link. See also LinkIdType on page 106. SpeedCategory SpeedCategoryType Classifies the general speed trend of a road based on posted or implied speed limit. Speed Category values represent the combination of several factors besides legal speed limit, for example, physical restriction or access characteristics. Therefore, Speed Category values can differ from Speed Limit From/To values, which represent the legal speed limits only. Available values are in range: SC1 SC8: SC1 >130 km/h / >80 MPH SC km/h / MPH SC km/h / MPH SC km/h / MPH SC km/h / MPH SC km/h / MPH SC km/h / 6-20 MPH SC8 <11 km/h / <6 MPH

74 Routing API Developer's Guide 74 PrivateTransportManeuverType A 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 12: PrivateTransportManeuverType PrivateTransportManeuverType defines the following attributes in addition to those derived from ManeuverType: Element Direction DirectionType Maneuver direction hint. Can be used to display the appropriate arrow icon for the maneuver. Action PrivateTransportActionType Code that identifies the action for this maneuver. Does not always indicate a direction. 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, "Flughafen Berlin-Tegel, Berlin-Zentrum, Berlin-Zehlendorf, Potsdam-Zentrum, A115" NextRoadName xs:string

75 Routing API Developer's Guide 75 Element RoadNumber Name of the next road in the route that the maneuver is heading toward. 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. SelectedLanes xs:int List of lanes that can be used for this maneuver. Lanes are references by their list index strating at index 0. RoadTemplate ExternalResourceType on page 100 External SVG resource that provides a template for displaying the route (for example, A5, B49). It is the client's responsibility to add the route name into the template to create the correct image for the maneuver. NavigationSignPost xs:string Name of the street as given on the sign post, but limited to the context of the route. 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. TrafficTime xs:duration on page 111 BaseTime xs:duration on page 111 Traffic-enabled time. Estimated time spent on the segment following this maneuver, based on the TrafficSpeed. The service may also account for additional time penalties, therefore this may be greater than the link length divided by the traffic speed. Estimated time spent on the segment following this maneuver, without considering traffic conditions, as it is based on the BaseSpeed. The service may also account for additional time penalties, therefore this may be greater than the link length divided by the base speed. RouteResponseMetaInfoType Meta information which is not directly related to the route calculation is wrapped within a separate element.

76 Routing API Developer's Guide 76 Table 9: Route Response MetaInfo elements Element 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 105 List of KeyValuePairType elements as genericcontainer to attach additional information to the 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]

77 Routing API Developer's Guide 77 RouteType A 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 13: RouteType RouteType defines the following attributes: Element RouteId xs:string Waypoint WaypointType on page 89 Permanent unique identifier of the route, generated based on route links. Can be used to reproduce any previously calculated route.

78 Routing API Developer's Guide 78 Element 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 the destination. Any points in between the two are considered via points. Mode RoutingModeType on page 50 Shape GeoPolylineType on page 102 Settings for route calculation. One mode can be specified for each route. BoundingBox GeoBoundingBoxType on page 103 Shape of the route as a polyline. The accuracy might depend on the resolution specified in mpp (meters per pixel) when requesting the route. In some use cases (like web portals), only the route's shape is required without the nested structure 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 be represented using this attribute at route level. Bounding Box of the route. Leg RouteLegType on page 80 Note RouteNoteType on page 82 Partition of the route into legs between the different waypoints. Summary RouteSummaryType on page 83 Notes that are either related to the calculation (violated routing options) or that refer the route as a whole. In addition to these notes additional notes can be attached to maneuvers. The maneuver notes are usually related to the route segment following the maneuver and would be of interest when passing this segment. Overall route distance and time summary. SummaryByCountry RouteSummaryByCountryType on page 85 Route distance and time summary per traversed country. Generalizations Enumeration Types on page 60 A simplified base polyline with a given tolerance parameter used to reduce the number of points. The points in the base polyline are implicitly referenced by index. RouteLinkType A link is a path segment in the routing network, such as a road. This type is an abstract base class for PrivateTransportLinkType on page 71. It includes the common attributes that every that every link type provides.

79 Routing API Developer's Guide 79 In this type, FirstPoint and LastPoint be used as alternate representation to avoid repeating shapes already provided at the route level. Figure 14: RouteLinkType RouteLinkType defines the following attributes: Element LinkId LinkIdType on page 106 Shape GeoPolylineType on page 102 Length DistanceType on page 99 Permanent ID which references a network link. When presented with a minus sign as the first character, this ID indicates that the link should be traversed in the opposite direction of its default coding (for example, walking SW on a link that is coded as one-way traveling NE). A polyline representation of the parent element (for example, route, route leg, link, etc.). Length of the parent element, always provided in meters. RemainDistance DistanceType on page 99 Distance from the start of this element to the destination of the route.

80 Routing API Developer's Guide 80 Element RemainTime xs:duration on page 111 AdditionalData KeyValuePairType on page 105 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 the user. Generic container to store additional information. NextLink LinkIdType on page 106 Reference to the next link on the recommended route. Maneuver ElementReferenceType on page 100 Reference to the maneuver that needs to take place to go from the current link to the next link in the route. RouteLegType The 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 15: RouteLegType

81 Routing API Developer's Guide 81 RouteLegType defines the following attributes: Element Start WaypointType on page 89 End WaypointType on page 89 Length DistanceType on page 99 Route waypoint that is located at the start of this route leg. This waypoint matches one of the waypoints in the Route. Route waypoint that is located at the end of this route leg. This waypoint matches one of the waypoints in the Route. Length of the leg. TravelTime xs:duration on page 111 Maneuver ManeuverType on page 67 The time needed to travel along this route leg. Considers any available traffic information, if enabled and the authorized for the user. 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 106. SubLegSummary RouteSummaryType on page 83 Distance and time summary information for any sub legs of this route leg. The service defines sub legs where passthrough waypoints are used, so the list may be empty if no such waypoints exist within this route leg.

82 Routing API Developer's Guide 82 RouteNoteType Route 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 16: RouteNoteType RouteNoteType defines the following elements: Element Type RouteNoteTypeType Type of the note. Please refer to the enumeration type RouteNoteTypeType for available values. Code RouteNoteCodeType A code that uniquely identifies the note. This code can be used to decide how to display the note (such as with a warning icon). Please refer to the enumeration type RouteNoteCodeType for available values. Text xs:string Position GeoCoordinateType on page 102 A short text describing the note. Please note that this attribute is not subject to internationalization and should therefore not be used in user displays. Position at which the note is relevant. LinkIds LinkIdType on page 106

83 Routing API Developer's Guide 83 Element Location at which the note is relevant given by a list of linkids. ValidityPeriod xs:duration on page 111 Validity period of the note. This attribute is used to specify time dependent restrictions (such as "road is closed during winter"). AdditionalData KeyValuePairType on page 105 Container for additional data to be stored along with the note. RouteSummaryType This type provides summary information for the entire route. This type of information includes travel time, distance, and descriptions of the overall route path. Additionally, RouteSummaryType contains any special flags on the route, such as "toll road" or "ferry." Figure 17: RouteSummaryType RouteSummaryType defines the following attributes: Element Distance DistanceType on page 99

84 Routing API Developer's Guide 84 Element Indicates total travel distance for the route, in meters. TrafficTime xs:duration on page 111 BaseTime xs:duration on page 111 BaseTime xs:duration on page 111 Contains the travel time estimate for this element, considering traffic and transport mode. Based on the TrafficSpeed. The service may also account for additional time penalties, so this may be greater than the element length divided by the TrafficSpeed. Contains the travel time estimate for this element, considering transport mode but not traffic conditions. Based on the BaseSpeed. The service may also account for additional time penalties, therefore this may be greater than the element length divided by the BaseSpeed. Total travel time not considering traffic but taking the transport mode into account. Flags RouteLinkFlagType Entries RouteSummaryType on page 83 Special link characteristics (like ferry or motorway usage) which are covered by the route. A route summary contains a rough description of the route limited to the essential streets and maneuvers. Each of these maneuvers/routes is described in a route summary entry. Text xs:string AdditionalData KeyValuePairType on page 105 Textual description of the route summary in the language requested by the user. For example, if the user requested English, the route summary might say: "The trip takes 7.5 miles and 13 min." Container for additional summary information. TravelTime xs:duration on page 111 Total travel time optionally considering traffic depending on the request parameters.

85 Routing API Developer's Guide 85 RouteSummaryByCountryType Rather than providing the entire route summary as a single summary, you can use this type to return summary information for each country in the route. Figure 18: RouteSummaryByCountryType In addition to its base type, RouteSummaryType, the RouteSummaryByCountryType defines the following elements: Element Country CountryCodeType on page 99 Country code of the associated route summary, using the ISO alpha-3 format.

86 Routing API Developer's Guide 86 RouteSummaryEntryType Each route summary contains a general description of the route, limited to the essential streets and maneuvers. Each of these maneuvers or routes are described in a route summary entry. Figure 19: RouteSummaryEntryType RouteSummaryEntryType defines the following attributes: Table 10: Route Summary Entry Type Attributes Element Label xs:string Textual description of the summary entry. Distance DistanceType on page 99 Travel distance for the part of the route represented by the summary entry. TravelProgressType This element displays progress data along a route that has been calculated previously. Based on a position provided in the GetRoute request, the Progress element displays a verified current position, remaining time, and remaining distance for route. Figure 20: TravelProgressType

87 Routing API Developer's Guide 87 TravelProgressType defines the following elements: Table 11: Travel Progress Type Attributes Element mappedposition xs:string remaindistance DistanceType on page 99 remaintime xs:duration on page 111 Contains the current position, potentially evaluated after map matching a sequence of positions provided in the request. Contains the distance remaining to destination, from the mappedposition. Remaining time needed to reach the destination from the current position. Considers traffic information if enabled and authorized.

88 Routing API Developer's Guide 88 TruckRestrictionsType This type is used to describe which restrictions apply on a link for trucks, such as weight or height restrictions or areas where they may not go. It is relevant to identifying routing appropriate for fleets. Figure 21: TruckRestrictionsType TruckRestrictionsType defines the following elements: Element TrailerForbidden xs:boolean Marks element as forbidden for trucks with trailers. ForbiddenHazardousGoods HazardousGoodTypeType LimitedWeight WeightType on page 100 Indicates forbidden hazardous goods types. Please refer to the enumeration type HazardousGoodTypeType for available values. Indicates maximum weight in tons. WeightPerAxle WeightType on page 100

89 Routing API Developer's Guide 89 Element Indicates maximum weight per axle in tons/ TrailerWeight WeightType on page 100 Indicates maximum trailer weight in tons. Height xs:double Indicates maximum truck height in meters. Width xs:double Indicates maximum truck width in meters. Length xs:double Indicates maximum truck length in meters. WaypointType Waypoints 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 22: WaypointType WaypointType defines the following elements:

90 Routing API Developer's Guide 90 Element LinkId LinkIdType on page 106 ID of the link on the navigable network associated with the waypoint. MappedPosition GeoCoordinateType on page 102 OriginalPosition GeoCoordinateType on page 102 If this waypoint is a start point, this will be mapped to the beginning of the link. If used as destination point or via point, it will be mapped to the end of the link. Original position as it was specified in the corresponding request. The value will depend 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. MatchQuality xs:float Defines the quality of the map matching results, between 0.0 and 1.0, where 1.0 represents a 100% match. Spot xs:double Contains the relative position of the mapped location along the link, as the fractional distance between the link's reference node and the non-reference node. Ranges in value from 0 to 1. Base Data Types Base 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 108 DistanceType on page 99 WeightType on page 100 PeriodType on page 107 HeadingType on page 104 AccuracyType on page 91 AngleType on page 98

91 Routing API Developer's Guide 91 FunctionalClassType on page 101 geometry types (for example, bounding box, corridor) GeoCoordinateType on page 102 CoordinatesArrayType on page 98 GeoBoundingBoxType on page 103 location-based information (for example, latitude, longtitude, country, language) LatitudeType on page 106 LongitudeType on page 106 AltitudeType on page 97 TMCCodeType on page 108 LanguageCodeType on page 105 CountryCodeType on page 99 AddressType on page 93 general (ID types, outside resources, additional information containers) AlternativeValueType on page 97 KeyValuePairType on page 105 ElementReferenceType on page 100 ExternalResourceType on page 100 LinkIdType on page 106 NameType Type on page 109 IncidentType on page 109 SideOfStreetType on page 108 TextSemanticsType on page 108 standard XML schema types, including how the Routing API handles these elements in for JSON format requests xs:datetime on page 110 xs:duration on page 111 xs:list on page 112 xs:sequence on page 113 AccuracyType The 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

92 Routing API Developer's Guide 92 Precision: 4 positions after decimal point, additional positions are ignored Examples

93 Routing API Developer's Guide 93 AddressType Address record of a Location. Attributes are normalized to US feature names and can be mapped to the local feature levels (for example, State matches "Bundesland" in Germany) using mapping tables. Figure 23: LocationFilterType

94 Routing API Developer's Guide 94 Address Type AddressType defines the following attributes: Element Label Country State County City District Street StreetDetails Definition Assembled address value for displaying purposes. ISO 3166-alpha-3 country code Includes the first subdivision level(s) below the country. Where commonly used, this is a state code (in other words, CA for California). Includes the second subdivision level(s) below the country. Use of this field is optional if a second subdivision level is not available. Refers to the locality of the address. Includes the subdivision level below the city. Use of this field is optional if a second subdivision level is not available. Refers to the street name. Not yet supported. Detail information about the street splitting the street name into the different parts like "base name", "prefix", "suffix". BaseName Base name part of the street name. The base name is a numbered route, local name, or commonly accepted name for a street. StreetType Street type part of the street name. Street Type is the local municipality designator of each road, such as "street", "road", "strasse", "straat", "via", or "rue de la". Street Types are defined as either "preceding" or "following" the Base Name and "attached" or "unattached" to the Base Name. StreetTypeBefore Defines if the street type is before or after the base name. StreetTypeAttached Defines if the street type is attached or unattached to the base name. Prefix A prefix is a directional identifier that precedes, but is not included in, the base name of a road. Suffix A suffix is a directional identifier that follows, but is not included in, the base name of a road. Direction Indicates the official directional identifiers assigned to highways, typically either "North/South" or "East/West"

95 Routing API Developer's Guide 95 Element HouseNumber PostalCode Floor Suite Definition House number. Depending on regional characteristics, can also be house name. For API implementations which do not support separate street and house number fields, this field can be omitted. Postal code Floor number Suite number or name Localized Name Information Not currently supported. The following elements expose localized name information about the address: CountryName List of localized country names. Unlike the "Country" element this element includes information about language and text semantics for each name. StateName List of localized state names. Unlike the "State" element this element includes information about language and text semantics for each name. CityName List of localized city names. Unlike the "City" element this element includes information about language and text semantics for each name. DistrictName List of localized district names. Unlike the "District" element this element includes information about language and text semantics for each name. StreetName List of localized street names. Unlike the "Street" element this element includes information about language and text semantics for each name. AlternativeAttributes Attributes in different languages and/or with different semantics. (see AlternativeValueType) AdditionalData Generic key/value container to keep additional attributes. The defined key/values are: "CrossingStreet0" First cross street near matched address "CrossingStreet1"

96 Routing API Developer's Guide 96 Second cross street near matched address. This value is omitted by the search module, if the location s distance to CrossingStreet0 is less than half of the distance to CrossingStreet1. "CountryName" Non-abbreviated, full name of the country. "StateName" Non-abbreviated, full name of the state. "Country2" If requested in SearchRequest.additionalData["Country2"], this field provides the ISO-3166 alpha-2 country code. By default, two-letter codes are not returned. Secondary address units as defined by the US Postal Service can be recognized and returned if the PreserveUnitDesignators switch was set to true in SearchRequest.additionalData. Recognized address units are returned in the AdditionalData field, where the designator is the key and the unit value is the value of the entry: "APT" - recognized value of unit type "Apartment" "BLDG" - recognized value of unit type "Building" "FL" - recognized value of unit type "Floor" "STE" - recognized value of unit type "Suite" "UNIT" - recognized value of unit type "Unit" "RM" - recognized value of unit type "Room" "DEPT" - recognized value of unit type "Department" "UnknownUnit" - unrecognized address unit value, which is usually printed with a pound ("#") sign.

97 Routing API Developer's Guide 97 AlternativeValueType This element is a generic container to keep textual values for any attribute in different languages and/or with different semantics or type. Figure 24: AlternativeValueType AlternativeValueType defines the following attributes: Key Attribute/field name Value Text value in selected language and with selected semantics and type Type Type of the alternative text (see NameType Type on page 109) Semantics Semantics of the alternative text (see TextSemanticsType on page 108) Language Language of the alternative text (RFC 5646 Language Tag) AltitudeType The altitude specifies the elevation of a point above mean sea level. AltitudeType is an xs:double type with the following restrictions: Unit: meters Precision: 2 positions after decimal point, additional positions are ignored Examples 300

98 Routing API Developer's Guide AngleType Angle in degrees. AngleType is an xs:double type with the following restrictions: Must satisfy: -360 value 360 Unit: degrees from reference node Examples CoordinatesArrayType In 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 102 or GeoPolygonType on page 100 type useful. XML Representation The following example illustrates how the CoordinatesArray looks like for a list of two 2#dimensional coordinates: <Foo> , , </Foo>

99 Routing API Developer's Guide 99 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: , ; , CountryCodeType This type is used whenever a country needs to be referenced. CountryCodeParameterType is a xs:string type with the following restrictions: Format: Country code according to ISO alpha-3 Examples DEU GBR DistanceType This type can be used whenever distances need to be represented. DistanceType is an xs:double type with the following restrictions: Unit: meters Precision: 4 positions after decimal point, additional positions are ignored Examples

100 Routing API Developer's Guide 100 WeightType This 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) Precision: 3 positions after decimal point, additional positions are ignored Query Parameter Representation Valid examples: GeoPolygonType While the CoordinatesArrayType on page 98 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 100, 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. ElementReferenceType This 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. ExternalResourceType Reference to an external resource (for example, a bitmap). The client is responsible for retrieving the referenced resource. Contains the following: ResourceType

101 Routing API Developer's Guide 101 The semantics of the resource. Filename Filename of the resource Note: This type can only be used to request junction info image names. Requesting images is unsupported. Examples <CompanyLogo> <ResourceType>vendorIcon</ResourceType> <Filename>727e0c0e b2f83f465f74626</Filename> </CompanyLogo> FunctionalClassType The functional class is used to classify roads depending on the speed, importance and connectivity of the road. It is an xs:byte type with the following restrictions: Must satisfy: 1 value < 5 The value represents one of the five levels: 1: allowing for high volume, maximum speed traffic movement 2: allowing for high volume, high speed traffic movement 3: providing a high volume of traffic movement 4: providing for a high volume of traffic movement at moderate speeds between neighbourhoods 5: roads whose volume and traffic movement are below the level of any functional class Examples 1 2 3

102 Routing API Developer's Guide 102 GeoCoordinateType The GeoCoordinateType represents a geographical position. Figure 25: 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. Query Parameter Representation Whenever a coordinate needs to be represented in query strings, use the following format: <Latitude> + "," + <Longitude> (+ "," + <Altitude>)? GeoPolylineType While the CoordinatesArrayType on page 98 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.

103 Routing API Developer's Guide 103 GeoBoundingBoxType A GeoBoundingBoxType defines a rectangular area in a geographic coordinate system. This type is derived from the abstract base type GeoAreaType. Figure 26: 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.

104 Routing API Developer's Guide 104 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) Query Parameter Representation 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= , ; , HeadingType Heading in degrees starting at true North and continuing clockwise around the compass. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. This type can be used whenever directions need to be represented. HeadingType is an xs:double type with the following restrictions: Must satisfy: 0 value < 360 Unit: decimal degrees

105 Routing API Developer's Guide 105 Measured: clockwise starting at 0 degrees at true North Precision: 4 positions after decimal point, additional positions are ignored Examples KeyValuePairType This type is a generic container for arbitrary information. Key/value pairs are supported to transport non-typed generic information which has not currently been defined in API data structures. Figure 27: KeyValuePairType The following attributes are defined: Key Name of the property The value is included directly in the body of the element. Query Parameter Representation A KeyValuePair can be represented in query strings as follows: <Key> + "," + <Value> Note: Representation formats: Special characters need to be URL-encoded. LanguageCodeType This 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

106 Routing API Developer's Guide 106 Examples de en-us LatitudeType Location of a place on Earth north or south of the equator. LatitudeType is an xs:double type with the following restrictions: Must satisfy: -90 value 90 Unit: decimal degrees Reference System: WGS 84 Precision: 7 positions after decimal point, additional positions are ignored Examples LinkIdType A 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+ LongitudeType Location of a place on Earth east or west of the prime meridian. LongitudeType is an xs:double type with the following restrictions: Must satisfy: -180 value 180 Unit decimal degrees Reference System: WGS 84 Precision: 7 positions after decimal point, additional positions are ignored

107 Routing API Developer's Guide 107 Query Parameter Representation Valid examples: PeriodType The PeriodType represents a time period between two distinct points in time. Figure 28: PeriodType The PeriodType has the following attributes: From Start date and time of the period Until End date and time of the period Query Parameter Representation The Period can be represented in query strings as follows: <From> + "," + <Until> Note: Null values are represented as "-" Note: Representation formats: <From>, <Until> The representation formats for xs:datetime apply.

108 Routing API Developer's Guide 108 SideOfStreetType Values to indicate on which side of a link an object is placed. The following enumeration values are available for SideOfStreetType: left right neither SpeedType This type can be used whenever speed information needs to be represented. SpeedType is an xs:double type with the following restrictions: Unit: m/s Precision: 2 positions after decimal point, additional positions are ignored Examples TextSemanticsType Available types of text semantics used in type AlternativeValue. Enumeration [synonym, exonym, unclassified]. TMCCodeType TMCCodeType is a xs:string type with the following restrictions: Fixed length: 9 characters Must match regular expression: \w\d{2}[+-pn]\d{5} Format: B + CC + D + EEEEE, where the following rules apply: B is the one character EBU Country Code. Note: EBU are defined for European Countries. There are no official EBU codes for Canada and the U.S. NAVTEQ Traffic has defined "C" for Canada and "1" for the U.S.

109 Routing API Developer's Guide 109 CC D is the two digit Location Table number. is the one character RDS direction, where: "+" - is in the positive direction and external to the Problem Location. "-" - is in the negative direction and external to the Problem Location. "P" - is in the positive direction and internal to the Problem Location. "N" - is in the negative direction and internal to the Problem Location. EEEEE is the five digit Location Code. This has leading zeros if necessary. NameType Type Available name types used in type AlternativeValue. Enumeration [basename (deprecated), shortbasename (deprecated), abbreviation (deprecated), primary, alternative]. IncidentType An incident describes a temporary event on a route network link. It typically refers to a real world incident (accident, road construction, weather condition, etc.) on a street or street segment. Figure 29: IncidentType ValidityPeriod

110 Routing API Developer's Guide 110 Time period when the incident is relevant Text A textual description of the event Type Classifier for the incident; there is currently no semantics or value restriction defined for this attribute Criticality Criticality on an integer scale: 0 = critical 1 = major 2 = minor 3 = low impact xs:datetime The 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 YYYY MM DD hh mm ss s zzzzzz 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 is a two-digit numeral that represents the month is a two-digit numeral that represents the day 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) is a two-digit numeral that represents the minute is a two-integer-digit numeral that represents the whole seconds represents the fractional seconds (optional) represents the timezone

111 Routing API Developer's Guide 111 The timezone portion zzzzzz is represented as follows: (("+" "-") + hh + ":"+ mm) "Z" Syntax "+" "-" "+" indicates a non-negative duration, "-" indicates a non-positive duration. hh mm "Z" is a two-digit numeral (with leading zeros as required) that represents the hours is a two-digit numeral that represents the minutes "Z" represent the zero-length duration timezone, UTC "Z" is the canonical representation for UTC datetime values. DateTime Example T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern Standard Time in the U.S.) is T17:00:00Z, five hours later than T12:00:00Z. xs:duration The 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 "-" Optional minus sign to represent negative durations. If the sign is omitted a positive duration is indicated. ny nm nd nh nm ns represents the number of years. Must be an unsigned integer. represents the number of months. Must be an unsigned integer. represents the number of days. Must be an unsigned integer. represents the number of hours. Must be an unsigned integer. represents the number of minutes. Must be an unsigned integer. represents the number of seconds, which can include decimal digits represent fractions of seconds.

112 Routing API Developer's Guide 112 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:list XML 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. Query Parameter Representation 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]> + "!" +

113 Routing API Developer's Guide 113 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 also xs:sequence on page 113). JSON Representation List types are represented as arrays: [<list[0]>, <list[1]>, <list[2]>, ] xs:sequence A 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. Query Parameter Representation 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]> + ";" +

114 Routing API Developer's Guide 114 "!" (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:list on page 112) JSON Representation Element sequences will be represented as arrays: [<list[0]>, <list[1]>, <list[2]>, ] LinkIdType A 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 Types Error details are transferred to the client using a generic error structure, which is returned instead of the actual response structure. Namespace Schema location(source)

115 Routing API Developer's Guide 115 XSD Version 1.0 Figure 30: ServiceErrorType The error type defines the following 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 Details RequestId AdditionalData Defined name of the concrete error, such as "InvalidInputData" or "ExceededUsageLimit". Clear text error message Arbitrary value to trace back the request. This value is copied from the request which caused the error. 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:

116 Routing API Developer's Guide 116 ApplicationError SystemError PermissionError Errors that are thrown since the business logic has detected some error Errors that are thrown due to technical reasons 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. InvalidCredentials This error is returned if the specified token was invalid or no contract could be found for this token. The following field mapping applies: Field ServiceError.type ServiceError.subtype Value PermissionError InvalidCredentials ServiceError.AdditionalData Entry 1: Key: token Value: token specified in the request InsufficientRights This error is returned if the user's contract exists for the given token but does not have the required entitlements. The following field mapping applies: Field ServiceError.type ServiceError.subtype Value PermissionError InsufficientRights ServiceError.AdditionalData Entry 1:

117 Routing API Developer's Guide 117 Field Value Key: token Value: token specified in the request Entry 2: Key: missing_entitlement Value: entitlement that is missing ContractViolated This error is returned if the user's contract exists for the given app_id but is not yet active or has already expired. The following field mapping applies: Field ServiceError.type ServiceError.subtype Value PermissionError ContractViolate ExceededUsageLimit This error is returned if the contract associated with the app_code has reached the usage limit for a certain entitlement. The following field mapping applies: Field ServiceError.type ServiceError.subtype Value PermissionError ExceededUsageLimit ServiceError.AdditionalData Entry 1: Key: token Value: token specified in the request Entry 2: Key: entitlement Value: entitlement that has reached usage limit Entry 3: Key: usage_limit

118 Routing API Developer's Guide 118 Field Value Value: Usage limit InvalidInputData This error is returned if the specified request parameters contain invalid data, such as due to wrong parameter syntax or invalid parameter combinations. The following field mapping applies: Field ServiceError.type ServiceError.subtype ServiceError.AdditionalData Value ApplicationError InvalidInputData One entry for each parameter that caused the error: Key: name of the query parameter Value: value specified for the query parameter WaypointNotFound This error indicates that one of the requested waypoints (start/end or via point) could not be found in the routing network. The following field mapping applies: Field ServiceError.type ServiceError.subtype ServiceError.AdditionalData Value ApplicationError"" WaypointNotFound One entry for each waypoint which could not be found: Key: waypoint[n] Value: as specified in the request (same representation) NoRouteFound This error indicates that no route could be constructed based on the input parameter. The following field mapping applies:

119 Routing API Developer's Guide 119 Field ServiceError.type ServiceError.subtype Value ApplicationError NoRouteFound ServiceError.AdditionalData - InvalidRouteId This error indicates that the route could not be reconstructed based on the given Route ID. The following field mapping applies: Field ServiceError.type ServiceError.subtype Value ApplicationError InvalidRouteId ServiceError.AdditionalData Entry 1: Key: routeid Value: Route ID that is invalid LinkIdNotFound This error indicates that a link ID passed as input parameter could not be found in the underlying map data. The following field mapping applies: Field ServiceError.type ServiceError.subtype ServiceError.AdditionalData Value ApplicationError LinkIdNotFound One entry for each link which could not be found: Key: linkid[n] Value: link ID which could not be found

120 Routing API Developer's Guide 120 PositionOffRoute This 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. The following field mapping applies: Field ServiceError.type ServiceError.subtype ServiceError.AdditionalData Value ApplicationError PositionOffRoute One entry for each link which could not be found: Key: position Value: geo coordinate of position as [lat],[long](,[alt]) HTTP Status Codes Routing API supports the standard HTTP status codes Error code 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.