Why use the Waypoints Sequence Extension API?

Transcription

Waypoints Sequence Extension API
Developer's Guide
Version 1.0.0
Waypoints Sequence Extension API Developer's Guide
► Contents
2
Contents
Legal Notices..........................................................................................................................................................3
Document Information.................................................................................................................................... 4
Chapter 1: Overview................................................................................................................................. 5
What is the Waypoints Sequence Extension API?................................................................................... 6
Why use the Waypoints Sequence Extension API?................................................................................. 6
Chapter 2: User Guide............................................................................................................................ 7
Acquiring Credentials..................................................................................................................................... 8
Constructing a Request................................................................................................................................ 8
Customer Integration Testing......................................................................................................... 9
Key Concepts.................................................................................................................................................10
Examples......................................................................................................................................................... 11
A Waypoints Sequence for a Car including Traffic Information............................................ 11
A Waypoints Sequence for a Truck............................................................................................. 14
Service Support............................................................................................................................................ 17
Chapter 3: API Reference................................................................................................................. 18
Resource Types............................................................................................................................................ 19
FindSequence.................................................................................................................................... 19
Response Types............................................................................................................................................ 21
FindSequence Response.................................................................................................................21
Data Types..................................................................................................................................................... 22
WaypointWithIdType........................................................................................................................ 23
Chapter 4: Error Handling................................................................................................................ 24
► Legal Notices
3
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 in the United States
and other countries.
Other trade names are trademarks or registered trademarks of their owners.
Disclaimer
This content is provided "as-is" and without warranties of any kind, either express or implied,
including, but not limited to, the implied warranties of merchantability, fitness for a particular
purpose, satisfactory quality and non-infringement. Nokia does not warrant that the content is error
free and Nokia does not warrant or make any representations regarding the quality, correctness,
accuracy, or reliability of the content. You should therefore verify any information contained in the
content before acting on it.
To the furthest extent permitted by law, under no circumstances, including without limitation Nokia's
negligence, shall Nokia be liable for any damages, including, without limitation, direct, special,
indirect, punitive, consequential, exemplary and/ or incidental damages that result from the use or
application of this content, even if Nokia or an authorized representative has been advised of the
possibility of such damages.
► Document Information
Document Information
Product
Name:
Waypoints Sequence Extension API
Version:
Version 1.0.0
Document
Name:
Id:
2f73fc9-1429099815
Status:
FINAL
Date:
2015-Apr-15, 12:10 (GMT)
4
► Overview
Chapter
1
Overview
Topics:
•
What is the Waypoints Sequence
Extension API?
•
Why use the Waypoints Sequence
Extension API?
This developer guide introduces the Waypoints Sequence
Extension API.
5
► Overview
6
What is the Waypoints Sequence Extension API?
The HERE Waypoints Sequence Extension API calculates the optimal sequence of any given waypoints
along a route, while minimizing the time or distance traveled. Often referred as the “Travelling
Salesman Problem”, the service takes into account the HERE road network restrictions as well as
traffic pattern data to provide accurate travel times and distances between subsequent waypoints.
Mode of travel, by car or truck, as well as route preference like fastest or shortest, can also be
considered when applying for specific use cases.
Why use the Waypoints Sequence Extension API?
The HERE Waypoints Sequence Extension API provides a planning tool for route planning through
several specified waypoints. In addition to the order of the user-provided destinations, the
HERE Waypoints Sequence Extension API gives travel times and distances between subsequent
destinations.
The result takes road network restrictions into account. The interface uses the introduced formats
from the HERE Enterprise Routing for easy integration.
Examples for use-cases are:
Transport & Logistics •
For parcel delivery services and time-critical deliveries of goods and services
Utilities
•
Save driving time and optimise working hours
•
Optimise driving distance and save fuel
•
Optimise maintenance, outage and repair jobs
•
•
Optimise driving distance and save fuel
Government Services •
For safety and security tours and regular blue light surveillance tours,
public transport grid optimisation
•
•
Optimise driving distance and save fuel.
► User Guide
Chapter
2
User Guide
Topics:
•
Acquiring Credentials
•
Constructing a Request
•
Key Concepts
•
Examples
•
Service Support
The articles in this section provide a guide to using the Waypoints
Sequence Extension API.
7
► User Guide
8
Acquiring Credentials
All users of HERE APIs must obtain authentication and authorization credentials and provide them as
values for the parameters app_id and app_code. The credentials are assigned per application.
To obtain the credentials for an application, please visit http://developer.here.com/get-started for
more details.
Constructing a Request
The basic elements of a request to the Waypoints Sequence Extension API are the start point, a
number of destination points and the routing mode.
You can include an end point. If the request does not contain an end point, one of the given
destination points will be chosen. Each point defining the start, a destination or the end consist of
WaypointId, latitude and longitude in the WGS 84 System. For more information about the
format, see WaypointWithIdType on page 23.
Using the parameter improvefor, you can define if to minimize the travel time or travel distance .
mode defines if the result is suitable for a car or a truck and if to use traffic information calculate the
result. Also, mode defines whether single interconnections are fastest or shortest. This setting is
important for interaction with the routing APIs. We recommend fastest for most use cases. Be sure
to provide a time for the departure if you enable traffic.
For authentication, the parameters app_id and app_code are mandatory. For information about
how to get them, see Acquiring Credentials.
The table below lists the basic request elements with examples. Additionally, a request may contain
more resource-specific parameters, such as parameters for truck specification. For more information
about resource-specific parameters, see FindSequence on page 19.
Table 1: Basic request elements
Element
Base URL
Value/Example
http://wse.api.here.com
http://wse.cit.api.here.com
Description
Production environment only
► User Guide
Element
Value/Example
9
Description
Staging environment only [1]
Path
/1/
The path consists of the major service
version only.
Resource
findsequence.json
GET only, specify request details via
query parameters
Format of Response
json
The format of the response is json.
Usage of jsonp is supported.
Application Code
&app_code=AJKnXv84fjrb0KIHawS0Tg
Substitute your own unique
app_code
Application Id
&app_id=DemoAppId01082013GAL
Substitute your own unique app_id
Start Point
&start=
WiesbadenCentralStation;50.0715,8.2434
First waypoint
A Intermediate
&destination1=
FranfurtCentralStation;50.1073,8.6647
The first of the waypoints
&destination2=
DarmstadtCentralStation;49.8728,8.6326
Up to 50 destinations with
incremented numbering
End Point
&end=MainzCentralStation;50.0021,8.259
Where the route ends. This parameter
is optional.
Routing Mode
&mode=fastest;car;traffic:enabled;
Specifies the way interconnection
routes are calculated.
Departure
&departure=2014-12-01T17:30:00+01:00
Required if
Destination
Another Intermediate
Destination
traffic:enabled;
is set in the routing mode.
Optimization Target
&improveFor=time
Specifies the target for minimizing.
This parameter is optional.
Request Id
&requestId=userGenerated85
This id is referenced again in the
result allowing to track a request
through the service. This parameter is
optional.
Customer Integration Testing
HERE is committed to maintain the best possible production service for all customers. Given that the
production environment is live and common to all API users, we request that you use the alternative
► User Guide
10
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
17.
The CIT environment is not intended for general production use.
Key Concepts
This section provides insights into the key concepts used throughout the Waypoints Sequence
Extension API.
Optimization Target
In the request, you can specify if to improve the result for distance or travel time using the
parameter improvefor. Values are time and distance. By default the Waypoints Sequence
Extension API improves for time.
Identification of Waypoints
The Waypoints Sequence Extension API references waypoints using an id field you need to set in the
request. If there are waypoints without ids, the service generates ids according to the parameter
name, such as "start", "destination1", "end". The response references the waypoints by these ids.
The references occur in the lists of waypoints and interconnections.
Interaction with HERE Routing APIs
The Waypoints Sequence Extension API will not return details of a route. You can receive the detailed
routes by using the HERE Enterprise Routing API .
The request to the Enterprise Routing API must include the mode and two subsequent waypoint
coordinates from the result. If the routes include traffic information, a departure time is also
required. The response of the Waypoints Sequence Extension API provides this information in the
field estimatedDeparture.
► User Guide
11
Examples
This section provides two examples of requests along with the responding results in the following
subsections.
A Waypoints Sequence for a Car including Traffic
Information
User Story
The user is looking for the fastest way from the Central Station in Wiesbaden, Germany to the Central
Station in Mainz, Germany, passing at the Central Stations in Frankfurt, Darmstadt, Hanau and the
Airport in Frankfurt. The user is interested in traffic information and wants to find a time-optimized
route.
Request Summary
The following list summarizes the elements required to create a request matching the user story and
shows, in the request example below, how to use those elements. Note that the request example also
uses the authentication parameters.
Resource:
/1/findsequence.json
Parameters:
start [start=WiesbadenCentralStation;50.0715,8.2434], specifies the start
point.
destination1 [destination1=FranfurtCentralStation;50.1073,8.6647],
specifies one of the destinations.
destination2 [destination2=DarmstadtCentralStation;49.8728,8.6326],
destination3 [destination3=FrankfurtAirport;50.0505,8.5698], specifies
one of the destinations.
destination4 [destination4=HanauCentralStation;50.1218,8.9298],
end [end=MainzCentralStation;50.0021,8.259], specifies one of the end point.
► User Guide
12
improveFor [improvefor=time], specifies the optimization target. The user
wants the fastest connection.
departure [departure=2014-12-09T09:30:00+01:00], specifies the
departure time at the start point. This is needed for including traffic
information.
mode [mode=fastest;truck;traffic:enabled;], specifies the way the connections
between the waypoints are calculated
Request
http://wse.cit.api.here.com/1/findsequence.json
?app_id=DemoAppId01082013GAL
&start=WiesbadenCentralStation;50.0715,8.2434
&destination1=FranfurtCentralStation;50.1073,8.6647
&destination2=DarmstadtCentralStation;49.8728,8.6326
&destination3=FrankfurtAirport;50.0505,8.5698
&destination4=HanauCentralStation;50.1218,8.9298
&improveFor=time
&departure=2014-12-09T09:30:00%2b01:00
&mode=fastest;truck;traffic:enabled;
Response
{
"results": [{
"waypoints": [{
"id": "WiesbadenCentralStation",
"lat": 50.0715,
"lng": 8.2434,
"sequence": 0,
"estimatedDeparture": "2014-12-09T09:30:00+01:00"
}, {
"id": "FranfurtCentralStation",
"lat": 50.1073,
"lng": 8.6647,
"sequence": 1,
}, {
"id": "HanauCentralStation",
"lat": 50.1218,
"lng": 8.9298,
"sequence": 2,
}, {
► User Guide
"id": "FrankfurtAirport",
"lat": 50.0505,
"lng": 8.5698,
"sequence": 3,
}, {
"id": "DarmstadtCentralStation",
"lat": 49.8728,
"lng": 8.6326,
"sequence": 4,
}, {
"id": "MainzCentralStation",
"lat": 50.0021,
"lng": 8.259,
"sequence": 5,
"estimatedDeparture": ""
}],
"distance": "169268",
"time": "8384",
"interconnections": [{
"fromWaypoint": "WiesbadenCentralStation",
"toWaypoint": "FranfurtCentralStation",
"distance": 36461.0,
"time": 1897.0
}, {
"fromWaypoint": "FranfurtCentralStation",
"toWaypoint": "HanauCentralStation",
"time": 1786.0
}, {
"fromWaypoint": "HanauCentralStation",
"toWaypoint": "FrankfurtAirport",
"time": 1527.0
}, {
"fromWaypoint": "FrankfurtAirport",
"toWaypoint": "DarmstadtCentralStation",
"time": 1255.0
}, {
"fromWaypoint": "DarmstadtCentralStation",
"toWaypoint": "MainzCentralStation",
"time": 1919.0
}],
"description": "Targeted best basetime; with traffic"
}],
"errors": [],
"processingTimeDesc": "3954ms",
"requestId": ""
}
13
► User Guide
14
A Waypoints Sequence for a Truck
User Story
The user searches the fastest way from the Central Station in Wiesbaden, Germany to the Central
Station in Mainz, Germany, passing at the Central Stations in Frankfurt, Darmstadt, Hanau and the
Airport in Frankfurt. The vehicle used for this journey will be a truck (18t) with a trailer (12t) having
a height of 4.00m, a width of 2.50m and a length of 18.35m. The user is not interested in traffic
information and wants to know the shortest route.
Request Summary
The following list summarizes the elements required to create a request matching the user story and
shows, in the request example below, how to use those elements. Note that the request example also
uses the authentication parameters.
Resource:
/1/findsequence.json
Parameters:
start [start=WiesbadenCentralStation;50.0715,8.2434], specifies the start
point.
destination1 [destination1=FranfurtCentralStation;50.1073,8.6647],
destination2 [destination2=DarmstadtCentralStation;49.8728,8.6326],
destination3 [destination3=FrankfurtAirport;50.050639,8.569641],
destination4 [destination4=HanauCentralStation;50.1218,8.9298],
end [end=MainzCentralStation;50.0021,8.259], specifies one of the end point.
improveFor [improveFor=distance], specifies the optimization target. The
user wantes the shortest route.
mode [fastest;truck;traffic:disabled;], specifies the way the connections
between the waypoints are calculated. Traffic information is not taken into
account.
hasTrailer [hasTrailer=true], specifies that the truck has a trailer.
► User Guide
15
limitedWeight [limitedWeight=18], specifies the way the limited weight of
the vehicle in tons.
trailerWeight [trailerWeight=12], specifies the weight of the trailer in tons.
height [height=4.00], specifies the height of the vehicle in meters.
width [width=2.50], specifies the width of the vehicle(s) in meters.
length [length=18.35], specifies the total length of truck and trailer in
meters.
Request
http://wse.cit.api.here.com/1/findsequence.json
?app_id=DemoAppId01082013GAL
&start=WiesbadenCentralStation;50.0715,8.2434
&destination1=FranfurtCentralStation;50.1073,8.6647
&destination2=DarmstadtCentralStation;49.8728,8.6326
&destination3=FrankfurtAirport;50.050639,8.569641
&destination4=HanauCentralStation;50.1218,8.9298
&improveFor=distance
&mode=fastest;truck;traffic:disabled;
&hasTrailer=true&limitedWeight=18&trailerWeight=12
&height=4.00&width=2.50&length=18.35
Response
{
"results" : [{
"waypoints" : [{
"id" : "WiesbadenCentralStation",
"lat" : 50.0715,
"lng" : 8.2434,
"sequence" : 0
}, {
"id" : "FrankfurtAirport",
"lat" : 50.050639,
"lng" : 8.569641,
"sequence" : 1
}, {
"id" : "FranfurtCentralStation",
"lat" : 50.1073,
"lng" : 8.6647,
"sequence" : 2
}, {
"id" : "HanauCentralStation",
"lat" : 50.1218,
► User Guide
"lng" : 8.9298,
"sequence" : 3
}, {
"id" : "DarmstadtCentralStation",
"lat" : 49.8728,
"lng" : 8.6326,
"sequence" : 4
}, {
"id" : "MainzCentralStation",
"lat" : 50.0021,
"lng" : 8.259,
"sequence" : 5
}
],
"distance" : "168764",
"time" : "11580",
"interconnections" : [{
"fromWaypoint" : "WiesbadenCentralStation",
"toWaypoint" : "FrankfurtAirport",
"distance" : 26568.0,
"time" : 1752.0
}, {
"fromWaypoint" : "FrankfurtAirport",
"toWaypoint" : "FranfurtCentralStation",
"distance" : 15008.0,
"time" : 1343.0
}, {
"fromWaypoint" : "FranfurtCentralStation",
"toWaypoint" : "HanauCentralStation",
"distance" : 34485.0,
"time" : 2447.0
}, {
"fromWaypoint" : "HanauCentralStation",
"toWaypoint" : "DarmstadtCentralStation",
"distance" : 54255.0,
"time" : 3159.0
}, {
"fromWaypoint" : "DarmstadtCentralStation",
"toWaypoint" : "MainzCentralStation",
"distance" : 38448.0,
"time" : 2879.0
}
],
"description" : "Targeted best distance; without traffic"
}
],
"processingTimeDesc" : "1241ms"
}
16
► User Guide
17
Service Support
If you need assistance with this or other HERE products, please contact your HERE representative or
Technical Customer Support.
► API Reference
18
Chapter
3
API Reference
Topics:
•
Resource Types
This section provides descriptions of the resources, parameters,
return types and error codes of the HERE Waypoints Sequence
•
Response Types
Extension API.
•
Data Types
► API Reference
19
Resource Types
This section provides descriptions of the resources of HERE Waypoints Sequence Extension API.
All 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.
FindSequence
Use the resource findsequence to get a good order of waypoints.
.../1/findsequence.json?<parameter1>=<value1>&<parameter2>=<value2>&...
Required 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 8.
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 8.
departure
DateTimeStringTime when travel is expected to start. Traffic speed and incidents are
taken into account when calculating the route. departure is required, if
trafficmode:enabled is set.
The format is as xsd type xs:datetime
[-]CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]
For Example: 2014-011-11T16:52:00+2b02:00,
2014-011-11T16:52:00Z
destinationN
mode
Waypoint with Intermediate destinations, at least one. If no end parameter is provided, one
ID
of these values is selected as end of the sequence.
String
The routing mode specifies how the route shall be calculated:
•
Type: fastest | shortest
•
TransportModes: car | truck
•
TrafficMode: enabled | disabled
This parameter is required.
► API Reference
Parameter
Type
start
Waypoint with Starting Position of the Journey. For Example: start=52.2,8.1
20
Description
ID
Optional Parameters
Parameter
Type
Description
avoidLinks
List of Link
Links that the route may not cross.
Ids
avoidArea
List of
Areas which the route must not cross.
Bounding
Boxes
end
Waypoint with Optional Position to be reached at the end of the journey. This value can be
ID
omitted. In this case the journey will end at any of the destinations.
hasTrailer
Boolean
The value indicates if a truck has a trailer.
height
Number
Defines the height of the truck in meters.
jsonCallback
String
Specifies the name of a user-defined function used to wrap the JSON
response (JSONP).
If a JSON callback is set, the http response status is always "200 OK". In the
case of an error onErrors is set to true and the response field errors
contains an error description.
length
Number
Defines the length of the truck in meter.
limitedWeight
Number
Defines the vehicle's limited weight in tons.
requestId
Text
Clients may pass in an arbitrary string to trace request processing through
the system. The requestId is mirrored in the response of the service.
shippedHazardousGoods
List of Strings List of hazardous goods.
For Example:
..&shippedHazardousGoods=flammable,harmfulToWater&..
trailerWeight
Number
Defines the weight of the vehicle's trailer in tons.
weightPerAxle
Number
Defines the vehicle's weight per axle in tons.
width
Number
Defines the width of the truck in meters.
Hazardous Goods
FindSequence requests can include the following hazardous goods:
explosive
Explosive material
► API Reference
gas
Gas
flammable
Flammable material
combustible
Combustible material
organic
Organic material
poison
Poison
radioActive
Radio-active material
corrosive
Corrosive material
poisonousInhalation
Materials that are poisonous upon inhalation
harmfulToWater
Materials that are harmful to water
other
Other types of hazardous materials
allHazardousGoods
All types of hazardous materials
21
Response Types
This section provides descriptions of the responses of HERE Waypoints Sequence Extension API.
FindSequence Response
Response of the resource findsequence.json.
Parameter
Type
Description
errors
List of strings This field provides descriptions of errors which occurred during the
calculation. The value is always included in the answer, but is a empty array, if
there is no error. errors is providing information if the HTTP response code
indicates an error
processingTimeDesc
String
Calculation time for the result, including the time unit. If the response does
not contains an error, the processing time value is included.
requestId
String
Identifier defined in the request and passed through the system. Only if you
provided a requestId with the parameters, it is included in the response.
results
List of results This List contains 1 or 0 elements with an the order of waypoints. This value
is set, if a result is found.
List of Results details
► API Reference
Parameter
Type
Description
description
String
Description how the sequence of waypoints was calculated.
distance
Number
Length of the journey defined by the sequence of waypoints.
22
Unit: Meters
interconnections
List of times
For each interconnections between two subsequent waypoints the time and
and distances distance are given. Each list entry consists of
•
fromWaypoint: origin waypoint id of the interconnection. The field
refers to the id in the waypoints list.
•
toWaypoint: destination waypoint id of the interconnection. The field
value refers to the id in the waypoints list.
•
time: The travel time between the given waypoints. Unit: Meters
•
distance: The travel distance between the given waypoints. Unit:
Seconds
time
Number
Time needed for the journey, defined by the sequence of waypoints,
depending on the provided parameters this value includes traffic or a static
time calculation.
Unit: Seconds
waypoints
List of
ordered
waypoints
The found sequence of waypoints. For each waypoint
•
id
•
lat
•
lng
•
sequence
•
estimatedDeparture
are given.
The id value is taken from the request. If you sent the request without id,
one is generated. Latitude (lat) and Longitude (lng) are WGS-84 degree
coordinates. id, lat, lng and sequence are always part of a waypoint
entry. The field sequence contains the order of the waypoints in the
calculated sequence. If you choose to make a calculation including traffic
information, the field estimatedDeparture contains the projected
departure at the waypoint. Otherwise estimatedDeparture is omitted.
Data Types
This section provides descriptions of the data types of HERE Waypoints Sequence Extension API.
► API Reference
23
WaypointWithIdType
WaypointWithIdType specifies WGS-84-compliant coordinates with an optional alphanumerical
Id starting with an alphabetic character: [A-Za-z][a-zA-Z0-9].*;latitude,longitude or
latitude,longitude
If you want to only specify a set of geocoordinates using WGS 84-compliant latitude and longitude
values, use
destination3=53.5296,9.97
If you want to specify an ID for the coordinates for tracking or other purposes, specify an
alphanumeric value and a semicolon (;) before the geocoordinates:
destination3=HamburgerHafen;53.5296,9.97
The response includes any values you specify in this case.
► Error Handling
24
Chapter
4
Error Handling
Waypoints Sequence Extension API supports the standard HTTP
status codes
HTTP Status Codes
Error code
Description
200 OK
Indicates success, but may also be returned when an invalid
resource name and/or an invalid parameter combination has
been used in the request.
400 Bad request
Invalid parameter value in the request, for example nonexisting layer requested.
401 Unauthorized
Invalid authentication.
403 Forbidden
Incorrect app_code or app_id in the request. See Acquiring
Credentials on page 8 for more information.
404 Not found
Resource not found.
500 Internal error
There is a server configuration issue.
503 Service
Indicates that the service is temporarily unavailable due to
Unavailable
system overload or maintenance or the resource is currently
disabled.

Why use the Waypoints Sequence Extension API?

Transcription

Similar documents

Gabe Westmaas Rackspace @westmaas

Sze Wong | CEO | Zerion Software, Inc.

μ TIR640 PORTABLE BROADBAND MICRO-TIR IMAGER FOR AIR & GROUND USE

Cyprexx Enhanced

See you in the air

Practical 5: OpenWeatherMap Objective Development of Web Applications Vincent Simonet, 2014-2015

Xfinity Live! 90`s Fest, Saturday, July 19, 2014 | Events | 95.7 BEN

presentation slides

How to save your .gpx file to your Humminbird GPS mapping unit