1) Routist API documentation

This document describes the Routist API, which can be used to access the Routist features without having to use the web interface. The API heavily uses JSON as the data format, both for the requests and for the responses. The document first presents some general information about calling convention and JSON Objects, then describes every API method. Examples are always provided to help the user quickly understand the data structures.

1.1) Terms of service

By using our API you are agreeing to our terms of service.

1.2) Versioning

This document describes the version 1.0 of the Routist API. As part of the application development, the API could be updated in the future. Every API of the v1 series, with version number 1.x, will be backward compatible with any previous API of the same series. Should the need of any backward incompatible change in the API someday arise, such new API will be called 2.0.

2) Calling conventions

2.1) SSL

All the calls to the API must use the SSL encryption protocol to protect the sensitive information which are sent and received.

2.2) HTTP Method

The requests can be made using the GET, POST, PUT or DELETE methods, depending on the request type. See the documentation for every request.

2.3) API Key

Every request to the API must include the API key provided with your account. Every request, regardless of the HTTP method used, should take the form of

http://www.routist.com/api/request_URL?email=account_email&api_key=account_key

Additional data should of course be supplied in the body part of the request, if needed.

2.4) API errors

No matter which API request is performed, in case of errors with the API key, with the JSON syntax, or with any other aspect of the API, Routist will return an Object with three fields:

  • status will hold the value error, to indicate that an error occurred. This helps in differentiating such message from other return messages of the API which, depending on the request, might contain the status key and assign other values to it, like for example success.
  • error_code contains a numeric error code, which broadly indicates the class of error. See the error codes table for more details.
  • error an human readable string, containing more detailed information about the error.

Error codes

The error_code parameter is linked to the type of error that occurred by the following table

error_code Description
Between 100 and 199Authentication error
Between 200 and 299Supplied JSON object is not a valid JSON
Between 300 and 399Supplied JSON object does not conform to the syntax described in this document
Between 400 and 499The object (vehicle, plan, order) referenced by the request does not exist
Between 500 and 599Geocoding error, the supplied Location object could not be localized
Between 900 and 999Operation not permitted
Between 1000 and 1100Generic error

Example

{
    "status": "error",
    "error_code": 100,
    "error": "Invalid API key for user John"
}

2.5) JSON format

The HTML requests and responses will contain JSON data, so the following declarations must be included in the header
Accept: application/json
Content-type: application/json

Also, JSON uses the dot symbol instead of the comma in floating point values representation.

2.6) Call example

As an example, assuming user Alice has alice@test.com as email and 1234567890 as API key, a call to the vehicles_add function to the plan number 42 could be made using curl with the command

curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"id": 42, "vehicle_names": ["David", "John"]}' "https://www.routist.com/api/v1/data/plans/vehicles?email=alice@test.com&api_key=1234567890"

3) Object definitions

Objects are JSON structures with a given set of keys and associated values. We describe here a set of Objects that, while they are not directly passed as arguments in the Routist API, they can be used to construct more complex JSON queries and responses, which will indeed be used inside the API. Every object will be defined by a table, which describes the fields contained inside the object. The column names are self-describing:
  • Name: the name of the field key
  • Description: provides a description for the value contained inside the object
  • Type: the JSON type for the value. Can be Number, String, Boolean, Array, Object or null
  • Is required: specifies if the given key is required or optional
  • Requirements: specifies any additional requirements the value must satisfy

3.1) Location

Used to represent a location, by supplying either the latitude and longitude in WGS84 format, or the address, to be geolocalized.

Format:

Name Description Type Is required Requirements
streetThe street name and number, to be localizedString
See note
cityThe city nameString
See note
regionThe regionString
See note
zipcodeThe location zip codeString
See note
countryThe location countryString
See note
latLocation latitudeNumber (float)
See note
lonLocation longitudeNumber (float)
See note

Note: The object must contain enough information so that Routist is able to correctly localize the point. Should both lat and lon parameters be supplied, then such values are used as coordinates, and any other field is used only for display purposes. In this case no actual localization takes place.
Otherwise, should lat and lon be missing, the other fields are used to localize the point. The more data is supplied, the more accurate the localization will be. We strongly suggest to provide at least the street, city (or zipcode) and country fields.

Example:

{
    "lat": 1.23,
    "lon": 1.23
}

3.2) Time window

Represents a time window, which begins and ends at given times of the day. The Time window object is used to represent constraints, like the allowed order delivery periods, or the driver rest period.

Format:

Name Description Type Is required Requirements
earliestThe earliest time allowed for the time window, in minutes from midnightNumber (integer)X
Must be non-negative
latestThe latest time allowed for the time window, in minutes from midnightNumber (integer)X
Must be non-negative
Must be greater or equal than earliest

Example:

{
    "earliest": 720,
    "latest": 840
}

3.3) Rest constraint

Represents the constraints for the driver rest period, intended for the launch break. The driver rest period has a duration, and must all fit inside the given time window. The optimizer will take care of deciding when should the rest period begin, taking into account the optimized schedule of the day for the given driver.

Format:

Name Description Type Is required Requirements
time_windowThe time window where the driver can restObject (Time window)X
durationThe rest period duration, in minutesNumber (integer)X
Must be non-negative
Must be at most time_window latest minus time_window earliest

Example:

{
    "time_window": {
	"earliest": 720,
	"latest": 840
    },
    "duration": 45
}

3.4) Vehicle

