Toll Cost Extension API - Heredocumentation.developer.here.com/pdf/routing_road... · Toll Cost Extension API is a really easy-to-use solution giving access to a complex mechanism

Toll Cost Extension APIDeveloper's Guide

Version 2.1

Toll Cost Extension API Developer's Guide 2► Contents

Contents

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

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

Chapter 1: Overview................................................................................................................................. 6What is the Toll Cost Extension API?.........................................................................................................7

The toll cost calculation resource.............................................................................................................. 7

The cost optimized routing resource........................................................................................................8

Why use the Toll Cost Extension API?.......................................................................................................9

Chapter 2: Quick Start........................................................................................................................11Making your first request...........................................................................................................................12

First request to the toll cost calculation resource.............................................................................. 12

First request to the cost optimized routing resource........................................................................ 14

Chapter 3: User Guide......................................................................................................................... 17Acquiring Credentials...................................................................................................................................18

Constructing a Request.............................................................................................................................. 18

Customer Integration Testing.......................................................................................................19

Key Concepts.................................................................................................................................................19

Key Concepts - Cost optimized routing resource................................................................................20

Examples.........................................................................................................................................................21

Example "toll cost calculation" request..................................................................................... 21

Example "cost optimized routing" request............................................................................... 23

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

Chapter 4: API Reference................................................................................................................. 27Resource "tollcost.json"- Input................................................................................................................ 28

Input Interface..................................................................................................................................28

Toll Cost Extension API Developer's Guide 3► Contents

Input parameter [vspec]................................................................................................................ 29

Input parameter [start_ts].............................................................................................................31

Input parameter [route]................................................................................................................. 31

Resource "tollcost.json" - Output............................................................................................................32

JSON response................................................................................................................................. 32

Response Elements......................................................................................................................... 33

Response Values.............................................................................................................................. 38

Resource "calculateroute.json"- Input....................................................................................................41

Input Interface..................................................................................................................................41

Resource "calculateroute.json" - Output............................................................................................... 42

JSON response................................................................................................................................. 42


Resource "warnings.json"- Input..............................................................................................................44

Input Interface..................................................................................................................................45

Resource "warnings.json" - Output......................................................................................................... 45

JSON response................................................................................................................................. 45


HTTP Status Codes......................................................................................................................................46

Toll Cost Extension API Developer's Guide 4► Legal Notices

Legal Notices© 2015 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.

Other product and company names mentioned herein may be trademarks or trade names of their

respective owners.

Disclaimer

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

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

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

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

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

content before acting on it.

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

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

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

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

possibility of such damages.

Toll Cost Extension API Developer's Guide 5► Document Information

Document Information

Product

Name: Toll Cost Extension API

Version: Version 2.1

Document

Name: Toll Cost Extension API Developer's Guide

Id: d3f8db7-1446200423

Status: FINAL

Date: 2015-Oct-30, 10:20 (GMT)

Toll Cost Extension API Developer's Guide 6► Overview

Chapter

1

OverviewTopics:

• What is the Toll Cost ExtensionAPI?

• The toll cost calculation resource

• The cost optimized routing resource

• Why use the Toll Cost ExtensionAPI?

This document introduces the Toll Cost Extension API


What is the Toll Cost Extension API?The HERE Toll Cost Extension API (TCE) is a service that provides 2 features related to toll cost:

• A calculation of the toll costs for a given route based on a defined vehicle profile

• A cost optimized routing based on toll and vehicle costs

Available as a REST web service, TCE service relies on the HERE Toll dataset and on the HERE Routing

API.

The toll cost calculation resourceThe toll cost calculation resource input is composed of 2 main elements:

• The route

◦ Input of road segments coming from the HERE Enterprise Routing Service or from the Route

Match Extension service

◦ Optionally with date/time info

• The vehicle specifications

◦ As the toll systems in place in the different countries are based on vehicle attributes, these

must be provided to clearly define the profile of the vehicle (weight, height, number of axles,

emission type…) and to match the applicable toll costs

The toll cost calculation resource output gives toll costs by country, in which are detailed:

• The administrative area admission costs, which are all usage fee required for all routes within the

country

• The road sections costs, which are all usage fee required for routes as defined by the toll

operator

For these 2 kinds of costs, all the links ids where applicable are provided, as well as all the related

conditional information (pass availability, currency, methods of payment, discount options…).


Figure 1: Typical Application Control Flow for Toll cost calculation resource

The cost optimized routing resourceThe cost optimized routing resource input is composed of 3 main elements:

• The router parameters

◦ Parameters used to specify which attributes must be returned with the response. These are

the parameters compliant with the HERE Routing API.

• The global costs

◦ The driver cost (per hour driven), the vehicle cost (per kilometer driven) and the currency

used to make the cost calculation

• The toll cost calculation parameters

◦ These are the parameters which must be specified when calling the "toll cost calculation"

resource from Toll Cost Extension API

The cost optimized routing resource output gives the cheapest route found based on the costs

provided as parameters. The response includes:

