Route API

Sommaire

Introduction

Our Open Street web application uses APIs, such as the one that allows you to display the route itinerary between two (or more) points on a map. This article describes how this API works for your own use.

The red markers are linked through the roads in blue.

The red markers are linked through the roads in blue.

In the image above, we notice the red markers, and the steps in blue. A step connects a starting point and a destination. To draw a step, a polyline is used, that is to say a broken line consisting of a succession of GPS coordinates.

Requesting a track with the API

Protocol used

This API uses the GET method implemented in the HTTP 1.1 protocol. It can therefore be used from a standard web browser or any other library which enables the data download from a web server. This optimization API is not likely to receive special or accented characters, but URLs must still be properly encoded. Recent browsers automatically encode URLs but not always HTTP libraries.

All of our APIs support gzip compression, so it is strongly recommended to enable this feature in your HTTP client. To verify that compression is active, the client request header must have Accept-Encoding: "gzip, deflate"  and the response header of the server must have Content-Encoding: "gzip" . This reduces the download time of the data by almost 50%. The compression is particularly effective with this API, which is why it is important to enable it.

The response time of this API is less than 100ms, whether the requests were previously requested or not.

Input Data

To work, this API needs data that is provided as URL parameters. In the table below, asterisks * indicate the parameters that are required to start a calculation.

Parameter Value Explanation
origin* 48.856614,2.352221 Coordinate of the point of departure. The numbers must be a maximum of 10 decimal places.
destination* 45.764043,4.835659 Coordinate of the point of departure. The numbers must be a maximum of 10 decimal places.
mode* driving ou walking Mode of transport vehicule (driving) or foot (walking).
key* chaine-de-caracteres Authentication key for each user.

A concrete example

Let us take the example of the route itinerary between Paris and Lyon (France).

Here’s what the query for the polylines API looks like. Note that a valid authentication key is required.

Data Usage

Output Data

The output data format is a JSON document that can be downloaded and processed by an application, or viewed by a browser. HTTP-based compression is handled by the HTTP client transparently for the developer.

Below is the Output parameter table.

Parameter Explanation
polyline String that contains the geographic path.
total_distance Distance in m.
total_time Time in seconds.
status Status code

The structure of the JSON object is very simple. The value behind the string “polyline” can still reach several tens of kilobytes. This is why we insist heavily on the need to enable client-side gzip compression.

This is a method of encoding a list of geographic coordinates that describe a path. It was defined by Google and is taken up by several cartographic projects. This is an efficient way to “compress” a long list of coordinates into a shorter string.

The above block is a result produced by our API. For better legibility, the polyline has been truncated and therefore not valid.

Usage Tips

When treating this JSON object, you must retrieve the values through their associated chain, and not by their position in the document and their number in line. Actually, other data may intermingle in the future and this is the only way to maintain correct compatibility. For further information on JSON, visit json.org which provides a full comprehensive list of decoding libraries in different languages.

You can use this API in conjunction with our Route Optimization API or our geocoding API.

There is no cache associated with this API, and therefore no gain in repeating a calculation several times.

For an impeccable superposition of the polyline with your background map, we recommend that you use a map from the OpenStreetMap project. We can advise you on this if necessary.

The Error Codes

The standard status code must be “OK”. For any other value returned, the query will fail. The table below describes the meaning of the various codes you may encounter using our API.

Code Explanation
SYNTAX_ERROR The request is incomplete or contains an error.
LIMIT_REACHED You have exhausted your usage quotas. Learn more.
WRONG_KEY Your authentication key is wrong. Contact us.
REQUEST_DENIED Unable to respond to this request.

Usage Example

As you can see, a polyline is a chain of characters that, when interpreted correctly by a cartographic application, appears as a path on a map. It can be converted to a list of latitude, longitude coordinates through an appropriate decoding function. It can be found on the internet.

When decoding, you must pay close attention to the decimal precision previously used during the encoding. Google APIs encode polylines with an accuracy of 5 decimals, while our polylines API has an accuracy of 6 decimal places.
Numerous cartographic libraries are compatible with this format including OpenLayers, Leaflet, Google Maps et Bing Maps.

A demonstration page of the polylines mapping with Leaflet.encoded is available here. Here is a list of projects related to this topic.