The Vehicle object contains all the data that define a vehicle. This includes the driver details, three different kinds of capacity, intended as the maximum amount of goods or other quantity the vehicle can hold, three different kind of cost parameters, the constraints relative to the working and rest hours, the starting and ending depots, and a list of skills that the driver can provide.

Format:

Name Description Type Is required Requirements
driverDriver nameStringX
Length must be between 1 and 40
Must be unique
emailDriver emailString
Must be a valid email
capacity1Type 1 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity2Type 2 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity3Type 3 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
cost_hourlyHourly cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_kilometricKilometric cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_activationActivation cost for the vehicle, if presentNumber (float)
Must be non-negative
start_timeDriver start time in minutes from midnight, default 540 (09:00 AM)Number (integer)
Must be non-negative
finish_timeDriver finish time in minutes from midnight, default 1080 (06:00 PM)Number (integer)
Must be non-negative
Must be greater or equal than start_time
flexible_departureAllows the vehicle to leave the departure after the start time, default true. See noteBoolean
restThe driver launch rest time, if required, otherwise nullObject (Rest constraint) or null
work_up_toThe maximum driver working time for the day, in minutes, if presentNumber (integer)
Must be non-negative
drive_up_toThe maximum driver driving time for the day, in minutes, if presentNumber (integer)
Must be non-negative
overtimeIf true, then the driver is allowed to work overtimeBoolean
If true, then also cost_hourly_overtime must be present
cost_hourly_overtimeHourly overtime cost for the vehicle, if presentNumber (float)
Must be non-negative
work_up_to_overtimeThe maximum driver working overtime for the day in addition to the standard work_up_to value, in minutes, if presentNumber (integer)
Must be non-negative
start_addressThe vehicle starting point locationObject (Location)X
end_addressThe vehicle end point location. If not supplied, the vehicle will return to the start_addressObject (Location)
skillsThe skills supplied by the driver. Skills are case-insensitiveArray of Strings
subfleetsA list of subfleets the vehicle is belonging toArray of Strings

Note: If flexible_departure is false, then the driver turn will begin at start_time, even if no order exist that can be served at the beginning of the shift. In that case, the driver will stay at the depot, waiting for the first order time window to open, and will incur in the specified hourly_cost. On the other hand, if flexible_departure is true, the driver starting time can be postponed, thus saving the hourly_cost up until the driver is actually needed.

Example:

{
    "driver": "David",
    "capacity1": 42,
    "cost_hourly": 5,
    "cost_kilometric": 0.5,
    "cost_activation": 10,
    "start_time": 480,
    "finish_time": 1080,
    "flexible_departure": true,
    "rest": {
	"time_window": {
	    "earliest": 720,
	    "latest": 840
	},
	"duration": 45
    },
    "work_up_to": 480,
    "drive_up_to": 360,
    "overtime": true,
    "cost_hourly_overtime": 10,
    "work_up_to_overtime": 120,
    "start_address": {"lat": 1.23, "lon": 1.23},
    "end_address": {"lat": 4.56, "lon": 4.56},
    "skills": ["Cleaning", "Plumbing"]
}

3.5) Order

Used to identify an order and its associated demand; demand can be expressed in at most three units of measurement, coherent with the three capacities used in vehicle definitions. Also describes the constraints relative to the service time, the priority and the skills or driver required to serve the order.

Format:

Name Description Type Is required Requirements
nameOrder nameStringX
Length must be between 1 and 60
addressThe order addressObject (Location)X
demand1The vehicle type 1 capacity used by the order, if presentNumber (float)
Must be non-negative
demand2The vehicle type 2 capacity used by the order, if presentNumber (float)
Must be non-negative
demand3The vehicle type 3 capacity used by the order, if presentNumber (float)
Must be non-negative
time_of_serviceThe time the vehicle must stop to serve the orders, in minutes, default 10Number (float)
Must be non-negative
time_windowsUp to 2 time window constraintsArray of Objects (Time window)
Length must be between 1 and 2
Time windows must be ordered and non-overlapping
priorityThe order priority, defaults to 3 (lowest)Number (integer)
Must be between 1 and 3
required_driver_nameRequires the order to be served by a specified driverString
skillsThe skills required by the driver to serve the given order. Skills are case-insensitiveArray of Strings
notesThe order notesString

Example:

{
    "name": "Cleaning 1",
    "address": {"lat": 2.34, "lon": 2.34},
    "demand1": 10,
    "demand3": 15,
    "time_of_service": 30,
    "time_windows": [
	{
	    "earliest": 540,
	    "latest": 720
	},
	{
	    "earliest": 900,
	    "latest": 1140
	}
    ],
    "priority": 1,
    "required_driver_name": "David",
    "skills": ["Cleaning"],
    "notes": "Third floor"
}

3.6) Route element

A route element for the optimization solution. A route is composed of a list of route elements, each one corresponding to a plan order. Every route element contains the information about the timing and the distance travelled to serve the order.

Format:

Name Description Type Is required Requirements
nameThe order identifierStringX
leg_travel_timeThe time spent to reach the given route element, in minutesNumber (float)X
Must be non-negative
leg_distanceThe distance covered to reach the given route element, in the plan's distance unitNumber (float)X
Must be non-negative
arrivalThe time of the day the vehicle reaches the route element, in minutes from midnightNumber (float)X
Must be non-negative
wait_timeThe time the driver has to wait before being allowed to serve the order, in minutesNumber (float)X
Must be non-negative
departureThe time of the day the driver leaves the route element, in minutes from midnightNumber (float)X
Must be non-negative