• The router response, containing all the attributes specified in the request

• The costs, showing the overall costs and the detailed costs for driver, vehicle and toll cost usage


• The detailed toll costs, if specified in the request delivers the detailed toll costs encountered

along the returned route

All the costs are given in the specified currency provided as a parameter (converted if needed)

Figure 2: Typical Application Control Flow for Cost optimized routing resource

Why use the Toll Cost Extension API?Toll Cost Extension API is a really easy-to-use solution giving access to a complex mechanism of toll

cost calculation and cost optimized routing:

• Based on continuously updated high quality HERE Toll Cost map data, field verified and sourced

from the toll operators

• Provides seamless toll cost calculation across country borders

• Enables toll cost calculation for multiple countries through one single interface

• Helps saving money with calculating cost optimized routes

• Easy to plug into existing solutions due to support for web standards

• High performance and capacity to calculate large amounts of requests

• Applicable for both commercial and consumer vehicles

The most typical use-cases are, among others:

• Fleet management


◦ Route planning while taking into account toll costs associated with vehicles taking particular

roads

• Cost management

◦ Controlling costs associated with fleet activities while analyzing incoming receipts against

calculated costs for particular trips

• Trip planning

◦ Consumers who are planning their holiday trips can get precise cost calculation

Toll Cost Extension API Developer's Guide 11► Quick Start

Chapter

2

Quick StartTopics:

• Making your first request

• First request to the toll costcalculation resource

• First request to the cost optimizedrouting resource

This article helps you start using the Toll Cost Extension API.


Making your first requestSometimes the easiest way to start using new software is to run simple working examples.

An authentication mechanism is set up on this service, and requires to provide a set of credentials

called app_id and app_code along with every request to TCE. See Acquiring Credentials on page

18 for more information.

The examples in this guide use the Customer Integration Testing (CIT) environment. This environment

allows you to test your software. For production please use the production environment. See

Constructing a Request on page 18 for the base URLs of both environments.

Note that most example URLs in this guide are broken up into multiple lines for better readability.

Remove these line breaks and spaces when copying and pasting the examples to make sure URLs are

still well formed.

Prerequisites

The only thing you need to start using the Toll Cost Extension API is an HTTP client. Choose any

HTTP client application you are familiar with. A command line tool like curl will do the job, as will any

modern web browser.

First request to the toll cost calculation resource

Calculate Route

The Toll Cost Extension expects the route definition as list of link IDs. Such a route can be

constructed by the Enterprise Router (planning use case) or by the Route Match Extension (analysis

use case). Route calculation example:

https://route.st.nlp.nokia.com/routing/6.2/calculateroute.json?&waypoint0=48.42732%2C2.5409&waypoint1=51.7094%2C-3.35138&mode0=fastest;car&legattributes=all&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

{ "Response" : { "MetaInfo" : { ...


AdditionalData : [ ... { "value" : "2015Q4" , "key" : "Map0" }, ... ] }, "Route" : [ { ... "Leg" : [ { ... "Link" : [ { ... "LinkId" : "+748873330", ... }, { ... "LinkId" : "+68614309", ... }, { ... "LinkId" : "-737272743", ... } ... ] } ], ... } ] }}

Request to TCE API

http://tce.cit.api.here.com/1/tollcost.json?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&start_ts=2015-06-09T16:26:00&vspec=3;0;0;2;0;0;6;350;0;10000;10000;0;0;0;1;8;0;0&route=748873330,60;68614309,50;17357322,40;748938713,30;76719821,20;17357323,0

{ "errors":[], "warnings":[], "countries":[ { "name":"FRA", "roadSectionsCosts":[ { "linksIds":[748938713,76719821], "conditions":[ { "time":null, "pass":null, "amount":7.4, "currency":"EUR", "methodsOfPayment":151,


"daylightHours":2, "discountAvailable":0, "tollSystemsIds":"5016" } ], "tollStructures":[ { "linkId1":748938713, "linkId2":76719821, "name":"LE TOURNEAU", "lngCode":"FRE", "latitude":47.9931, "longitude":2.67762 } ] } ], "adminAdmissionCosts":null, "usageFeeRequiredLinks": { "linksIds":[748873330,68614309], "conditions":null, "tollStructures":[ { "linkId1":748873330, "linkId2":68614309, "name":"FLEURY-EN-BIERE", "lngCode":"FRE", "latitude":48.42819, "longitude":2.5403 } ] }, "tollSystemsNames":[ { "id":5016, "names":[ { "languageCode":"ENG","name":"APRR" } ] } ] } ], "onError":false}

First request to the cost optimized routing resource

Router parameter

A request to the cost optimized routing resource is basically an extended request to the HERE

Routing API. Therefore, it must contain all the necessary and wanted parameters from the Routing

API as available here.

https://developer.here.com/rest-apis/documentation/routing


Request to TCE API

