Upload
others
View
5
Download
0
Embed Size (px)
Citation preview
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
Response Elements......................................................................................................................... 42
Resource "warnings.json"- Input..............................................................................................................44
Input Interface..................................................................................................................................45
Resource "warnings.json" - Output......................................................................................................... 45
JSON response................................................................................................................................. 45
Response Elements......................................................................................................................... 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
Toll Cost Extension API Developer's Guide 7► Overview
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…).
Toll Cost Extension API Developer's Guide 8► Overview
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
Toll Cost Extension API Developer's Guide 9► Overview
• 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
Toll Cost Extension API Developer's Guide 10► Overview
◦ 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.
Toll Cost Extension API Developer's Guide 12► Quick Start
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" : { ...
Toll Cost Extension API Developer's Guide 13► Quick Start
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,
Toll Cost Extension API Developer's Guide 14► Quick Start
"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.
Toll Cost Extension API Developer's Guide 15► Quick Start
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¤cy=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
Toll Cost Extension API Developer's Guide 16► Quick Start
} ], 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
Toll Cost Extension API Developer's Guide 18► User Guide
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
Toll Cost Extension API Developer's Guide 19► User Guide
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.
Toll Cost Extension API Developer's Guide 20► User Guide
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.
Toll Cost Extension API Developer's Guide 21► User Guide
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.
Toll Cost Extension API Developer's Guide 22► User Guide
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,
Toll Cost Extension API Developer's Guide 23► User Guide
"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
Toll Cost Extension API Developer's Guide 24► User Guide
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
Toll Cost Extension API Developer's Guide 25► User Guide
&vehicle_cost=0.7¤cy=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: [...] } ] }}
Toll Cost Extension API Developer's Guide 26► User Guide
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.
Toll Cost Extension API Developer's Guide 28► API Reference
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
used for the authentication of the client application. See Acquiring Credentials on
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.
Toll Cost Extension API Developer's Guide 29► API Reference
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
• if trailer type (param number 2) is 0 : must be 0
• 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
Toll Cost Extension API Developer's Guide 30► API Reference
Position in string Parameter Description
9 Trailer height Integer, 0 or more
• if trailer type (param number 2) is 0 : must be 0
• 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
• set to 0 otherwise
13 Minimal pollution Integer, Enum [0,1]
• set to 1 if the vehicle is considered to cause minimal pollution
• set to 0 otherwise
14 HOV Integer, Enum [0,1]
• set to 1 if the vehicle is considered as an HOV (High Occupancy Vehicle)
• set to 0 otherwise
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
• set to 0 otherwise
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
Toll Cost Extension API Developer's Guide 31► API Reference
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).
Toll Cost Extension API Developer's Guide 32► API Reference
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": ...,
Toll Cost Extension API Developer's Guide 33► API Reference
"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
Parameter Description
name 3 characters iso-country-code
Toll Cost Extension API Developer's Guide 34► API Reference
Parameter Description
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
Parameter Description
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
Parameter Description
linksIds array of links ids (strings)
name name of the administrative area (string)
conditions See detailed description of this element
Toll Cost Extension API Developer's Guide 35► API Reference
Element 'usageFeeRequiredLinks'
Description
Object representing the links where a usage fee is required, but without detailed information.
Properties
Parameter Description
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
Parameter Description
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
Parameter Description
time string value, See detailed description of this value
Toll Cost Extension API Developer's Guide 36► API Reference
Parameter Description
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
Parameter Description
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.
Toll Cost Extension API Developer's Guide 37► API Reference
Properties
Parameter Description
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
Parameter Description
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.
Toll Cost Extension API Developer's Guide 38► API Reference
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
Toll Cost Extension API Developer's Guide 39► API Reference
• 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
Toll Cost Extension API Developer's Guide 40► API Reference
• 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:
Toll Cost Extension API Developer's Guide 41► API Reference
▪ "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
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
used for the authentication of the client application. See Acquiring Credentials on
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.
Toll Cost Extension API Developer's Guide 42► API Reference
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
Toll Cost Extension API Developer's Guide 43► API Reference
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
Parameter Description
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
Toll Cost Extension API Developer's Guide 44► API Reference
Properties
Attribute Description
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
Attribute Description
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
Attribute Description
* 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.
Toll Cost Extension API Developer's Guide 45► API Reference
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
Attribute Description
code The numeric identifier of the warning
message The string message associated with the warning code
Toll Cost Extension API Developer's Guide 46► API Reference
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.