Example:

{
    "name": "Order 2090",
    "leg_travel_time": 2.66667,
    "leg_distance": 1292,
    "arrival": 542.667,
    "wait_time": 0,
    "departure": 582.667
}

3.7) Route

Describes an optimized route, including the data about the driver, the list of orders to be served, and the time and distance covered.

Format:

Name Description Type Is required Requirements
driver_nameThe identifier of the driver assigned to the routeStringX
durationThe total duration of the route, in minutesNumber (float)X
Must be non-negative
time_on_the_roadThe total time spent while driving, in minutesNumber (float)X
Must be non-negative
worked_timeThe total time spent while working, equal to the total duration, excluding the wait and rest times, in minutesNumber (float)X
Must be non-negative
distanceThe total distance covered, in the plan's distance unitNumber (float)X
Must be non-negative
forward_time_slackThe difference between the vehicle earliest start time and the time the vehicle leaves the depot, in minutesNumber (float)X
Must be non-negative
departureThe time the vehicle leaves the depot, in minutes from midnightNumber (float)X
Must be non-negative
routeThe list of orders served by the routeArray of Objects (Route element)X
restThe driver rest period, if presentObject (Rest response)
last_legThe data about the depot reentry legObject (Last leg data)X

Example:

{
    "driver_name": "Richard",
    "duration": 489.167,
    "time_on_the_road": 99.1667,
    "worked_time": 429.167,
    "distance": 76876,
    "forward_time_slack": 0,
    "departure": 540,
    "route": [
	{
	    "name": "Order 2098",
	    "leg_travel_time": 14.1667,
	    "leg_distance": 10914,
	    "arrival": 554.167,
	    "wait_time": 0,
	    "departure": 644.167
	},
	{
	    "name": "Order 2100",
	    "leg_travel_time": 35.5,
	    "leg_distance": 22120,
	    "arrival": 679.667,
	    "wait_time": 0,
	    "departure": 799.667
	},
	{
	    "name": "Order 2099",
	    "leg_travel_time": 0,
	    "leg_distance": 0,
	    "arrival": 894.5,
	    "wait_time": 0,
	    "departure": 1014.5
	}
    ],
    "rest":
    {
	"rest_type": 1,
	"order_after_rest": "Order 2099",
	"rest_start": 834.5,
	"rest_end": 894.5,
	"rest_travel_time": 34.8333,
	"rest_distance": 32937,
	"rest_wait_time": 0
    },
    "last_leg":
    {
	"arrival": 1029.17,
	"leg_travel_time": 14.6667,
	"leg_distance": 10905
    }
}

3.8) Rest response

A Rest response object is generated by the optimizer, and used to provide information about the rest period for the driver, should such driver require it. Rests can be performed on the road, by taking a break while driving between two orders, or as soon as the driver arrives at a destination, just before serving the order.

Format:

Name Description Type Is required Requirements
rest_typeType 1 rests are performed once the vehicle arrives at a route element, just before serving the order. Type 2 rests are performed while on the roadNumber (integer)X
Must be between 1 and 2
order_after_restThe order to be served as soon as the rest period finishes, or null if the rest is performed while returning to the depotString or nullX
rest_startStarting time for the rest period, in minutes from midnightNumber (float)X
Must be non-negative
rest_endEnd time for the rest period, in minutes from midnightNumber (float)X
Must be non-negative
rest_travel_timeThe amount of time spent between the completion of the last order and the rest beginning, in minutesNumber (float)X
Must be non-negative
rest_distanceThe distance traveled between the completion of the last order and the rest beginning, in the plan's distance unitNumber (float)X
Must be non-negative
rest_wait_timeThe amount of time the driver has to wait, once arrived at the rest destination, before starting the rest periodNumber (float)X
Must be non-negative

Example:

{
    "rest_type": 1,
    "order_after_rest": "Order 2099",
    "rest_start": 834.5,
    "rest_end": 894.5,
    "rest_travel_time": 34.8333,
    "rest_distance": 32937,
    "rest_wait_time": 0
}

3.9) Last leg data

Contains some additional information for the vehicle route plan, regarding the return to the depot.

Format:

Name Description Type Is required Requirements
leg_travel_timeThe time spent to reach the depot from the last order, in minutesNumber (float)X
Must be non-negative
leg_distanceThe distance covered to reach the depot from the last order, in the plan's distance unitNumber (float)X
Must be non-negative
arrivalThe time of the day the vehicle reaches the depot, in minutes from midnightNumber (float)X
Must be non-negative

Example:

{
    "arrival": 1029.17,
    "leg_travel_time": 14.6667,
    "leg_distance": 10905
}

3.10) Plan

Object used to return additional plan information, not already contained in the order sequence.

Format:

Name Description Type Is required Requirements
idThe plan identifierNumber (integer)X
Must be non-negative
nameThe plan nameStringX
Length must be between 1 and 40
dateThe plan dateString or null
Must be a valid date, formatted as yyyy/mm/dd or must be null
distance_unitThe distance unit used by the plan, which can be kilometers or miles, default kmString
Must be one of: km, mi

Example:

{
    "id": 42,
    "name": "My delivery plan",
    "date": "2013/12/12",
    "distance_unit": "km"
}

3.11) Order details

Order details for the mobile device. Adds additional tracking information to the Order object

Format:

Name Description Type Is required Requirements
nameThe order nameStringX
priorityThe order priorityNumber (integer)X
Must be between 1 and 3
demand1A description of the vehicle type 1 capacity used by the orderString
demand2A description of the vehicle type 2 capacity used by the orderString
demand3A description of the vehicle type 3 capacity used by the orderString
addressThe order addressObject (Location)X
time_of_serviceThe time the vehicle must stop to serve the orders, in minutes, default 10Number (float)
Must be non-negative
time_windowsUp to 2 time window constraintsArray of Objects (Time window)
Length must be between 1 and 2
Time windows must be ordered and non-overlapping
notesThe order notesString
arrivalThe time of the day the vehicle reaches the route element, in minutes from midnightNumber (float)X
Must be non-negative
wait_timeThe time the driver has to wait before being allowed to serve the order, in minutesNumber (float)X
Must be non-negative
departureThe time of the day the driver leaves the route element, in minutes from midnightNumber (float)X
Must be non-negative
statusThe order status: 0 if successfully closed, 1 if closed with error, -1 if openNumber (integer)X
Must be between -1 and 1

Example:

{
    "name": "Cleaning 1",
    "priority": 1,
    "demand1": "10 kg",
    "demand3": "15 bottles",
    "address": {"lat": 2.34, "lon": 2.34, "street": "14, 16th Street", "city": "New York", "country": "United States"},
    "time_of_service": 30,
    "time_windows": [
	{
	    "earliest": 540,
	    "latest": 720
	},
	{
	    "earliest": 900,
	    "latest": 1140
	}
    ],
    "notes": "Second floor, door on the left",
    "arrival": 600,
    "wait_time": 0,
    "departure": 630,
    "status": 0
}

3.12) Plan tracking details

The details for a given plan, to be transmitted to the mobile app

Format:

Name Description Type Is required Requirements
tracking_frequencyThe driver tracking frequency, in minutesNumber (float)X
Must be non-negative
idThe plan unique identifierNumber (integer)X
Must be non-negative
nameThe plan nameStringX
dateThe plan dateStringX
Must be a valid date, formatted as YYYY/MM/DD
departureThe driver departure time, in minutes from midnightNumber (float)X
Must be non-negative
ordersAn ordered array of ordersArray of Objects (Order details)X
restThe driver rest period, if presentObject (Rest response)
last_legThe data about the depot reentry legObject (Last leg data)X

Example:

{
    "tracking_frequency": 5,
    "id": 42,
    "name": "My delivery plan",
    "date": "2014/02/03",
    "departure": 550,
    "orders": [
	{
	    "name": "Cleaning 1",
	    "priority": 1,
	    "demand1": "10 kg",
	    "demand3": "15 bottles",
	    "address": {"lat": 2.34, "lon": 2.34, "street": "14, 16th Street", "city": "New York", "country": "United States"},
	    "time_of_service": 30,
	    "time_windows": [
		{
		    "earliest": 540,
		    "latest": 720
		},
		{
	    	    "earliest": 900,
		    "latest": 1140
		}
	    ],
	    "notes": "Second floor, door on the left",
	    "arrival": 600,
	    "wait_time": 0,
	    "departure": 630,
	    "status": 0
	},
	{
	    "name": "Cleaning 2",
	    "priority": 2,
	    "demand1": "10 kg",
	    "demand2": "20 liters",
	    "address": {"lat": 3.45, "lon": 3.45, "street": "1, 43th Street", "city": "New York", "country": "United States"},
	    "time_of_service": 120,
	    "time_windows": [
		{
	    	    "earliest": 1000,
		    "latest": 1140
		}
	    ],
	    "arrival": 980,
	    "wait_time": 20,
	    "departure": 1120,
	    "status": -1
	}
    ],
    "rest":
    {
	"rest_type": 1,
	"order_after_rest": "Cleaning 2",
	"rest_start": 834.5,
	"rest_end": 894.5,
	"rest_travel_time": 34.8333,
	"rest_distance": 32937,
	"rest_wait_time": 0
    },
    "last_leg":
    {
	"arrival": 1200,
	"leg_travel_time": 14.6667,
	"leg_distance": 10905
    }
}

4) VRP API

4.1) Optimization

The Optimization API allows to directly perform an optimization on user-supplied data, without using the vehicle and order data stored on Routist. All the data relative to the optimization is sent with the request, and all the data about the optimization routes can be recovered by the API.

4.1.1) optimize

Description:

Launches a plan optimization by supplying a list of orders and vehicles.

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/vrp/optimize?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
vehiclesThe list of vehicles that can be used to serve the orders, or previously uploaded vehicle namesArray of Object (Vehicle) or StringsX
Length must be between 0 and 30
ordersThe list of orders to be servedArray of Objects (Order)X
Length must be between 0 and 1000
plan_distance_unitThe distance unit used by the plan, which can be kilometers or miles, default kmString
Must be one of: km, mi
save_plan_nameAfter the optimization, saves the plan with the given name.StringX

Request Example:

{
    "vehicles": [
	{
	    "driver": "Marco",
	    "capacity1": 42,
	    "cost_hourly": 5,
	    "cost_kilometric": 0.5,
	    "cost_activation": 10,
	    "start_time": 480,
	    "finish_time": 1080,
	    "flexible_departure": true,
	    "rest": {
		"time_window": {
		    "earliest": 720,
		    "latest": 840
		},
		"duration": 45
	    },
	    "work_up_to": 480,
	    "drive_up_to": 360,
	    "start_address": {"lat": 1.23, "lon": 1.23},
	    "end_address": {"lat": 4.56, "lon": 4.56},
	    "skills": ["Cleaning", "Plumbing"]
	},
	{
	    "driver": "John",
	    "capacity1": 100,
	    "capacity2": 200,
	    "capacity3": 300,
	    "start_time": 480,
	    "finish_time": 1080,
	    "work_up_to": 480,
	    "drive_up_to": 360,
	    "overtime": true,
	    "cost_hourly_overtime": 10,
	    "work_up_to_overtime": 120,
	    "start_address": {"lat": 1.23, "lon": 1.23}
	}
    ],
    "orders": [
	{
	    "name": "Cleaning 1",
	    "address": {"lat": 2.34, "lon": 2.34},
	    "demand1": 10,
	    "demand3": 15,
	    "time_of_service": 30,
	    "time_windows": [
		{
		    "earliest": 540,
		    "latest": 720
		},
		{
	    	    "earliest": 900,
		    "latest": 1140
		}
	    ],
	    "priority": 1,
	    "required_driver_name": "Marco",
	    "skills": ["Cleaning"]
	},
	{
	    "name": "Cleaning 2",
	    "address": {"lat": 3.45, "lon": 3.45},
	    "time_of_service": 60
	}
    ],
    "plan_distance_unit": "km",
    "save_plan_name": "My plan"
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString
idThe optimization identifier, used to query the status of the optimization runNumber (integer)
Must be non-negative

Response Example:

{
    "status": "success",
    "id": 42
}

4.1.2) optimization_status

Description:

Queries the optimization result of a plan

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/vrp/optimization_status?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe optimization identifierNumber (integer)X
Must be non-negative

Request Example:

{
    "id": 42
}

Response Format:

Name Description Type Is required Requirements
statusThe optimization statusStringX
Must be one of: error, running, optimized
errorThe error message, if presentString
routesThe list of plan routes, present if status is optimizedArray of Objects (Route)
unassignedThe list of orders names which have not been assigned to any route, present if status is optimizedArray of Strings

Response Example:

{
    "status": "optimized",
    "routes": [
	{
	    "driver_name": "John",
	    "duration": 210.833,
	    "time_on_the_road": 50.8333,
	    "worked_time": 210.833,
	    "distance": 36322,
	    "forward_time_slack": 0,
	    "departure": 580,
	    "route": [
		{
		    "name": "Order 2090",
		    "leg_travel_time": 2.66667,
		    "leg_distance": 1292,
		    "arrival": 542.667,
		    "wait_time": 0,
		    "departure": 582.667
		},
		{
		    "name": "Order 2097",
		    "leg_travel_time": 20.5,
		    "leg_distance": 15736,
		    "arrival": 603.167,
		    "wait_time": 0,
		    "departure": 673.167
		},
		{
		    "name": "Order 2096",
		    "leg_travel_time": 4.66667,
		    "leg_distance": 2398,
		    "arrival": 677.833,
		    "wait_time": 0,
		    "departure": 727.833
		}
	    ],
	    "last_leg":
	    {
		"arrival": 750.833,
		"leg_travel_time": 23,
		"leg_distance": 16896
	    }
	},
	{
	    "driver_name": "Richard",
	    "duration": 489.167,
	    "time_on_the_road": 99.1667,
	    "worked_time": 429.167,
	    "distance": 76876,
	    "forward_time_slack": 0,
	    "departure": 540,
	    "route": [
		{
		    "name": "Order 2098",
		    "leg_travel_time": 14.1667,
		    "leg_distance": 10914,
		    "arrival": 554.167,
		    "wait_time": 0,
		    "departure": 644.167
		},
		{
		    "name": "Order 2100",
		    "leg_travel_time": 35.5,
		    "leg_distance": 22120,
		    "arrival": 679.667,
		    "wait_time": 0,
		    "departure": 799.667
		},
		{
		    "name": "Order 2099",
		    "leg_travel_time": 0,
		    "leg_distance": 0,
		    "arrival": 894.5,
		    "wait_time": 0,
		    "departure": 1014.5
		}
	    ],
	    "rest":
	    {
		"rest_type": 1,
		"order_after_rest": "Order 2099",
		"rest_start": 834.5,
		"rest_end": 894.5,
		"rest_travel_time": 34.8333,
		"rest_distance": 32937,
		"rest_wait_time": 0
	    },
	    "last_leg":
	    {
		"arrival": 1029.17,
		"leg_travel_time": 14.6667,
		"leg_distance": 10905
	    }
	}
    ],
    "unassigned": [ "Order 2092", "Order 2093" ]
}

4.1.3) optimize_plan

Description:

Starts the optimization for the given plan, with the currently assigned vehicles and orders

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/vrp/optimize_plan?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative

Request Example:

{
    "id": 42
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString
idThe optimization identifier, used to query the status of the optimization runNumber (integer)
Must be non-negative

Response Example:

{
    "status": "success",
    "id": 42
}
An optimization run can also be executed on a plan stored on the server. This function differs from the api_optimization#optimize function, where all the data about the vehicles and orders is transmitted along with the request, and does not need to be stored on the server beforehand.
To query the progress and result of the optimization run, use the optimization_status function of the VRP API.

5) Data API

5.1) Vehicles

The Vehicle API allows CRUD operations on the vehicle list stored on the server. The following functions are used to create, inspect, update or delete the list of vehicles to be used in the plans.

5.1.1) create

Description:

Creates a new vehicle

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/data/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
driverDriver nameStringX
Length must be between 1 and 40
Must be unique
emailDriver emailString
Must be a valid email
capacity1Type 1 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity2Type 2 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity3Type 3 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
cost_hourlyHourly cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_kilometricKilometric cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_activationActivation cost for the vehicle, if presentNumber (float)
Must be non-negative
start_timeDriver start time in minutes from midnight, default 540 (09:00 AM)Number (integer)
Must be non-negative
finish_timeDriver finish time in minutes from midnight, default 1080 (06:00 PM)Number (integer)
Must be non-negative
Must be greater or equal than start_time
flexible_departureAllows the vehicle to leave the departure after the start time, default true. See noteBoolean
restThe driver launch rest time, if required, otherwise nullObject (Rest constraint) or null
work_up_toThe maximum driver working time for the day, in minutes, if presentNumber (integer)
Must be non-negative
drive_up_toThe maximum driver driving time for the day, in minutes, if presentNumber (integer)
Must be non-negative
overtimeIf true, then the driver is allowed to work overtimeBoolean
If true, then also cost_hourly_overtime must be present
cost_hourly_overtimeHourly overtime cost for the vehicle, if presentNumber (float)
Must be non-negative
work_up_to_overtimeThe maximum driver working overtime for the day in addition to the standard work_up_to value, in minutes, if presentNumber (integer)
Must be non-negative
start_addressThe vehicle starting point locationObject (Location)X
end_addressThe vehicle end point location. If not supplied, the vehicle will return to the start_addressObject (Location)
skillsThe skills supplied by the driver. Skills are case-insensitiveArray of Strings
subfleetsA list of subfleets the vehicle is belonging toArray of Strings

Request Example:

{
    "driver": "David",
    "capacity1": 42,
    "capacity2": 0,
    "capacity3": 0,
    "cost_hourly": 5,
    "cost_kilometric": 0.5,
    "cost_activation": 10,
    "start_time": 480,
    "finish_time": 1080,
    "flexible_departure": true,
    "rest": {
	"time_window": {
	    "earliest": 720,
	    "latest": 840
	},
	"duration": 45
    },
    "work_up_to": 480,
    "drive_up_to": 360,
    "overtime": true,
    "cost_hourly_overtime": 10,
    "work_up_to_overtime": 120,
    "start_address": {"lat": 1.23, "lon": 1.23},
    "end_address": {"lat": 4.56, "lon": 4.56},
    "skills": ["Cleaning", "Plumbing"]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.1.2) get

Description:

Gets the list of vehicles

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/data/vehicles?email=account_email&api_key=account_key

Request Format:

No additional data must be supplied

Response Format:

Name Description Type Is required Requirements
vehiclesAn array of vehiclesArray of Objects (Vehicle)X

Response Example:

{
    "vehicles": [
	{
	    "driver": "David",
	    "capacity1": 42,
	    "cost_hourly": 5,
	    "cost_kilometric": 0.5,
	    "cost_activation": 10,
	    "start_time": 480,
	    "finish_time": 1080,
	    "flexible_departure": true,
	    "rest": {
		"time_window": {
		    "earliest": 720,
		    "latest": 840
		},
		"duration": 45
	    },
	    "work_up_to": 480,
	    "drive_up_to": 360,
	    "overtime": true,
	    "cost_hourly_overtime": 10,
	    "work_up_to_overtime": 120,
	    "start_address": {"lat": 1.23, "lon": 1.23},
	    "end_address": {"lat": 4.56, "lon": 4.56},
	    "skills": ["Cleaning", "Plumbing"]
	},
	{
	    "driver": "John",
	    "capacity1": 100,
	    "capacity2": 200,
	    "capacity3": 300,
	    "start_time": 480,
	    "finish_time": 1080,
	    "work_up_to": 480,
	    "drive_up_to": 360,
	    "start_address": {"lat": 1.23, "lon": 1.23}
	}
    ]
}

5.1.3) update

Description:

Updates a vehicle

HTTP Method:

PUT

URL:

https://www.routist.com/api/v1/data/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
driverDriver nameStringX
Length must be between 1 and 40
Must be unique
emailDriver emailString
Must be a valid email
capacity1Type 1 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity2Type 2 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
capacity3Type 3 capacity for the vehicle (default infinite)Number (float)
Must be non-negative
cost_hourlyHourly cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_kilometricKilometric cost for the vehicle, if presentNumber (float)
Must be non-negative
cost_activationActivation cost for the vehicle, if presentNumber (float)
Must be non-negative
start_timeDriver start time in minutes from midnight, default 540 (09:00 AM)Number (integer)
Must be non-negative
finish_timeDriver finish time in minutes from midnight, default 1080 (06:00 PM)Number (integer)
Must be non-negative
Must be greater or equal than start_time
flexible_departureAllows the vehicle to leave the departure after the start time, default true. See noteBoolean
restThe driver launch rest time, if required, otherwise nullObject (Rest constraint) or null
work_up_toThe maximum driver working time for the day, in minutes, if presentNumber (integer)
Must be non-negative
drive_up_toThe maximum driver driving time for the day, in minutes, if presentNumber (integer)
Must be non-negative
overtimeIf true, then the driver is allowed to work overtimeBoolean
If true, then also cost_hourly_overtime must be present
cost_hourly_overtimeHourly overtime cost for the vehicle, if presentNumber (float)
Must be non-negative
work_up_to_overtimeThe maximum driver working overtime for the day in addition to the standard work_up_to value, in minutes, if presentNumber (integer)
Must be non-negative
start_addressThe vehicle starting point locationObject (Location)
end_addressThe vehicle end point location. If not supplied, the vehicle will return to the start_addressObject (Location)
skillsThe skills supplied by the driver. Skills are case-insensitiveArray of Strings
subfleetsA list of subfleets the vehicle is belonging toArray of Strings