http://tce.cit.api.here.com/2/calculateroute.json?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&release=2015Q1&vspec=2;0;0;2;0;0;5;167;0;1739;1739;0;0;0;2;4;0;0&driver_cost=1&vehicle_cost=10&currency=EUR&verbosemode=0&waypoint0=geo!49.33729606975952,0.5986232869327068&waypoint1=geo!49.493527937780975,0.10129541603788539&metricsystem=metric&maneuverattributes=none&routeattributes=gr&mode=shortest;car&jsonattributes=41&combinechange=true&linkattributes=none,rt,fl&legattributes=none,li,sm&language=en-us&alternatives=3

{ response: { metaInfo: { timestamp: "2015-09-17T15:45:29Z", mapVersion: "8.30.59.159", moduleVersion: "7.2.60.0-1202", interfaceVersion: "2.6.15" }, route: [...], language: "en-us" }, errors: [ ], warnings: [ ], onError: false, costs: { totalCost: 558.14, currency: "EUR", details: { driverCost: "8.85", vehicleCost: "546.79", tollCost: "2.5" } }, detailedTollCosts: { countries: [ { name: "FRA", roadSectionsCosts: [ { linksIds: [ 746822847, 746822848 ], conditions: [ { time: null, pass: null, currency: "EUR", methodsOfPayment: 151, daylightHours: 2, discountAvailable: 0, tollSystemsIds: "5061", amount: 2.5


} ], tollStructures: [ { linkId1: 746822847, linkId2: 746822848, name: "PONT DE TANCARVILLE S/N", lngCode: "FRE", latitude: 49.47689, longitude: 0.45998 } ] } ], adminAdmissionCosts: null, usageFeeRequiredLinks: { linksIds: [ 60762966, 724552383, 846814091, 846814092, 772720381, 819480117, 819480118, 545541436, 545541437, 71500600, 799331506 ], conditions: null, tollStructures: [ ] }, tollSystemsNames: [ { id: 5061, names: [ { languageCode: "ENG", name: "CCI DU HAVRE" } ] } ] } ] }}

Toll Cost Extension API Developer's Guide 17► User Guide

Chapter

3

User GuideTopics:

• Acquiring Credentials

• Constructing a Request

• Key Concepts

• Key Concepts - Cost optimizedrouting resource

• Examples

• Service Support

The articles in this section provide a guide to using the Toll Cost

Extension API:

• explains key concepts

• provides examples


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

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

This document uses the placeholder text {YOUR_APP_CODE} and {YOUR_APP_ID} as placeholders

for access and authorization credentials. Please replace these placeholders with your own unique

application-specific credentials to access the API resources.

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

more details.

If you wish to explore the API, use the API Explorer at https://developer.here.com/api-explorer.

Constructing a Request

Toll cost calculation resource

A request to the Toll Cost Extension API toll cost calculation includes the basic elements shown in the

following table and, in addition, it may contain resource-specific parameters or data.

Table 1: Basic request elements

Element Value/Example Description

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

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

Production environment only

CIT environment: see Customer

Integration Testing on page 19

Path /1/

Resource tollcost.json GET/POST, specify request details via

query parameters

Application Code &app_code={YOUR_APP_CODE} Substitute your own unique

app_code

Application Id &app_id={YOUR_APP_ID} Substitute your own unique app_id

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

https://developer.here.com/api-explorer


Cost optimized routing resource

A request to the Toll Cost Extension API cost optimized routing includes the basic elements shown in

the following table and, in addition, it may contain resource-specific parameters or data.

Table 2: Basic request elements

Element Value/Example Description

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

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

Production environment only

CIT environment: see Customer

Integration Testing on page 19

Path /2/

Resource calculateroute.json GET/POST, specify request details via

query parameters

Application Code &app_code={YOUR_APP_CODE} Substitute your own unique

app_code

Application Id &app_id={YOUR_APP_ID} Substitute your own unique app_id

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

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

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

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

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

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

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

testing in general.

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

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

26.

The CIT environment is not intended for general production use.

Key ConceptsThis section provides insights into the key concepts used throughout the Toll Cost Extension API.


How to Obtain a Route?

The route is provided as sequence of Permanent Link IDs. A route can be constructed by the HERE

Routing Web service or the HERE Route Match Web service (RME). The route link IDs can also be

obtained through the HERE Reverse Geocoding Web service, from processing HERE Core Map data or

through any other means.

Vehicle specifications

Toll costs are always given for specific vehicles: the usage fee required to use a specific road network

or go through a toll booth will be different whether the vehicle is a motorbike or a truck. Therefore

when computing the toll costs of a given route, TCE needs to know as precisely as possible all the

specifications of the vehicle to be able to choose between the different fees the one(s) which are

the closest. Hence when issuing a request to TCE, the client has to provide the specifications of the

vehicle as a string, summing up different attributes like:

• Category: motorcycle, truck, auto...

• Trailer type: none, trailer, caravan

• Vehicle number of axles

• ....

Types of costs

The due costs for road usage can be divided into two categories:

• Road section costs: fees that the driver must pay to use a specific road, section of road or to

through a specific toll booth

• Administrative area admission costs: fees that the driver must pay in order to gain access to the

