RouteXL API v2

RouteXL API v2 and this documentation are under active development. Find the current supported version V1 here

The RouteXL API v2 provides programmatic access to optimize multiple stop itineraries. Upload locations, get distance tables and the optimized order of stops. In the route optimization time windows are supported. Responses are in JSON.

  • The API requires username and password using Basic Authentication over HTTPS. Register your account at: https://www.routexl.com/register
  • Locations must be latitude and longitude coordinates. The API does not provide geocoding of addresses.
  • The maximum number of locations per request is 10. Upgrade your account on the public website to increase the maximum accordingly.
  • The number of allowed requests per day is “unlimited” (fair-use policy), but you can make only one call at a time.
  • The API is provided as-is, without guarantee or warranty of any kind, and is still under active development. We do not advise usage in high-profile production environments.

Overview

Base-URL: https://api.routexl.com/v2/

GET status – gets status of the API
POST distances – creates distances matrix
POST tour – creates new optimized route
Response – HTTP status codes
Examples – cURL & PHP connector class

GET status

Get status of API server, its load and the load of the solvers.

Input

(string) (optional)

String to repeat in the output.

Example:
https://api.routexl.com/v2/status/Hello+world

Output

id (string)

System name and version

datetime (string)

Timestamp of the server.

echo (string)

Returns your string.

max_locations (integer)

The maximum number of locations you are allowed with the username given.

Example:
{"id":"RouteXL API 2.0","datetime":"2017-03-01 09:30:12","echo":"Hello world","max_locations":10}

POST distances

Create a distance matrix for locations.

Input

locations (json array)

Array of locations in json. Required fields for each location are the name/address, and its gps coordinates in lat/lng.

maxDistance (integer) (optional)

Maximum distance in meters. If the estimated distance between two points as the crow flies is larger, the leg will not be routed. The API will then estimate a realistic value without actual routing.

Example:
locations=[{"address":"The Hague, The Netherlands","lat":"52.05429","lng":"4.248618"},{"address":"The Hague, The Netherlands","lat":"52.076892","lng":"4.26975"},{"address":"Uden, The Netherlands","lat":"51.669946","lng":"5.61852"},{"address":"Sint-Oedenrode, The Netherlands","lat":"51.589548","lng":"5.432482"}]

Output

count (integer)

The number of locations that were received (for testing).

distances(json array)

Array of distances. Each distance holds the indices of two points, the distance in meters and duration in seconds, and a boolean router. The indicates if the leg is indeed calculated by the router. If not routed, the distance and duration were estimated as the crow flies.

Example:
{"count":4,"distances":{"0":{"from":0,"to":1,"distance":3850,"duration":305,"router":true},"1":{"from":0,"to":2,"distance":134646,"duration":5399,"router":true},"2":{"from":0,"to":3,"distance":128881,"duration":5443,"router":true},"3":{"from":1,"to":2,"distance":133251,"duration":5266,"router":true},"4":{"from":1,"to":3,"distance":127486,"duration":5310,"router":true},"5":{"from":2,"to":1,"distance":134764,"duration":5366,"router":true},"6":{"from":2,"to":3,"distance":23361,"duration":1173,"router":true}},"maxDistance":false,"skipValues":false,"solver":"WS2611@WBC"}


POST tour

Post new set of addresses, creating a new tour. For now, this immediately returns an optimized tour, the fastest route. In future, it wil return the tour ID for CRUD referal.

Input

locations (array)

The locations for the route. Required fields for each location are the name/address and the gps coordinates in lat/lng. The first element is used as departure, the last as final arrival. If you need to start and finish at the same location, you’ll need to add it twice in the array.

Optionally, each location can have a servicetime, expressed in minutes. This is the waiting or processing time at the location, the time delay between arrival and departure.
Note: if no servicetime is given, the system default of 5 minutes is used.

Optionally, each location can have restrictions. This can be used for time windows, pickup & delivery points, heading and capacity constraints. Restrictions is an array with these optional integers:

– ready: earliest time the location may be visited (minutes, greater than 0).
– due: latest time the location must be visited (minutes, greater than 0).
– before: index number of the location that is the delivery point for this location.
– after: index number of the location that is the pickup point for this location.
– heading: the direction of approach and departure of this location (degrees, north=0, clockwise).
– demand: with multiple rounds, the percentage of vehicle capacity required for this location (0-100).

Some notes on restrictions:
– Ready and due times are relative. A route starts at 0 minutes. E.g. if you start driving at 8:00AM and a location needs to be visited before 9:00AM, use due: 60.
– Index numbers for before and after need to be the array index of the locations array, counting from 0. Do not use the name/address field.

endAtMostDistantLocation (bool) (optional)

This will make the route end at the most distant location in your input, instead of ending at the last location in your input. Note that beeline distance (as the crow flies, calculated from the first location) is used to select the most distant location, not travel time.

skipOptimisation (bool) (optional)

This will prevent the API to optimize the route. The locations are returned in same order as is, but arrival times and cumulative distances are calculated.

parameters (array) (optional)

Optionally, you can send parameters for the optimization:
– type: sets the vehicle to be used (car, smalltruck, foot, bike, drone)
– speed: percentage to adjust the speed for the vehicle (10-200)
– rounds: sets the number of rounds in the route, for multiple vehicles, drivers or days (1-10)
– balance: sets the balance between total travel time and makespan (0-100)
– maxRoundtime: soft restriction on the duration of each round (minutes >0)
– directions: when set the result will hold details of the route (boolean)

Example:
locations=[{"address":"The Hague, The Netherlands","lat":"52.05429","lng":"4.248618"},{"address":"The Hague, The Netherlands","lat":"52.076892","lng":"4.26975"},{"address":"Uden, The Netherlands","lat":"51.669946","lng":"5.61852"},{"address":"Sint-Oedenrode, The Netherlands","lat":"51.589548","lng":"5.432482"}]

Output

id (alfanumeric)

The unique ID for the tour that may be used for CRUD referal (in future).

count (integer)

The number of locations that were received (for testing).

feasible (boolean)

Indicates if the restrictions are met. If the route meets all requirements from the input, the route is feasible (true). If one or more restrictions do not hold, the route is not feasible (false). Infeasible routes are unreliable and should not be used.

route (array of waypoints)

The optimized tour holding the fastest route. Waypoints are returned in an array in the optimized order. Start and finish are first and last locations from the input.

Each waypoint returns the name as a string, the arrival time in minutes (integer) and the cumulative distance in kilometers (float).

Note: if skipOptimisation was set true, the route is not optimized. Waypoints are returned in the same order as the input, but the feasibility is checked and both arrival times and cumulative distances are available.

(optional) directions (array)

When parameters[directions] was set true, the result will hold more details of the route. The directions are returned as a numbered array of instructions and points. These can be used to draw the route on a map of give driving instructions.

Example:
{"id":"4T4446Pj","count":4,"feasible":true,"route":{"0":{"name":"The Hague, The Netherlands","arrival":0,"distance":0},"1":{"name":"The Hague, The Netherlands","arrival":5,"distance":3.9},"2":{"name":"Uden, The Netherlands","arrival":93,"distance":137.1},"3":{"name":"Sint-Oedenrode, The Netherlands","arrival":112,"distance":160.5}}}


Response

The API may respond with the following HTTP status codes:

  • 401: Authentication problem
  • 403: Too many locations for your subscription
  • 409: No input or no locations found
  • 429: Another route in progress
  • 204: No distance matrix, tour or route was found

Examples

Get an unoptimized route using cURL:

curl \
--url https://api.routexl.com/v2/tour/ \
--user <username>:<password> \
--data 'locations=[{"address":"1","lat":"52.05429","lng":"4.248618"},{"address":"2","lat":"52.076892","lng":"4.26975"},{"address":"3","lat":"51.669946","lng":"5.61852"},{"address":"4","lat":"51.589548","lng":"5.432482"}]&skipOptimisation=true'

There are more examples with code for PHP and Javascript on GitHub, and user contributed C# .NET API Snippets on the support forums.