Request Example:

{
    "driver": "David",
    "capacity3": 100
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.1.4) delete

Description:

Deletes vehicles

HTTP Method:

DELETE

URL:

https://www.routist.com/api/v1/data/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
namesA list of vehicle namesArray of StringsX

Request Example:

{
    "names": ["David", "John"]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.2) Plans

The Plans API is meant to perform basic CRUD operations on the plans stored in the database. It allows creating, listing, updating and deleting the plan basic parameters. Only open plans are affected by the API. To handle the list of vehicles and orders contained in the plans, use the Plan vehicles API and the Plan orders API.

5.2.1) create

Description:

Creates a new plan

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/data/plans?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
nameThe plan nameStringX
Length must be between 1 and 40
dateThe plan dateString or null
Must be a valid date, formatted as yyyy/mm/dd or must be null
distance_unitThe distance unit used by the plan, which can be kilometers or miles, default kmString
Must be one of: km, mi

Request Example:

{
    "name": "My delivery plan",
    "date": "2013/11/20",
    "distance_unit": "km"
}

Response Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative

Response Example:

{
    "id": 42
}

5.2.2) get

Description:

Gets the list of plans

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/data/plans?email=account_email&api_key=account_key

Request Format:

No additional data must be supplied

Response Format:

Name Description Type Is required Requirements
plansAn array of plansArray of Objects (Plan)X

Response Example:

{
    "plans": [
	{
	    "id": 42,
	    "name": "Delivery plan 1",
	    "date": "2013/11/20",
	    "distance_unit": "km"
	},
	{
	    "id": 43,
	    "name": "Delivery plan 2",
	    "date": "2013/10/04",
	    "distance_unit": "mi"
	}
    ]
}

5.2.3) update

Description:

Updates a plan

HTTP Method:

PUT

URL:

https://www.routist.com/api/v1/data/plans?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idPlan id to be updatedNumber (integer)X
Must be non-negative
nameThe plan nameString
Length must be between 1 and 40
dateThe plan dateString or null
Must be a valid date, formatted as yyyy/mm/dd or must be null
distance_unitThe distance unit used by the plan, which can be kilometers or miles, default kmString
Must be one of: km, mi

Request Example:

{
    "id": 42,
    "date": "2014/05/25"
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.2.4) delete

Description:

Deletes a plan

HTTP Method:

DELETE

URL:

https://www.routist.com/api/v1/data/plans?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idsA list of plan idsArray of Numbers (integer)X

Request Example:

{
    "ids": [1, 4, 9, 16]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.3) Plan vehicles

The Plan vehicles API is used to get or update the list of vehicles to be used inside a stored plan.

5.3.1) vehicles_add

Description:

Adds new vehicles to the plan, or updates them if already present in the plan

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/data/plans/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative
vehicle_namesAn array of vehicle namesArray of StringsX

Request Example:

{
    "id": 42,
    "vehicle_names": ["David", "John"]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.3.2) vehicles_get

Description:

Gets the plan vehicle list

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/data/plans/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative

Request Example:

{
    "id": 42
}

Response Format:

Name Description Type Is required Requirements
vehicle_namesAn array of vehicle namesArray of StringsX

Response Example:

{
    "vehicle_names": ["David", "John"]
}

5.3.3) vehicles_delete

Description:

Deletes vehicles from a plan

HTTP Method:

DELETE

URL:

https://www.routist.com/api/v1/data/plans/vehicles?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative
vehicle_namesAn array of vehicle namesArray of StringsX

Request Example:

{
    "id": 42,
    "vehicle_names": ["David", "John"]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.4) Plan orders

The Plan orders API is used to get or update the list of orders to be used inside a stored plan.

5.4.1) orders_add

Description:

Adds new orders to the plan

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/data/plans/orders?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative
ordersA list of ordersArray of Objects (Order)X

Request Example:

{
    "id": 42,
    "orders": [
	{
	    "name": "Cleaning 1",
	    "address": {"lat": 2.34, "lon": 2.34},
	    "demand1": 10,
	    "demand3": 15,
	    "time_of_service": 30,
	    "time_windows": [
		{
		    "earliest": 540,
		    "latest": 720
		},
		{
	    	    "earliest": 900,
		    "latest": 1140
		}
	    ],
	    "priority": 1,
	    "required_driver_name": "David",
	    "skills": ["Cleaning"]
	},
	{
	    "name": "Cleaning 2",
	    "address": {"lat": 3.45, "lon": 3.45},
	    "time_of_service": 60,
	    "notes": "Third floor"
	}
    ]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.4.2) orders_get

Description:

Gets the plan order list

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/data/plans/orders?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative

Request Example:

{
    "id": 42
}

Response Format:

Name Description Type Is required Requirements
ordersA list of ordersArray of Objects (Order)X

Response Example:

{
    "orders": [
	{
	    "name": "Cleaning 1",
	    "address": {"lat": 2.34, "lon": 2.34},
	    "demand1": 10,
	    "demand2": 0,
	    "demand3": 15,
	    "time_of_service": 30,
	    "time_windows": [
		{
		    "earliest": 540,
		    "latest": 720
		},
		{
	    	    "earliest": 900,
		    "latest": 1140
		}
	    ],
	    "priority": 1,
	    "required_driver_name": "David",
	    "skills": ["Cleaning"]
	},
	{
	    "name": "Cleaning 2",
	    "address": {"lat": 3.45, "lon": 3.45},
	    "demand1": 0,
	    "demand2": 0,
	    "demand3": 0,
	    "time_of_service": 60,
	    "priority": 1,
	    "skills": [],
	    "notes": "Third floor"
	}
    ]
}

5.4.3) orders_delete

Description:

Deletes orders from a plan

HTTP Method:

DELETE

URL:

https://www.routist.com/api/v1/data/plans/orders?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative
order_namesA list of order namesArray of StringsX

Request Example:

{
    "id": 42,
    "order_names": ["Plumbing 1", "Cleaning 1"]
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

5.4.4) orders_add_recurrent

Description:

Imports into the plan all the orders scheduled for the day of the plan. Can only be called on a plan which has been supplied with a date parameter

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/data/plans/orders_add_recurrent?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
idThe plan unique identifierNumber (integer)X
Must be non-negative

Request Example:

{
    "id": 42
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

6) Tracking API

The Tracking API is used by the driver personal mobile devices to transmit the current driver status, or fetch information about the orders schedule. The authentication for the Tracking API is done using the driver email and token, which can be requested by the new_token method.

6.1) Methods

6.1.1) new_token

Description:

Requests a new token, to be sent to the driver email

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/tracking/new_token

Request Format:

Name Description Type Is required Requirements
emailThe user emailStringX
Must be a valid email

Request Example:

{
    "email": "driver_email@company.com"
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}
The method returns an API error with error_code 101 in case the supplied email does not exist.

6.1.2) plans

Description:

Gets the list of plans for the day

HTTP Method:

GET

URL:

https://www.routist.com/api/v1/tracking/plans?email=account_email&api_key=account_key

Request Format:

No additional data must be supplied

Response Format:

Name Description Type Is required Requirements
plansThe list of plansArray of Objects (Plan tracking details)X

Response Example:

{
    "plans": [
	{
	    "tracking_frequency": 5,
	    "id": 42,
	    "name": "My delivery plan",
	    "date": "2014/02/03",
	    "departure": 550,
	    "orders": [
		{
		    "name": "Cleaning 1",
		    "priority": 1,
		    "demand1": "10 kg",
		    "demand3": "15 bottles",
		    "address": {"lat": 2.34, "lon": 2.34, "street": "14, 16th Street", "city": "New York", "country": "United States"},
		    "time_of_service": 30,
		    "time_windows": [
			{
			    "earliest": 540,
			    "latest": 720
			},
			{
	    		    "earliest": 900,
			    "latest": 1140
			}
		    ],
		    "notes": "Second floor, door on the left",
		    "arrival": 600,
		    "wait_time": 0,
		    "departure": 630,
		    "status": 0
		},
		{
		    "name": "Cleaning 2",
		    "priority": 2,
		    "demand1": "10 kg",
		    "demand2": "20 liters",
		    "address": {"lat": 3.45, "lon": 3.45, "street": "1, 43th Street", "city": "New York", "country": "United States"},
		    "time_of_service": 120,
		    "time_windows": [
			{
	    		    "earliest": 1000,
			    "latest": 1140
			}
		    ],
		    "arrival": 980,
		    "wait_time": 20,
		    "departure": 1120,
		    "status": -1
		}
	    ],
	    "rest":
	    {
		"rest_type": 1,
		"order_after_rest": "Cleaning 2",
		"rest_start": 834.5,
		"rest_end": 894.5,
		"rest_travel_time": 34.8333,
		"rest_distance": 32937,
		"rest_wait_time": 0
	    },
	    "last_leg":
	    {
		"arrival": 1200,
		"leg_travel_time": 14.6667,
		"leg_distance": 10905
	    }
	}
    ]
}

6.1.3) status

Description:

Updates the driver status with respect to a given order

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/tracking/status?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
plan_idThe plan unique identifierNumber (integer)X
Must be non-negative
order_nameThe order nameStringX
statusThe new order statusStringX
Must be one of: success, error, open
status_noteAn additional note for the statusString
unixtimeThe UNIX time the status is updatedNumber (float)X

Request Example:

{
    "plan_id": 42,
    "order_name": "Cleaning 1",
    "status": "success",
    "status_note": "Client asked for a second delivery next week",
    "unixtime": 1385131838
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}

6.1.4) position

Description:

Updates the driver position

HTTP Method:

POST

URL:

https://www.routist.com/api/v1/tracking/position?email=account_email&api_key=account_key

Request Format:

Name Description Type Is required Requirements
latLocation latitudeNumber (float)X
lonLocation longitudeNumber (float)X
accuracyCoordinates accuracyNumber (float)X
Must be non-negative
unixtimeThe UNIX time the position is updatedNumber (float)X

Request Example:

{
    "lat": 6.78,
    "lon": 7.89,
    "accuracy": 10,
    "unixtime": 1385131838
}

Response Format:

Name Description Type Is required Requirements
statusThe request statusStringX
Must be one of: success, error
error_codeThe error code, if presentNumber (integer)
errorThe error message, if presentString

Response Example:

{
    "status": "success"
}