road network of a specific area

These two categories are returned separately in TCE response to a request.

Key Concepts - Cost optimized routing resourceThis section provides insights into the key concepts used throughout the Toll Cost Extension API cost

optimized routing resource.


How to build a request?

A request for calculating a cost optimized route is similar to a request to the HERE Routing API.

In addition, almost all the parameters for a toll cost calculation need to be provided, in order to

calculate the toll cost for the route. At last, the global costs (driver, vehicle) and currency need to be

provided as well.

Parameter costs

2 costs must be provided as parameters in order to be able to calculate the best cost optimized

route

• Driver cost: represents the cost of driving per hour in the provided currency. For example the

hourly cost of a truck driver.

• Vehicle cost: represents the cost of usage of the vehicle per kilometer in the provided currency.

For example the usage cost of a truck.

ExamplesThis section provides examples of requests along with the responding results.

Example "toll cost calculation" request

User Story

The user wants to retrieve the toll costs for a route knowing its link ids (computed by the Enterprise

Router for instance) for a truck without trailer.

Request Summary

The following list summarizes the elements required to create a request matching the user story and

shows, in square brackets, how those elements are used in the request example below. Note that the

request example also uses the authentication parameters.

Resource: tollcost

Parameters: release [2014Q4], map release quarter (can be retrieved from the HERE

Enterprise Routing Service response meta data). Optional, default = latest

available.


start_ts [2015-06-01T08:00:00 or now], start date of the route

vspec [3;0;0;2;0;0;6;350;0;10000;10000;0;0;0;1;8;0;0], string

representation of the vehicle specifications

route [748873330,50;68614309,40;17357322,30;748938713,20;

76719821,10;17357323,0], link ids of the route, each with the number of

seconds to go until to the destination. If no start_ts is specified, then the

route is just a list of link ids.

Request

http://tce.cit.api.here.com/1/tollcost.json?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&release=2015Q4&start_ts=2015-06-01T08:00:00&vspec=3;0;0;2;0;0;6;350;0;10000;10000;0;0;0;1;8;0;0&route=748873330,50;68614309,40;17357322,30;748938713,20;76719821,10;17357323,0

Response

{ "errors":[], "warnings":[], "countries":[ { "name":"FRA", "roadSectionsCosts":[ { "linksIds":[748938713,76719821], "conditions":[ { "time":null, "pass":null, "amount":7.4, "currency":"EUR", "methodsOfPayment":151, "daylightHours":2, "discountAvailable":0, "tollSystemsIds":"5016" } ], "tollStructures":[ { "linkId1":748938713, "linkId2":76719821, "name":"LE TOURNEAU", "lngCode":"FRE", "latitude":47.9931, "longitude":2.67762 } ] } ], "adminAdmissionCosts":null,


"usageFeeRequiredLinks": { "linksIds":[748873330,68614309], "conditions":null, "tollStructures":[ { "linkId1":748873330, "linkId2":68614309, "name":"FLEURY-EN-BIERE", "lngCode":"FRE", "latitude":48.42819, "longitude":2.5403 } ] }, "tollSystemsNames":[ { "id":5016, "names":[ { "languageCode":"ENG","name":"APRR" } ] } ] } ], "onError":false}

Example "cost optimized routing" request

User Story

The user, a logistic company, wants to retrieve the cheapest route between Paris and Le Havre in

France, for a 40 tons truck.

Request Summary

The following list summarizes the elements required to create a request matching the user story and

shows, in square brackets, how those elements are used in the request example below. Note that the

request example also uses the authentication parameters.

Resource: calculateroute

Parameters: driver_cost [15], cost per hour of the truck driver

vehicle_cost [0.7], usage cost of the truck per kilometer

currency [EUR], the currency to use to display the costs

detail [1], flag indicating that the detailed toll cost for the route should be

included in the response


start_ts [2015-09-18T16:00:00], start datetime of the route

vspec [3;2;1;3;2;0;5;400;400;12000;40000;0;0;0;1;6;1;0], string

representation of the vehicle specifications

(router parameters) waypoint0 [geo!48.85450344626631,2.3434416413849135], first

waypoint of the route, here Paris the starting point

waypoint1 [geo!49.49255240285734,0.13279463294355764], last

waypoint of the route, here Le Havre the final point

metricsystem [metric], measurement system used in instruction text

maneuverattributes [none], defines which attributes are included in the

response as part of the data representation of the route maneuvers, here

none

routeattributes [gr], defines which attributes are included in the

response as part of the data representation of the route, here groups

mode [shortest;truck], routing mode indicating shortest (will not be the

only one calculated for optimization) and vehicle type

jsonattributes [41], flag to control JSON output

combinechange [true], enables the change maneuver in the route response,

which indicates a public transit line change

linkattributes [none,rt,fl], defines which attributes are included in

the response as part of the data representation of the route links. Here the

usage of "none" allows to remove all the defaults attributes to select only the

selected (rt = remainTime and fl = flags)

