NFleet Routes API overview

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.

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

{
    "access_token": "ey…y76A",
    "token_type": "Bearer",
    "expires_in": 3600
}

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"
    }
}

The elements of the request body are as follows.

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 pedestrian, bicycle, truck, van, or car. 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.

Example response in application/json

{
    "values": [
        0,
        106573,
        117538,
        102128,
        0,
        79927,
        61851,
        94721,
        0
    ]
}

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

he 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 pedestrian, bicycle, truck, van, or car. 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.

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

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.