Optimization API

Introduction

Open Street is a route optimisation service created from open-source programming libraries and a software developed in-house. In short, if you know your venues but you do not know in what order it is best to go through them, Open Street can be useful.

Our online web application uses Open Street APIs, including the one that optimises journeys by solving the problem of the commercial traveler.

The launch of a calculation by the optimization API

Protocols 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 that allows data to be downloaded from a web server. This optimisation API is not suited to receiving 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 calculation time increases according to the number of points. Specifically, it grows to the square of the number of points. It takes a few seconds for about 10 points, and a few minutes for a hundred. For more information on calculating time prediction, click here.

It is therefore important that the HTTP client used supports a timeout of several minutes. On request, we can provide the function that gives the estimated calculation time according to the number of points, in order to implement a progress bar in an application.

Our resolution engine takes advantage of an internal cache that allows a request to be accelerated given it has already been requested. Thus, by relaunching a calculation, or by modifying only a few points of a calculation already launched, the resolution time will be substantially shorter.

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.

The geographical points to be optimised must be entered in the form of latitude and longitude coordinates and not in the form of postal addresses. The Open Street geocoding API allows you to perform this conversion.

Parameter	Value	Explanation
pts*	46.2021852,5.2221591	Crossing points separated by vertical pipes |. The numbers must be between 1 and 10 decimal places. The absence of a decimal is denied because it is not precise enough to describe a place.
nb*	from 3 to hundreds	Number of points submitted. It must be consistent with the pts parameter, and ensures the integrity of the transmission
mode	driving or bicycling or walking	Mode of transport: car, bicycle or pedestrian. The distances are modified to use the channels adapted to each of these modes. For technical reasons, we have currently deactivated the «bicycling» and «walking» modes.
unit	m or s	Choice of the work unit to optimise the distance traveled in meters, or the travel time in seconds.
tour	open ou closed	Choice of an open loop itinerary without return to the starting point or in a closed loop with return to the starting point.
key*	string	Authentication key for each user.

As for the means of transport (mode), many tests were carried out for the car journeys, and less for the bike or pedestrian.

The recommended work unit is m.

The type of route (tour) profoundly changes the interpretation that must be made of the results. In the first closed-loop case, the result does not really have a starting point, and the loop can be traversed in the desired direction. In the second open loop case, the starting point is the first point provided to the API while the end point is the last point provided to the API; The order of the result must be considered as it is.

With the round parameter “closed”, the results of the API can be presented in any way. This explains why you can find a difference between this mode and the “open” mode in which you would have fixed the starting point identical to the point of arrival: the direction of travel of the loop can be reversed.

A concrete example

Let us take the simplistic example of a four-point path whose optimized passage order is to be calculated.

Point	Postal address	Coordinates lat,lon
A	135 rue Saint-Leu, 80000, Amiens, France	49.8998757,2.300284
B	1 rue Marcel Cuny-Cronne, 54039, Baccarat, France	48.4510104,6.7483327
C	37 rue Bronzac, 94230, Cachan, France	48.7830011,2.333158
D	1 Boulevard Maréchal Foch, 76200, Dieppe, France	49.929876,1.078363

The postal addresses have previously been transformed into latitude and longitude coordinates thanks to our geocoding API. Here is what the query for the optimization API looks like. Note that a valid authentication key is required.

 

Processing the API optimisation results

Output Data

The format of the output data is a JSON object which can be downloaded and utilised through an application, or visualised through a browser. The compression linked to the HTTP protocol is managed by the HTTP client in a transparent way for the developer. Find below, the table of outgoing parameters.

Parameter	Explanation
DIMENSION	Problem dimension, identical digits to the entry parameters nb.
TOUR	Identical to the entry parameter and shown as a reminder.
COMPUTE_TIME	Calculation time in seconds.
TOTAL_TIME	Data cleansing time and calculation in seconds.
OPTIMIZATION	Optimised order of passage of points using the indexes and initial request.
STEPS_DURATIONS	Travel time by stages (in seconds).
STEPS_DISTANCES	Travelled time by stages (in meters).

This is the exact JSON object returned by the API.

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. You can safely transform the JSON object into a spreadsheet in your programming language with the help of a specialized library, given that you keep the strings and values intact. For further information on JSON, visit json.org which provides a full comprehensive list of decoding libraries in different languages.

Take particular note of the tips with regards to interpretation of the data within the tour parameters used. In this precise case, the route is a closed-loop and so we can take any direction desired, and from any point of our choice. By default, the first point of the loop is the first request point.

During the calculation of an optimized route, the point of departure and arrival can be warehouses, the head-office, the residence, a hotel, etc. It is important to include this points when optimizing, and not only the meet-up points.

For this simplistic four-point calculation, we notice that the optimised order is identical to the request order. It would be different for a 40-point calculation.

For calculations made up of multiple points (several tens), we can notice that the result shows a certain variability pattern when multiplying requests. This is very normal, since our resolution algorithm is initiated through a random variable. However, you will notice that the length of these results are close to more than 95%. If you wish to be extremely certain you possess the most optimized results to the nearest kilometer, you have the possibility of doing the calculation over, many times and keeping the best result.

The error codes

It can happen that the calculation fails due to a request error or and internal server error. This is the type of code that can be displayed.

The spreadsheet below describes the significance of the different codes that you can encounter when using our API. Every export which does not contain resolution data with the key « OPTIMIZATION » should be considered an error. The error messages below can change, that is why it is necessary to test the presence of the key « OPTIMIZATION » to identify an error.

Code	Explanation
SYNTAX_ERROR	The request is incomplete or contains an error.
INVALID_LATLON	The latitude and longitude coordinates are not decimals between 1 and 10 decimals.
WRONG_KEY	Your auth key is faulty. Contact us.
NB_IS_INCONSISTENT	The nb parameter is false.
LIMIT_REACHED	You have exhausted your quota. Learn more.

The codes below are particularly rare, but it may be useful to comprehend.

Code	Explanation
BINARY_NOT_FOUND	The system resolution is absent, obsolete, or corrupted. Contact us.
INTMAXDATA_TOO_BIG	The distance between the points are too large, greater than the distance from Paris-Pekin. Can signify a geocoding error on the wrong continent.
PRESET_UNKNOWN	System configuration error. Contact us.
RESOLVER_HAS_FAILED	The resolution failed after the matrix became normale. Contact us.
RESULTS_NOT_FOUND	The problem cannot be solved. Contact us.
DISTANCES_TIMEOUT	Internal Problem. Contact us.
DISTANCES_ERROR	Internal Problem. Contact us.

Upcoming Developments

• Other parameters may come up to help with the calculation.
• The HTTP protocol’s GET method limits the size of the requests to 8 Ko, which is approximately 200 coordinates in a single optimization. This limit will be overcome in future through the use of the POST method.