legattributes [none,li,sm], defines which attributes are included in

the response as part of the data representation of the route legs. Here the

usage of "none" allows to remove all the defaults attributes to select only the

selected (li = links and sm = summary)

language [en-us], the language to use for textual information

Request

http://tce.cit.api.here.com/2/calculateroute.json?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}&driver_cost=15


&vehicle_cost=0.7&currency=EUR&detail=1&start_ts=2015-09-18T16:00:00&vspec=3;2;1;3;2;0;5;400;400;12000;40000;0;0;0;1;6;1;0&waypoint0=geo!48.85450344626631,2.3434416413849135&waypoint1=geo!49.49255240285734,0.13279463294355764&metricsystem=metric&maneuverattributes=none&routeattributes=gr&mode=shortest;truck&jsonattributes=41&combinechange=true&linkattributes=none,rt,fl&legattributes=none,li,sm&language=en-us

Response

{ response: { metaInfo: { timestamp: "2015-09-18T07:57:13Z", mapVersion: "8.30.59.159", moduleVersion: "7.2.60.0-1202", interfaceVersion: "2.6.15" }, route: [ { waypoint: [...], mode: {...}, leg: [...], summary: {...} } ], language: "en-us" }, errors: [ ], warnings: [ ], onError: false, costs: { totalCost: 210.87, currency: "EUR", details: { driverCost: "39.62", vehicleCost: "136.55", tollCost: "34.7" } }, detailedTollCosts: { countries: [ { name: "FRA", roadSectionsCosts: [ {...}, ... ], adminAdmissionCosts: null, usageFeeRequiredLinks: {...}, tollSystemsNames: [...] } ] }}


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

Technical Customer Support.

Toll Cost Extension API Developer's Guide 27► API Reference

Chapter

4

API ReferenceTopics:

• Resource "tollcost.json"- Input

• Resource "tollcost.json" - Output

• Resource "calculateroute.json"-Input

• Resource "calculateroute.json" -Output

• Resource "warnings.json"- Input

• Resource "warnings.json" - Output

• HTTP Status Codes

This section provides descriptions of the resources, parameters,

return types and error codes of the HERE Toll Cost Extension API.


Resource "tollcost.json"- InputAll parameter values including letters outside A-Z and a-z must be first UTF-8 encoded and then URL

encoded. Every URL unsafe character should be URL encoded and checked.

Responses can be extended by new elements or attributes without prior announcement, and without

a new major version. Hence, applications that parse the responses should not assume fixed response

structures, but should deal with additional, unexpected elements and attributes.

Input Interface

Resource URI

/tollcost

Resource Parameters

Parameter Type Description

release String Map release quarter, e.g. 2015Q1 to which the route link IDs belong. Note that

while the IDs are permanent, there can be changes between map releases, e.g. if

a link got split into two links. The HERE Routing service and the HERE Route Match

service (RME) return their current map release in the response. This parameter is

optional, default = latest available map.

app_id String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string

used for the authentication of the client application. See Acquiring Credentials on

page 18.

app_code String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string


page 18.

vspec String Semi-column separated string containing all the vehicle specifications. See

detailed description of this parameter

start_ts String Start timestamp of the route. See detailed description of this parameter

route String Detailed information about the route. See detailed description of this parameter

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


Input parameter [vspec]

Format

List of semi-column ";" separated values

Description

Position in string Parameter Description

1 Category Integer, Enum [1,2,3,4,5,6,7,8,9,10,11,12]

• WORLD : [1=Motorcycle, 2=Auto, 3=Truck, 4=Motor home, 5=Minibus,

6=Bus]

• EU ONLY : [7=Motorcycle Sidecar, 8=Tricycle, 9=Delivery Truck]

• US ONLY : [10=Snowmobile, 11=Pick-up, 12=Tractor]

2 Trailer type Integer, Enum [0,1,2]

• [0=None, 1=Caravan, 2=Trailer]

3 Number of trailers Integer, Enum [0,1,2,3]

• if trailer type (param number 2) is 0 : must be 0

• else : must be in [1=Truck with one more trailers, 2= Truck with two or more

trailers, 3=Truck with three or more trailers]

4 Number of axles

vehicle

Integer, must be > 0

5 Number of axles

trailer

Integer, 0 or more


• else : must be > 0

6 Hybrid Integer, Enum [0,1]

• set to 1 if the vehicle is partly running on electricity

• set to 0 otherwise

7 Emission type Integer, Enum [1,2,3,4,5,6,7,8]

• [1=EURO I, 2=EURO II, 3=EURO III, 4=EURO IV, 5=EURO V, 6=EURO VI, 7=EURO

EEV, 8=Electric Vehicles]

8 Vehicle height Integer, must be > 0

• USA : Inches with precision zero

• REST OF THE WORLD : Centimeters with precision zero


Position in string Parameter Description

9 Trailer height Integer, 0 or more


• else : must be > 0

• USA : Inches with precision zero

• REST OF THE WORLD : Centimeters with precision zero

10 Vehicle weight Integer, must be > 0

