Routes REST API
NFleet Routes API based on OpenStreetMap data is available at https://routes.nfleet.fi. The API version 1.0 offers two use cases: travel time matrix query and fastest paths query.
Overview
The use of NFleet Routes API requires a subscription. Refer to Authorization section of this documentation to view example on how to include the access token with the request.
The map data covers the countries listed in section Map coverage. If some or all of the coordinates are located outside the covered map area, those locations have a travel time value indicating an unreachable location in the matrix and paths, and have no coordinates traveling to or from such locations.
When using curl or other custom client for making requests, note that operations may respond with HTTP 303 See Other
with a subsequent Location
header to continue the query with, in order to facilitate long-running requests and prevent them from timing out. The clients may use follow redirects option to handle this automatically. For example, in curl this is set with flag -L.
Authorization
Authorization to NFleet Routes API is performed by requesting an OAuth 2.0 access token from NFleet Identity service for an identity assigned to a client. Refer to the Assigning a client identity section in NFleet Portal user guide.
Requesting an access token for an identity is performed by making a POST
request to NFleet identity service token endpoint.
Method | URI | HTTP version |
---|---|---|
POST |
https://id.nfleet.fi/<identity_guid>/token |
HTTP/1.1 |
URI parameters
Parameter | Description |
---|---|
identity-guid | The GUID referring to the identity the client is performing the request for. For a client application, this is the assigned identity of the application. For a user account, this GUID refers to the id of the assignment of a user to a the client making the request. |
Request headers
Header | Description |
---|---|
Authorization |
Required. Basic auth credentials as Base64 encoded octet sequence of UTF-8 characters which contains the client key and the client secret for the client requesting the access token, separated by the : character. The header format is Basic <credentials> |
Response codes
HTTP 200 OK
. Indicates that the request succeeded and that the response contains an OAuth 2.0 access token for the identity requested.
HTTP 401 Unauthorized
. Indicates that the request did not have the correct credentials for the identity requested. Make sure that the identity-guid refers to an id for an assignment of a user to the client application with the credentials used in the request.
Example response
The elements of the response body are as follows.
Field | Type | Description |
---|---|---|
access_token |
string | The OAuth 2.0 access token for the identity requested with parameter identity-guid. |
token_type |
string | The type of the access token. |
expires_in |
number | Number of seconds the access token is valid. |
The value of the field access_token
is used as in the Authorization
header to authenticate the requests to the Routes service.
Available operations
NFleet Routes can be used to request a travel time matrix and a set of shortest paths between waypoints. Each use case consists of two operations: creating the query, and requesting the results of the query.
Operation | Description |
---|---|
Create matrix query | Request a query of travel time matrix between all locations. |
Get matrix | Get a travel time matrix data from a previously requested query. |
Create path query | Request a query of fastest paths between lists of waypoints. |
Get path | Get a set of paths from a previously requested query. |
Create matrix query
The create matrix query operation creates a query for a full travel time matrix for the given set of locations.
Method | URI | HTTP version |
---|---|---|
POST |
https://routes.nfleet.fi/matrix?api-version=<version> |
HTTP/1.1 |
URI parameters
Parameter | Description |
---|---|
version |
Required. The version of the API to use. Use value 1.0 |
Request headers
Header | Description |
---|---|
Authorization |
Required. A unique access token that identifies the user of the API. The header format is Bearer <access_token> . Refer to the Authorization section for steps for obtaining a token. |
Content-Type |
Required. The content type of the request. Use application/json . |
Accept |
Optional. The response format preferred by the client. The default is application/json . To request the data in a compact binary format, use application/octet-stream . See the Get matrix operation for details of the response formats. |
Request body
The request body describes a request to query a travel time matrix between all locations listed, with given settings.
Example payload
{
"locations": [
{
"latitude": 48.775443,
"longitude": 9.168995
},
{
"latitude": 48.776949,
"longitude": 9.170776
},
{
"latitude": 48.777076,
"longitude": 9.166914
}
],
"settings": {
"speedProfile": "van"
}
}
Field | Type | Description |
---|---|---|
locations | List of Locations | Required. Locations to query the matrix for. |
settings | Query Settings | Required. Settings to use in the matrix query. |
The elements of Query Settings are as follows.
Field | Type | Description |
---|---|---|
speedProfile | string | Required. Vehicle travel speed profile to use in query. Affects both the travel times and the road types used. One of car , van , truck , tractor , bicycle , or pedestrian . See the section Travel speed profiles for a description of each profile. |
The elements of Location are as follows.
Field | Type | Description |
---|---|---|
latitude | number | Required. Latitude value of the coordinate in WGS 84 coordinate system. |
longitude | number | Required. Longitude value of the coordinate in WGS 84 coordinate system. |
accessRequirements | string | Optional. Location access requirements to use for the location in the query. Determines how the nearest allowed road of the location is selected. One of driving , stopping , or parking . If omitted, value stopping is used. See the section Location access requirements for a description of each access requirement. |
Response codes
HTTP 303 See Other
. Indicates that the request has been received and is being processed. In order to obtain the results of the query, refer to the Location
response header for a URI to make a subsequent GET
request to.
For other response codes, refer to the section HTTP response codes.
Response headers
Header | Description |
---|---|
Location |
The location of the result of the query. Make a GET request to this URI to obtain the results of the query. |
Get matrix
The Get matrix operation returns the results of a matrix query operation.
Method | URI | HTTP version |
---|---|---|
GET |
https://routes.nfleet.fi/matrix/<query-guid>?api-version=<version> |
HTTP/1.1 |
URI parameters
Parameter | Description |
---|---|
query-guid | The GUID of the matrix query. The GUID is returned as part of the Location response header of the create matrix query. |
version | Required. The version of the API to use. Use value 1.0 |
Request headers
Header | Description |
---|---|
Accept | Optional. The response format preferred by the client. The default is application/json . To request the data in a compact binary format, use application/octet-stream . |
Response codes
HTTP 200 OK
. Indicates that the request succeeded and that the response contains the matrix values from the query.
HTTP 303 See Other
. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location
response header for a URI to make a subsequent GET
request to.
For other response codes, refer to the section HTTP response codes.
Response body
Example response in application/json
The elements of the response body in application/json
format are as follows.
Field | Type | Description |
---|---|---|
values | Array of numbers | The elements of the matrix in an one dimensional array. Each element denotes a travel time in milliseconds between two locations. The ordering of the array corresponds to the order in which the locations were in the request. The array length is n2 for a location list of n locations. |
The elements of the response body in application/octet-stream
format are as follows.
Byte Position | Value | Type | Count | Byte Order |
---|---|---|---|---|
0 | Length of the value array (n) | 32-bit integer | 1 | Little Endian |
4 | Travel time value in milliseconds | 32-bit unsigned integer | n | Little Endian |
Create path query
The create path query operation creates a query for shortest paths between sequences of locations.
Method | URI | HTTP version |
---|---|---|
POST |
https://routes.nfleet.fi/path?api-version=<version> |
HTTP/1.1 |
URI parameters
Parameter | Description |
---|---|
version | Required. The version of the API to use. Use value 1.0 |
Request headers
Header | Description |
---|---|
Authorization |
Required. A unique access token that identifies the user of the API. The header format is Bearer <access_token> . Refer to the Authorization section for steps for obtaining a token. |
Content-Type |
Required. The content type of the request. Use application/json . |
Accept |
Optional. The response format preferred by the client. The default is application/json . To request the data in a compact binary format, use application/octet-stream . See the Get path operation for details of the response formats. |
Request body
The request body describes a request to query for shortest paths between sequences of locations.
Example payload
{
"paths": [
{
"waypoints": [
{
"latitude": 48.775443,
"longitude": 9.168995
},
{
"latitude": 48.776949,
"longitude": 9.170776
},
{
"latitude": 48.777076,
"longitude": 9.166914
}
]
},
{
"waypoints": [
{
"latitude": 48.778087,
"longitude": 9.163695
},
{
"latitude": 48.775209,
"longitude": 9.163201
}
]
}
],
"settings": {
"speedProfile": "van"
}
}
The elements of the request body are as follows.
Field | Type | Description |
---|---|---|
paths | List of Path queries | Set of path queries to perform. |
settings | Query settings | Settings to use in the path query. |
The elements of the path queries are as follows.
Field | Type | Description |
---|---|---|
waypoints | List of Locations | List of waypoints to query the path with. |
The elements of Query Settings are as follows.
Field | Type | Description |
---|---|---|
speedProfile | string | Required. Vehicle travel speed profile to use in query. Affects both the travel times and the road types used. One of car , van , truck , tractor , bicycle , or pedestrian . See the section Travel speed profiles for a description of each profile. |
The elements of Location are as follows.
Field | Type | Description |
---|---|---|
latitude | number | Required. Latitude value of the coordinate in WGS 84 coordinate system. |
longitude | number | Required. Longitude value of the coordinate in WGS 84 coordinate system. |
accessRequirements | string | Optional. Location access requirements to use for the location in the query. Determines how the nearest allowed road of the location is selected. One of driving , stopping , or parking . If omitted, value stopping is used. See the section Location access requirements for a description of each access requirement. |
Response codes
HTTP 303 See Other
. Indicates that the request has been received and is being processed. In order to obtain the results of the query, refer to the Location
response header for a URI to make a subsequent GET
request to.
For other response codes, refer to the section HTTP response codes.
Response headers
Header | Description |
---|---|
Location |
The location of the result of the query. Make a GET request to this URI to obtain the results of the query. |
Get path
The Get path operation returns the results of a path query operation.
Method | URI | HTTP version |
---|---|---|
GET |
https://routes.nfleet.fi/path/<query-guid>?api-version=<version> |
HTTP/1.1 |
URI parameters
Parameter | Description |
---|---|
query-guid | The GUID of the path query. The GUID is returned as part of the Location response header of the create path query. |
version | Required. The version of the API to use. Use value 1.0 |
Request headers
Header | Description |
---|---|
Accept |
Optional. The response format preferred by the client. The default is application/json . To request the data in a compact binary format, use application/octet-stream . |
Response codes
HTTP 200 OK
. Indicates that the request succeeded and that the response contains the paths from the query.
HTTP 303 See Other
. Indicates that the request is being processed. In order to obtain the results of the query, refer to the Location
response header for a URI to make a subsequent GET
request to.
For other response codes, refer to the section HTTP response codes.
Response body
Example response in application/json
{
"paths": [
{
"parts": [
{
"coordinates": [
48.775448,
9.168991,
48.775455,
9.169007,
48.777092,
9.170982,
48.776947,
9.170784
],
"properties": {
"lengthInMeters": 710,
"lengthInMilliseconds": 106573
}
},
{
"coordinates": [
48.776947,
9.170784,
48.77704,
9.166989,
48.777027,
9.16695
],
"properties": {
"lengthInMeters": 561,
"lengthInMilliseconds": 79927
}
}
]
},
{
"parts": [
{
"coordinates": [
48.778065,
9.163626,
48.777622,
9.163951,
48.77571,
9.162838,
48.775208,
9.163203
],
"properties": {
"lengthInMeters": 424,
"lengthInMilliseconds": 76488
}
}
]
}
]
}
The elements of the response body in application/json
format are as follows.
Field | Type | Description |
---|---|---|
paths | List of Paths | List of paths in the path set. |
Path describes a single distinct path in the path set. The elements of Path are as follows.
Field | Type | Description |
---|---|---|
parts | List of Path Parts | List of path parts in the path. Each part describes a leg between two waypoints in the original path computation request. |
Path part describes a part of a path. A part describes a leg between two waypoints in the original path computation request. The part contains the geometry and the properties of the path part. To reconstruct a full path, concatenate and sum all path parts of a single path element. The elements of the path part are as follows.
Field | Type | Description |
---|---|---|
coordinates | Array of numbers | Geometry of the path part in a one dimensional array. Each coordinate is encoded in the array as latitude and longitude values in WGS 84 coordinate system. The first coordinate is at position 0 and 1, the second coordinate at position 2 and 3, and so on. |
properties | Path Part Properties | Properties of the path part. |
Path part properties describe properties of a path part between two waypoints. The elements of path part properties are as follows.
Field | Type | Description |
---|---|---|
lengthInMeters | number | Length of the path part in meters. |
lengthInMilliseconds | number | Travel time of the path part in milliseconds. |
The elements of the response body in application/octet-stream format are as follows.
Byte Position | Value | Type | Count | Byte Order |
---|---|---|---|---|
0 | Number of paths in set (n) | 32-bit integer | 1 | Little Endian |
4 | Paths | Path | n |
The elements of a path are as follows.
Byte Position | Value | Type | Count | Byte Order |
---|---|---|---|---|
0 | Number of parts in path (n) | 32-bit integer | 1 | Little Endian |
4 | Parts | Path Part | n |
The elements of a Path part are as follows.
Byte Position | Value | Type | Count | Byte Order |
---|---|---|---|---|
0 | Part length in meters | 32-bit unsigned integer | 1 | Little Endian |
4 | Part length in milliseconds | 32-bit unsigned integer | 1 | Little Endian |
8 | Number of coordinates in path part (n) | 32-bit integer | 1 | Little Endian |
12 | Coordinates | Coordinate | n |
The elements of a coordinate are as follows.
Byte Position | Value | Type | Count |
---|---|---|---|
0 | Latitude | IEEE 754 32-bit floating point number | 1 |
4 | Longitude | IEEE 754 32-bit floating point number | 1 |
HTTP response codes
The API responds with HTTP response codes that match the HTTP specification semantics as closely as possible. The common responses returned by the GIS API are the following.
200 OK
The request completed successfully.
303 See Other
The request is in progress and the client should continue the request by performing GET
to the address designated by the Location
header of the response.
400 Bad Request
The request data has an error. The errors are described in the response using error message and an error code. See the Request error codes section of this documentation for error details.
401 Unauthorized
Authentication failed for the request. Make sure the authorization scheme Bearer
is designated and that the access token is valid.
403 Forbidden
Authorization failed for the request. The authenticated client does not have permission to perform the request. Make sure that the client has requested an access token for an identity with the necessary permissions.
404 Not Found
The requested resource was not found. Make sure the request URL is correct. If Not Found
is encountered during long-running operation, a timeout may have occurred between requests and the request should be sent again.
405 Method Not Allowed
The HTTP method used is not allowed to the requested URL. Check the HTTP header Allow
for list of allowed method to this resource.
406 Not Acceptable
The HTTP header Accept
contains value that the server cannot use as a response format. Check the documentation for supported Accept
header values for the given operation.
415 Unsupported Media Type
The HTTP header Content-Type
is missing or contains value that the server does not support. Use the application/json
content type for route operations.
429 Too Many Requests
The client has sent too many requests in a given amount of time. Refer to your NFleet subscription details on the request quotas applicable for the client. Check the Retry-After
response header for the number of seconds the client must wait before making a new request.
500 Internal Server Error
The server encountered an unexpected error. The request should be sent again. If the issue persists, contact NFleet support at support@nfleet.fi.
503 Service Unavailable
The server is currently not available. The request should be sent again after a delay. If the issue persists, contact NFleet support at support@nfleet.fi.
Request error codes
If the request reasults in a 400 Bad Request
, the following error codes in the response describe the error in more detail.
Matrix query request errors
Code | Description |
---|---|
10001 | Matrix query settings are missing. |
10002 | Speed profile is missing from matrix query settings. |
10003 | Speed profile is not recognized in path query settings. |
10011 | Location array is missing. |
10012 | Location array is too long. |
10021 | Location latitude value is missing. |
10022 | Location longitude value is missing. |
10023 | Location latitude value is not valid. |
10024 | Location longitude value is not valid. |
10025 | Location access requirements not recognized. |
Path query request errors
Code | Description |
---|---|
20001 | Path query settings are missing. |
20002 | Speed profile is missing from path query settings. |
20003 | Speed profile is not recognized in path query settings. |
20011 | Path list is missing. |
20012 | Path list is too long. |
20013 | Waypoint list is too long. |
20021 | Waypoint latitude value is missing. |
20022 | Waypoint longitude value is missing. |
20023 | Waypoint latitude value is not valid. |
20024 | Waypoint longitude value is not valid. |
20025 | Waypoint location access requirements not recognized. |
Generic request errors
Code | Description |
---|---|
30001 | Api version not supported. |
Map coverage
The Routes API is currently available an area covering the following countries.
- Andorra
- Austria
- Belgium
- Czech Republic
- Denmark
- Estonia
- Finland
- France
- Germany
- Italy
- Latvia
- Liechtenstein
- Lithuania
- Luxembourg
- Monaco
- Netherlands
- Norway
- Poland
- Portugal
- Slovakia
- Slovenia
- Spain
- Sweden
- Switzerland
Travel speed profiles
The travel speed profile set for the query affects both the travel times and the road types used according to map attributes in OpenStreetMap data. In addition, the profile dictates the rules for locating the nearest point on a compatible road for each location in the query. These points serve as start and end point for the query between the locations. For example, with a bicycle profile, the nearest point on a road may be on a cycle path, but with a truck profile, the nearest point may be on a street. If a compatible road is not found near the location, the location is considered inaccessible.
The following speed profiles are defined: car
, van
, truck
, tractor
, bicycle
, and pedestrian
.
Car
The car profile refers to traveling with passenger cars. The profile has the following properties.
- Driving according to road speed limits on fast roads
- Driving at most 140 km/h on roads without speed limit
- Driving nominal average speeds in urban areas and small roads
- Allowed to use all roads designated for motor vehicles
- Allowed to use pedestrian streets and roads marked for loading only
- Not allowed to stop for delivery at motorways or trunks, or on no stopping roads or on ferries
Van
The van profile refers to traveling with vans and small delivery trucks (9 tons or less). The profile has the following properties.
- Driving at most 100 km/h on fast roads
- Driving according to nominal road speed limits on medium roads
- Driving slightly below nominal average speed in urban areas and small roads
- Allowed to use all roads designated for motor vehicles
- Allowed to use pedestrian streets and roads marked for loading only
- Not allowed to stop for delivery at motorways or trunk roads, or on no stopping roads or on ferries
Truck
The truck profile refers to traveling with medium and heavy trucks (10 tons or more). The profile has the following properties.
- Driving at most 80 km/h or 90 km/h on fast roads
- Driving slightly slower than nominal road speed limits on medium roads
- Driving below nominal average speed in urban areas and small roads
- Allowed to use all roads designated for motor vehicles
- Allowed to use pedestrian streets and roads marked for loading only
- Not allowed to stop for delivery at motorways or trunk roads, or on no stopping roads or on ferries
Tractor
The tractor profile refers to traveling with tractors and other special vehicles. The profile has the following properties.
- Driving at most 50 km/h on fast roads
- Driving according to nominal road speed limits on medium roads
- Driving slightly below nominal average speed in urban areas and small roads
- Allowed to use all roads designated for motor vehicles except motorways
- Allowed to use pedestrian streets and roads marked for loading only
- Not allowed to stop for delivery at trunk roads, or on no stopping roads or on ferries
Bicycle
The bicycle profile refers to traveling with bicycles and (electric) delivery bikes. The profile has the following properties.
- Traveling at an average speed of 15 km/h
- Not allowed to use roads designated only for motor vehicles, such as motorways
- Allowed to use cycleways
- Allowed to use footways at walking speed
- Not allowed to use steps
Pedestrian
The pedestrian profile referst to traveling by foot. The profile has the following properties.
- Traveling at an average speed of 5 km/h
- Not allowed to use roads designated only for motor vehicles, such as motorways
- Does not observe one-way street restrictions
- Allowed to use cycleways
- Allowed to use footways
- Allowed to use steps
Location access requirements
In conjunction with the travel speed profile, the location access requirements define how the nearest point on a road for a given location is determined. This is necessary for different kind of routing cases. For example, a delivery should be routed to a service road near to the building, but not on the highway next to the location coordinates. In contrast, a road maintenance operations or vehicle towing services may have waypoints directly on a highway, necessitating different access requirements for each location used in routing.
The following location access requirements are defined: driving
, stopping
, and parking
.
Driving
Driving refers to any road segment accessible through driving, limited only by the speed profile. In other words, if a vehicle is allowed to use a road, the nearest point of a location can be placed on that road. This can be used for example where the routing is for operations that do not require stopping the vehicle.
Stopping
Stopping refers to road segments which permit stopping on the side of the road, for example for a delivery. This is the default value if none is provided.
Parking
Parking refers to road segments where parking for a lengthy stay is permitted. This access requirement conforms to any normal parking restrictions placed on vehicles as defined in the map data.