• USA : Pounds (lbs) with precision zero

• REST OF THE WORLD : Kilograms (KG) with precision zero

11 Total weight Integer, total weight of the vehicle including trailer(s) or caravan. Must be > 0

• USA : Pounds (lbs) with precision zero

• REST OF THE WORLD : Kilograms (KG) with precision zero

12 Disabled equipped Integer, Enum [0,1]

• set to 1 if the vehicle is specially equipped for transporting disabled people


13 Minimal pollution Integer, Enum [0,1]

• set to 1 if the vehicle is considered to cause minimal pollution


14 HOV Integer, Enum [0,1]

• set to 1 if the vehicle is considered as an HOV (High Occupancy Vehicle)


15 Number of

passengers

Integer, must be > 0

16 Number of tires Integer, must be > 0

17 Commercial Integer, Enum [0,1]

• set to 1 if the vehicle is designed for commercial use


18 Hazardous type Integer, Enum [0,1,2]

• [0=None, 1=Explosives, 2=Any hazardous material]

Examples

Passenger car: vspec=2;0;0;2;0;0;5;167;0;1739;1739;0;0;0;2;4;0;0

7.5 ton truck: vspec=3;0;0;2;0;0;5;340;0;7500;7500;0;0;0;1;4;1;0


38 ton truck with trailer: vspec=3;2;1;2;3;0;5;400;400;24000;38000;0;0;0;1;6;1;0

Input parameter [start_ts]

Format

YYYY + '-' + MM + '-' + DD + 'T' + hh + ':' + mm + ':' + ss

Description

Parameter Description

YYYY Four-digit numeral that represents the year.

MM Two-digit numeral that represents the month

DD Two-digit numeral that represents the day

hh Two-digit numeral that represents the hour. The value 24 is permitted if the minutes and seconds

represented are zero, and the dateTime value so represented is the first instant of the following

day (the hour property of a dateTime object in the value space cannot have a value greater than 23)

mm Two-digit numeral that represents the minute

ss Two-integer-digit numeral that represents the whole seconds

Input parameter [route]

Format

List of route details objects, as semicolon separated list. If start_ts is given, then each route detail

is a comma separated struct of link id,seconds left to destination. Otherwise, each route detail is only

a link id. Link ids are specified as a negative number, if the link is driven towards reference node.

Example

For a route going through following link ids: 554987845, 1213212 and -9998745, the query string

must look like:

route=554987845,90;1213212,60;-9998745,0 or route=554987845;1213212;-9998745(without time).


Resource "tollcost.json" - OutputThe response is provided in JSON format. Below are detailed the elements of the response as well as

the literal values.

JSON response

{ "countries": [ { "name": ..., "roadSectionsCosts": [ { "linksIds": [ ..., ..., ... ], "conditions": [ { "time": ..., "pass": ..., "amount": ..., "currency": ..., "methodsOfPayment": ..., "daylightHours": ..., "discountAvailable": ..., "tollSystemsIds": ... }, ... ] "tollStructures":[ { "linkId1": ..., "linkId2": ..., "name": ..., "lngCode": ..., "latitude": ..., "longitude": ... } ] }, ... ], "adminAdmissionCosts": { "linksIds": [ ..., ..., ... ], "name": ..., "conditions": [ { "time": ..., "pass": ..., "amount": ..., "currency": ..., "methodsOfPayment": ...,


"daylightHours": ..., "discountAvailable": ..., "tollSystemsIds": ... }, ... ] }, "usageFeeRequiredLinks": { "linksIds": [ ..., ..., ... ], "conditions": null }, "tollSystemsNames": [ { "id": ..., "names": [ { "languageCode": ..., "name": ... }, ... ] }, ... ] }, ... ], "errors": [ ..., ..., ... ], "warnings": [ ..., ..., ... ], "onError": ...}

Response Elements

Element 'countries'

Description

Array of objects, one object per country.

Properties


name 3 characters iso-country-code



roadSectionCosts See detailed description of this element

adminAdmissionCosts See detailed description of this element

usageFeeRequiredLinks See detailed description of this element

tollSystemsNames See detailed description of this element

Element 'roadSectionCosts'

Description

Array of objects, one object per road section cost where a toll is applicable.

Properties


linksIds array of links ids (integers)

conditions See detailed description of this element

Element 'adminAdmissionCosts'

Description

Object representing the costs related to the current administrative area (country).

Properties


linksIds array of links ids (strings)

name name of the administrative area (string)

conditions See detailed description of this element


Element 'usageFeeRequiredLinks'

Description

Object representing the links where a usage fee is required, but without detailed information.

Properties


linksIds array of links ids (strings)

conditions Always null, generated for parsing compatibility

Element 'tollSystemsNames'

Description

Array of objects, one object per toll system encountered along the route.

Properties


id toll system id (integer)

names See detailed description of this element

Element 'conditions'

Description

Array of objects, one per toll condition. One condition represents the toll costs and conditions

applied to the related set of links.

Properties


time string value, See detailed description of this value



pass string value, See detailed description of this value

amount float value, cost to be paid for this toll

currency string value, 3-iso-code currency

methodsOfPayment string value, See detailed description of this value

daylightHours integer value, See detailed description of this value

discountAvailable integer value, See detailed description of this value

tollSystemsIds string value, See detailed description of this value

Element 'tollStructures'

Description

Array of objects, one per toll structure. One toll structure represents a physical toll booth or similar.

Properties


linkId1 integer value, the link id before entering the toll structure

linkId2 integer value, the link id that leaves the toll structure

name string value, name of this toll structure

lngCode string value, 3 letter language code of the name

latitude floating point number, WGS84 degree latitude of the toll structure point

longitude floating point number, WGS84 degree longitude of the toll structure point

Element 'names'

Description

Array of objects, one per name / language for the parent toll system.


Properties


languageCode ISO-3 code of the language in which the name is written

name name of the toll system

Element 'errors'

Description

Array of strings, one per error encountered during the process or the validation of input request

parameters. If this array is empty, the “onError” element value is false; otherwise, the “onError”

element value is true.

Element 'on-error'

Description

String value, indicating whether an error (or several) has happened during the process or the

validation of input request parameters. If the “errors” array is empty, this element value is false;

otherwise, this element value is true.

Element 'warnings'

Description

Array of objects, one per warning generated by the service when processing the request.

Properties


category Numeric identifier of the warning. The meaning of the associated warning can be retrieved by using

the "warnings.json" resource.

context String contextual information providing details about the warning. Can be null if no contextual

information is associated to this warning.


Response Values

Value 'time'Comma separated list of Date/Time modifiers to indicate specific time periods when the toll cost

applies.

One entry contains following colon separated values:

• DATETIME_TYPE:High level indication of the period for which the date time restriction is valid.

The value of this type effects the interpretation of START_DATE/END_DATE

◦ C - Day of Month, Example: 00010000 - f.e. 1 January, 1 February,..., 1 December

◦ D - Day of Week of Month, Example: 00010002 - 2nd Sunday of each month, 00020001 - 1st

Monday of each month, 00070002 - 2nd Saturday of each month, 00060005 - 5th Friday of

each month

◦ E - Day of Week of Year, Example: 00030020 - Tuesday of week 20, 00050052 - Thursday of

week

◦ F - Week of Month, Example: 00020000 - 2nd week of each month

◦ H - Month of Year, Example: 00010000 - January, 00070000 - July

◦ I - Day of Month of Year, Example: 00150001 - 15 January of each year, 00300004 - 30 April

of each year

◦ 1 - Day of week starting with Sunday, Example: X XX - Sunday and Friday and Saturday,

XXXXXXX - all weekdays

◦ 2 - External date, Example: Easter

◦ A - Date Ranges, Example: 20131119 - 19th of november year 2013

▪ For Date Time Type = A-I, the Start Date represents the start of the range and the End

Date represents the end of the range.

▪ For Date Time Type = 1, Start Date identifies the day(s) of the week. End Date is not

published for Date Time Type = 1.

▪ For Date Time Type = 2, Start Date identifies the name of the external date. The only

currently existing situation is "Easter". End Date is not published for Date Time Type = 2.

• FROM_END:This attribute allows time to be specified 'from the end' of a standard time period

such as month and year


• EXCLUDE_DATE:Flag that indicates if the specified data (in Date Time Type) represents an

excluded date. Example, all year except 30 April is modelled Exclude Date = Y, with Start Date =

30 April

• START_DATE:Identifies the start dates of the Date/Time for Date Time Type = A-I. Identifies the

days of the week for Date Time Type = 1 and the external date for Date Time Type = 2

• END_DATE:Identifies the end date of the Date/Time for Date Time Types = A-I

• START_TIME:Identifies the start time for the time period in which the Date Time restriction is in

effect. Time in format HHMM, where a 24 hour clock is used. Range 0000...2400. Example: 1130

means 11:30 and 2115 means 21:15

• END_TIME:Identifies the end time for the time period in which the Date Time restriction is in

effect. Time in format HHMM, where a 24 hour clock is used. Range 0000...2400. Example: 1130

means 11:30 and 2115 means 21:15 s

Value 'pass'Pass information applicable for this toll cost. The information are represented by a concatenate

string, as described below. The string is always prefixed by a unique id (integer) followed by the ";"

character.

After this prefix, the string is the concatenation of 3 elements, separated by the ":" character:

• The bit sum of validity information (see description below)

• The number of days the pass is valid for

• The number of months the pass is valid for

The bit sum of validity information is composed of these values:

• 1: the pass is valid for a year (annual)

• 2: the pass is valid for a year plus the month prior to the specified year and the month following

the specified year (Dec-Jan)

• 4: the pass is valid for Senior people only

Several passes can be applied for this toll cost, if it is the case the different passes information are

separated by the "," character.

Value 'methodsOfPayment'Methods of payment applicable to this toll cost, represented as a bit sum. The values are:

• 1: Cash


• 2: Bank card

• 4: Credit card

• 8: Pass / subscription

• 16: Transponder

• 32: Video toll charge

• 64: Exact cash

• 128: Travel card

Value 'daylightHours'Integer value:

• 0: toll cost applicable during non-daylight hours

• 1: toll cost applicable during daylight hours

• 2: information not available

Value 'discountAvailable'Integer value:

• 0: no discount available

• 1: discount available under certain circumstance

Value 'tollSystemsIds'Toll system(s) the links ids of the condition belong to. The possible values / forms are:

• null: no toll system

◦ Example:

▪ "tollSystemsIds": null

• "{toll system id}": the toll system id the current links ids are belonging to

◦ Example:

▪ "tollSystemsIds": "509"

• "{toll system id},{toll system id}": the first link id of the current condition belongs to the toll

system id which is specified before the comma, and the last link id belongs to the toll system id

which is specified after the comma

◦ Example:


▪ "tollSystemsIds": "509,510"

Resource "calculateroute.json"- InputAll parameter values including letters outside A-Z and a-z must be first UTF-8 encoded and then URL

encoded. Every URL unsafe character should be URL encoded.

Input Interface

Resource URI

/calculateroute

Resource Parameters

Parameter Type Description

app_id String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string


page 18.

app_code String Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string


page 18.

vspec String Semi-column separated string containing all the vehicle specifications. See

detailed description of this parameter

start_ts String Start timestamp of the route. See detailed description of this parameter

driver_cost Float Cost per hour of driving

vehicle_cost Float Usage cost of the vehicle per kilometer driven

currency String 3 characters (ISO 4217) currency code in which the costs will be given. See here for

more details.

* * HERE Routing API parameters, at least the mandatory ones to make a valid request

to the router. HERE Routing API documentation is available here.

http://www.xe.com/iso4217.php



Resource "calculateroute.json" - OutputThe response is provided in JSON format. Below are detailed the elements of the response as well as

the literal values.

JSON response{ "response": {...}, "errors": [ ..., ..., ... ], "warnings": [ ..., ..., ... ], "onError": ..., "costs": { "totalCost": ..., "currency": ..., "details": { "driverCost": ..., "vehicleCost": ..., "tollCost": ... } }, "detailedTollCosts": {...}}

Response Elements

Element 'response'

Description

Router JSON response describing the cheapest route found.

Properties

Attribute Description

* router response in JSON format. See here for more details



Element 'errors'

Description

Array of strings, one per error encountered during the process or the validation of input request

parameters. If this array is empty, the “onError” element value is false; otherwise, the “onError”

element value is true.

Element 'warnings'

Description

Array of objects, one per warning generated by the service when processing the request.

Properties


category Numeric identifier of the warning. The meaning of the associated warning can be retrieved by using

the "warnings.json" resource.

context String contextual information providing details about the warning. Can be null if no contextual

information is associated to this warning.

Element 'on-error'

Description

String value, indicating whether an error (or several) has happened during the process or the

validation of input request parameters. If the “errors” array is empty, this element value is false;

otherwise, this element value is true.

Element 'costs'

Description

Costs for this route


Properties


totalCost Total cost (driver + vehicle + tolls) for this route

currency ISO 4217 currency code in which costs are given

details See detailed description of this element

Element 'details'

Description

Object representing the different costs for the response route.

Properties


driverCost Total driver cost calculated from the number of hours driven, given in the specified currency

vehicleCost Total vehicle cost calculated from the number of kilometers driven, given in the specified currency

tollCost Total toll costs encountered along the route, given in the specified currency

Element 'detailedTollCosts'

Description

Detailed toll costs encountered for this route

Properties


* toll cost details response in JSON format. See detailed description of this element

Resource "warnings.json"- InputAll parameter values including letters outside A-Z and a-z must be first UTF-8 encoded and then URL

encoded. Every URL unsafe character should be URL encoded.


Input Interface

Resource URI

/2/warnings.json

Resource Parameters

None

Resource "warnings.json" - OutputThe response is provided in JSON format. Below are detailed the elements of the response as well as

the literal values.

JSON response[ { "code": ..., "message": ... }, { "code": ..., "message": ... }, ...]

Response Elements

Description

Array of JSON objects representing all warning codes and their associated message

Properties


code The numeric identifier of the warning

message The string message associated with the warning code


HTTP Status CodesToll Cost Extension API supports the standard HTTP status codes

Error code Description

200 OK Indicates success, but may also be returned when an invalid resource name and/or an invalid

parameter combination has been used in the request.

400 Bad request Invalid parameter value in the request.

401 Unauthorized Invalid authentication.

403 Forbidden Incorrect app_code or app_id in the request. See Acquiring Credentials on page 18 for

more information.

404 Not found Resource not found.

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

or the resource is currently disabled.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4

Documents

Toll Cost Extension API - Heredocumentation.developer.here.com/pdf/routing_road... · Toll Cost Extension API is a really easy-to-use solution giving access to a complex mechanism