NAV Navbar
shell

Introduction

This document is the official reference for the OptimoRoute Web Service Application Programming Interface (WS API).

Our Web Service API is HTTP based

The methods to retrieve data from our Web Service (WS) API require an HTTP GET request method.

The methods that submit, change, or destroy data require a POST request method.

The API methods will return an error if you do not make your request with the correct HTTP method.

We use JSON for structured data exchange

Our API uses the JSON (JavaScript Object Notation) format.

More information about JSON and how it works can be found here: http://json.org/ and here: http://en.wikipedia.org/wiki/JSON.

There are many readily available libraries to convert to and from the JSON format both for popular and for more esoteric programming languages.

SSL is required

Using SSL (https) is required to avoid passing both the authentication key and potentially confidential data in clear text over the web.

Limited number of concurrent requests

The maximum number of concurrent web service API requests for one account or for one IP address is limited to 5.

General error codes

The following error codes are applicable to all API operations:

Error Code Description
AUTH_KEY_MISSING the authentication key is missing
AUTH_KEY_UNKNOWN a wrong authentication key was supplied
MALFORMED_REQUEST something is wrong with the input
ERR_MISSING_MAND_FIELD one of the mandatory fields is missing
ERR_INVALID_PARAM_FORMAT one of the specified fields is not in a valid format
ERR_TOO_MANY_CONNECTIONS there are too many concurrent requests
ERR_INTERNAL an internal server error occur

There are also error codes specific that are described in the Error and Warning Codes section of each method.

Error codes with bulk operations

For bulk operations, there are multiple failure modes. For example, if performing a bulk operation on orders:

Allow for additional fields in the response messages

Additional fields might be added to the JSON response messages in the future, so your client code should ignore additional fields.  

Authentication

The OptimoRoute Web Service API authentication key parameter is required with all API requests, in addition to all the standard parameters.

To enable the API and generate the API key please log into the OptimoRoute web application. In the Administration section select Settings -> WS API and enable the API. The API key will be generated for you.

The Web Service API is also available during the free trial period.

Data Objects

Some endpoints in the API share definitions of objects that are sent in the request and response.

Order Object

Example Order Object

{
  "orderNo": "ORD001",
  "date": "2018-11-12",
  "duration": 60,
  "priority": "M",
  "type": "T",
  "load1": 1,
  "load2": 0,
  "load3": 0,
  "load4": 0,
  "assignedTo": {"externalId": "DRV001", "serial": "001"},
  "location": {
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationName": "Green Cross Pharmacy North End",
    "latitude": 42.365142,
    "longitude": -71.052882,
    "checkInTime": 0,
    "notes": ""
  },
  "timeWindows": [{
      "twFrom": "11:00",
      "twTo": "17:00"
  }],
  "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
  "allowedDates": {},
  "skills": ["SK001"],
  "vehicleFeatures": [],
  "notes": "",
  "email": "john.doe@example.com",
  "phone": "",
  "customField1": "",
  "customField2": "",
  "customField3": "",
  "customField4": "",
  "customField5": "",
  "notificationPreference": "email"
}
Property Type Description
orderNo string A user specified order identifier, also displayed in the web application. Orders are matched by this identifier. It can also be used for deleting and retrieving orders via the WS API.
relatedOrderNo string or null orderNo of the related order. Used to link pickups and deliveries in situations where goods are transported directly from one customer location to the another customer location.
When creating orders, the relationship should be specified only on the second order that is created (the first order has to already exist in the system so that it can be referenced).
The default value is null, which means the order is not related to any other pickup/delivery.
date date (string) Delivery date.
YYYY-MM-DD format, for example 2013-12-20.
location location object Delivery/Service location. See Location Object.
type string enum Order type: D (delivery), P (pickup) or T (task).
duration integer The time in minutes required to unload the goods or perform a task at the given location.
timeWindows list of time windows List of time windows when the order can be serviced.
Each time window is an object with twFrom and twTo fields. Both times are in 24-hour (military) clock format, in the range from 00:00 to 23:59.
twFrom specifies the earliest time allowed to begin the service (if the driver arrives too early, they will be forced to wait). twTo specifies the deadline to end the service.
Example:
[{"twFrom": "10:00", "twTo": "14:00"}].
Default is [] meaning no time windows.
allowedWeekdays list of strings Restricts days of the week when the order can be scheduled:
sun, mon, tue, wed, thu, fri, sat.
For example if the order can be scheduled on Monday or Tuesday the value should be:
["mon", "tue"].
By default all days of the week are allowed.
allowedDates daterange object Restricts the dates when the order can be scheduled.
Daterange is specified as an object with from and to fields, for example:
{"from": "2018-06-01", "to": "2018-07-01"}
Default is an empty object {} meaning no restriction.
assignedTo object or null An object with string properties serial or externalId that uniquely identifies the Driver that this Order must be assigned to. Example: {"serial": "102"} or {"externalId": "444"}. Setting this field forces this Order to be served by the specified Driver. A null value means no assignment, which is the default.
priority string Order priority, by default M. Values can be:
L – Low
M – Medium
H – High
C – Critical
High priority orders are scheduled earlier and are less likely to be left unscheduled if not all orders can be serviced.
load1 integer The load requirements of the order, i.e. how many load units (Number of boxes, Kilos, Pounds, Liters etc) should be delivered.
The meaning of this entry depends on the provided configuration of load/capacity constraints.
Default value is 0.
load2 integer See load1.
load2 integer See load1.
load3 integer See load1.
vehicleFeatures list of strings The vehicle features used to differentiate some Vehicles from the others. The required vehicle features are defined as a list of vehicle feature codes. Default value is an empty list [].
skills list of strings The driver skills used to differentiate some Drivers from the others. The required skills are defined as a list of skill codes. Default value is an empty list [].
notes string The optional note that will accompany the driver’s instructions. Notes do not affect the optimization process. A free form string.
customField1 string Value that will be saved in custom field #1, default empty.
customField2 string Value that will be saved in custom field #2, default empty.
customField3 string Value that will be saved in custom field #3, default empty.
customField4 string Value that will be saved in custom field #4, default empty.
customField5 string Value that will be saved in custom field #5, default empty.
email string Customer email. If enabled, order notifications can be sent to that email. Default empty.
phone string Customer phone number. Default empty.
notificationPreference string email Defines the delivery method for order tracking notifications for this order. Notifications will only be sent if this account has order tracking configured.
Allowed values:
email – send notifications to email address specified in the email field
dont_notify – don't send notifications
Defaults to email.

Location Object

Location Object example with GPS coordinates:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "latitude": 39.9892,
  "longitude": -83.0054,
  "locationName": "Colorado pharmacy 033",
  "locationNo": "COL033",
  "notes": "GATE CODE 4412",
  "checkInTime": 3
}
Property Type / Default Description
locationNo string The unique identifier for the given location.
locationName string Location name.
address string The full address including the country, for example 393 Hanover St, Boston, MA 02113, US
latitude decimal Location latitude.
longitude decimal Location longitude.
checkInTime integer Default value is 0. Minimum waiting time at the location (in minutes). Upon arrival at the location the driver will spend at least checkInTime minutes before starting the service of one or several consecutive orders at the same location.
Example: if we have 3 orders at the same location:
  • A: duration 10min, check in time 15min
  • B: duration 5min, check in time 15min
  • C: duration 20min, check in time 15min
If one driver serves all three orders consecutively the driver would arrive at the location, spend 15 minutes at the location (for example parking and checking in) and then start servicing orders A, B and C. Total time at the location would be 50min = 15min (shared duration) + 10min (order A) + 5min (order B) + 20min (order C).
notes string Optional notes related to this location.

Create Order

Creates a new order in the system or updates an existing order.

HTTP Request

POST https://api.optimoroute.com/v1/create_order

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_order?key=AUTH_KEY'

Parameters

Request body example:

{
  "operation": "CREATE",
  "orderNo": "ORD001",
  "type": "D",
  "date": "2014-10-14",
  "location": {
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationNo": "LOC001",
    "locationName": "Green Cross Pharmacy North End",
    "acceptPartialMatch": true
  },
  "duration": 20,
  "twFrom": "10:00",
  "twTo": "10:59",
  "load1": 10,
  "load2": 25,
  "vehicleFeatures": ["FR"],
  "skills": ["SK001", "SK002"],
  "notes": "Deliver at back door"
}

In addition to properties from the Order Object, the following properties are available:

Property Type Description
operation string enum CREATE – creates a new order in the system.

UPDATE – updates an existing order in the system. If the orderNo does not exist the system will return an error.

SYNC – recommended when the end goal is to make sure orders are reflected in OptimoRoute. If this is a new order, we will create it. If there is an existing order in the system, it will be updated. SYNC makes a clean sync-up of order data. Whatever we have on this order will be replaced by the data you send us on SYNC.

MERGE – used to only update specific fields and leave all the other fields unchanged (for example if some fields were manually edited in OptimoRoute and should not be updated). If this is a new order, we will create it. If there is an existing order in the system, it will be updated.
acceptDuplicateOrderNo boolean If set to true the system will accept orders with orderNo that already exists in the system. When false or not specified, the system will return an error.
twFrom time (string) Deprecated, please use the timeWindows field; ignored if timeWindows is set.

The earliest time allowed to begin the service (if the driver arrives too early, they will be forced to wait).
24-hour (military) clock format, for example: 16:00
The valid values range from 00:00 to 23:59.
twTo time (string) Deprecated, please use the timeWindows field; ignored if timeWindows is set.

The deadline to end the service.
24-hour (military) clock format, for example 17:00
The valid values range from 00:00 to 23:59.

The operation property is mandatory. When operation is specified as UPDATE, only orderNo is mandatory, otherwise mandatory properties are orderNo, date, type, duration and location.

Location Object

Location Object example specifying address to be geocoded and accepting any result:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "acceptPartialMatch": true,
  "acceptMultipleResults": true
}

In addition to properties from the Location Object, the following properties are available:

Property Type Description
acceptMultipleResults boolean Used only if a new location is created by geocoding the address field. If false or not specified, the system will not accept the geocoded addresses where several results matching the provided address have been found and an error will be raised.
acceptPartialMatch boolean Used only if a new location is created by geocoding the address field. If false or not specified, the system will not accept the geocoded addresses that were only a partial match (lower geocoding confidence) and an error will be raised.

A location is defined by one of the following:

Response

Response to example request:

{
  "success": true,
  "location": {
    "notes": "",
    "longitude": -71.0528824,
    "locationName": "Green Cross Pharmacy North End",
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "latitude": 42.3651425,
    "checkInTime": 0
  },
  "geocodingResults": [
    [
      "393 Hanover St, Boston, MA 02113, USA",
      42.3651425,
      -71.0528824
    ]
  ]
}
Property Type / Default Description
success
mandatory
boolean
-
true if the order was saved, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).
location
optional
location object
-
The location data for the created order (only if the operation was successful).
geocodingResults
optional
list
-
The list of geocoding results if the location is created from the supplied address.
Each geocoding result is defined as:
[geocodedAddress, latitude, longitude, partialMatchFlag]

Error and Warning Codes

The following error codes are applicable to Create Order method:

Error Code Description
ERR_ORD_EXISTS an order with the specified orderNo already exists in the system (checked only if orderNo field is set)
ERR_RELATED_ORD_MISSING the order with the ID passed in relatedOrderNo does not exist
ERR_RELATED_ORD_MULTIPLE multiple orders with ID passed in relatedOrderNo exist
ERR_RELATED_ORD_LINK order can not be linked to order with ID passed in relatedOrderNo (only pickups and deliveries can be linked)
ERR_DRV_NOT_EXISTS the driver with the serial number passed in assignedTo does not exist
ERR_DRV_MULTIPLE there is more than one driver with the assignedTo serial number
ERR_LOC_NOT_VALID the specified location is not valid
ERR_LOC_GEOCODING the specified address could not be geocoded
ERR_LOC_GEOCODING_MULTIPLE multiple results have been found during geocoding
ERR_LOC_GEOCODING_PARTIAL the geocoder did not return an exact match for the original request
ERR_LOC_NON_EXISTING_LOC the location specified by locationNo does not exist
ERR_LOC_MULTIPLE_LOC multiple locations with specified locationNo have been found
ERR_VF_NOT_EXISTS the vehicle feature does not exist (for one of the codes specified in vehicleFeatures field)
ERR_VF_MULTIPLE multiple vehicle features exist (for one of the codes specified in the vehicleFeatures field)
ERR_SK_NOT_EXISTS the skill does not exist (for one of the codes specified in the skills field)
ERR_SK_MULTIPLE multiple skills exist (for one of the codes specified in skills field)
WAR_LOC_GEOCODING_MULTIPLE multiple results have been found during geocoding (but the order was created because acceptMultipleResults was set to True)
WAR_LOC_GEOCODING_PARTIAL the geocoder did not return an exact match for the original request (but the order was created because acceptPartialMatch was set to True)

Create or Update Orders (bulk)

Create, update or replace one or more orders in the system.

Note that geocoding addresses is not available in this call. The locations for orders must either exist in the system, or be specified via latitude and longitude coordinates. Geocoding is available in Create Order.

HTTP Request

POST https://api.optimoroute.com/v1/create_or_update_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_or_update_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "54913250",
      "date": "2019-03-22",
      "duration": 60,
      "priority": "H",
      "type": "T",
      "assignedTo": {"externalId": "DRV001", "serial": "001"},
      "location": {
        "locationNo": "G402333",
        "address": "393 Hanover St, Boston, MA 02113, USA",
        "locationName": "Green Cross Pharmacy North End",
        "latitude": 42.365142,
        "longitude": -71.052882,
        "checkInTime": 0,
      },
      "timeWindows": [{
        "twFrom": "11:00",
        "twTo": "17:00"
      }],
      "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
      "allowedDates": {},
      "skills": ["SK001"],
      "vehicleFeatures": [],
      "notes": "Notify manager",
      "email": "joe.customer@example.com",
      "phone": "",
      "customField1": "300",
      "notificationPreference": "email"
    },
    {
      "orderNo": "27463225",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "locationNo": "999999999",
      },
    },
    {
      "orderNo": "09463221",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "notes": "",
        "locationNo": "R384892",
        "locationName": "Moe's Southwest Grill",
        "longitude": -71.7520717,
        "latitude": 42.2752323,
        "notes": "Use gate"
      },
    }
  ]
}
Property Type / Default Description
orders
mandatory
list of order objects
-
List of one or more order objects to create, update or replace in the system. At most 500 orders can be specified.

Order Object

In addition to properties from the Order Object, the following properties are available:

Property Type Description
operation string enum MERGE (default) – used to only update specific fields and leave all the other fields unchanged (for example if some fields were manually edited in OptimoRoute and should not be updated). If this is a new order, we will create it. If there is an existing order in the system, it will be updated.

SYNC – recommended when the end goal is to make sure orders are reflected in OptimoRoute. If this is a new order, we will create it. If there is an existing order in the system, it will be updated. SYNC makes a clean sync-up of order data. Whatever we have on this order will be replaced by the data you send us on SYNC.

CREATE – creates a new order in the system. If the orderNo exists the system will return an error.

UPDATE – updates an existing order in the system. If the orderNo does not exist the system will return an error.

Each order object given in orders will result in an order being created, updated or replaced in the system. The exact behavior for each order can be configured via operation in each order object. The default behavior is:

Location Object

See Location Object for all available location properties. Locations can be created or updated.

If locationNo is specified and a matching location exists, that location will be updated. If locationNo does not have any matches, a new location will be created.

If locationNo is not specified and an existing order is updated - the order's location will be updated.

During update, the matched location will be updated with the values given in the object, if any. No properties are mandatory when updating. When updating with SYNC the properties are reset to default, otherwise they keep their existing values.

In cases when a new location is created, the following properties are mandatory: latitude, longitude and one of locationNo, address, locationName.

Response

Response example:

{
  "orders": [
    {
      "success": true,
      "orderNo": "54913250"
    },
    {
      "success": false,
      "code": "ERR_LOC_NON_EXISTING_LOC",
      "message": "The location with the given location number does not exist.",
      "orderNo": "27463225",
      "locationNo": "999999999"
    },
    {
      "success": true,
      "orderNo": "09463221"
    }
  ],
  "success": true
}
Property Type / Default Description
success
mandatory
boolean
-
true if at least one operation was successful, false if all failed
orders
list of order response objects
-
Each order object in the list corresponds to the respective order in the request. See Order Response Object section for more information.

Order Response Object

Property Type / Default Description
success
mandatory
boolean
-
true if the operation succeeded, false if there was an error.
orderNo
optional
string
-
Identifier of the respective order
locationNo
optional
string
-
Identifier of the location if a location-related error happened
code
optional
string
-
A per-order error code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).

Error and Warning Codes

The following per-order error codes are applicable:

Error Code Description
ERR_INVALID_PARAM_FORMAT the specified order is not valid, possibly an order to be created/updated did not exist in the system but could not be created because a mandatory property is missing
ERR_ORD_EXISTS an order with the specified orderNo already exists in the system (only with CREATE plus orderNo)
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found (only with UPDATE plus orderNo)
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_OPT_RUNNING optimization is running for this order
ERR_RELATED_ORD_MISSING the order with the ID passed in relatedOrderNo does not exist
ERR_RELATED_ORD_MULTIPLE multiple orders with ID passed in relatedOrderNo exist
ERR_RELATED_ORD_LINK order can not be linked to order with ID passed in relatedOrderNo (only pickups and deliveries can be linked)
ERR_DRV_NOT_EXISTS the driver specified in assignedTo does not exist
ERR_DRV_MULTIPLE there is more than one driver with the specified assignedTo values
ERR_LOC_NOT_VALID the specified location is not valid, possibly a location to be created/updated did not exist in the system but could not be created because a mandatory property is missing
ERR_LOC_NON_EXISTING_LOC the location specified by locationNo does not exist
ERR_LOC_MULTIPLE_LOC multiple locations with specified locationNo have been found
ERR_VF_NOT_EXISTS the vehicle feature does not exist (for one of the codes specified in vehicleFeatures field)
ERR_VF_MULTIPLE multiple vehicle features exist (for one of the codes specified in the vehicleFeatures field)
ERR_SK_NOT_EXISTS the skill does not exist (for one of the codes specified in the skills field)
ERR_SK_MULTIPLE multiple skills exist (for one of the codes specified in skills field)

Get Orders (bulk)

Retrieves one or more orders from the system.

HTTP Request

POST https://api.optimoroute.com/v1/get_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    }
  ]
}
Property Type / Default Description
orders
mandatory
list of order objects
-
List of order objects to retrieve. Each order object must contain an orderNo property with user-specified identifier of an order. At most 500 orders can be specified.



For flexibility, the call to get_orders can also be done as a HTTP GET request:

GET request example:

curl 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99'
Property Type / Default Description
orderNo
mandatory
string
-
The user-specified identifier of an order; can be repeated to retrieve multiple orders

Response

Response example:

{
  "success": true,
  "orders": [
    {
      "success": true,
      "data": {
        "orderNo": "ORD001",
        "date": "2018-11-12",
        "duration": 60,
        "priority": "M",
        "type": "T",
        "load1": 1,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "assignedTo": {"externalId": "DRV001", "serial": "001"},
        "location": {
          "locationNo": "LOC001",
          "address": "393 Hanover St, Boston, MA 02113, USA",
          "locationName": "Green Cross Pharmacy North End",
          "latitude": 42.365142,
          "longitude": -71.052882,
          "checkInTime": 0,
          "notes": ""
        },
        "timeWindows": [{
            "twFrom": "11:00",
            "twTo": "17:00"
        }],
        "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
        "allowedDates": {},
        "skills": ["SK001"],
        "vehicleFeatures": [],
        "notes": "",
        "email": "",
        "phone": "",
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "notificationPreference": "email"
      }
    },
    {
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD99",
      "success": false
    }
  ]
}
Property Type / Default Description
success
mandatory
boolean
-
true if at least one order was retrieved, false if no orders were retrieved
orders
mandatory
list of order response objects
-
Each order object in the list corresponds to the respective orderNo in the request. See Order Response Object section for more information.

Order Response Object

Property Type / Default Description
success
mandatory
boolean
-
true if the order was retrieved, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).
orderNo
optional
string
-
The orderNo whose retrieval failed (not set if the operation was successful).
data
optional
Order object
-
The retrieved order

Order Object

In case of success, data will be an object with properties listed in Order Object.

The returned type property can additionally be break or depot.

Error and Warning Codes

The following per-order error codes are applicable to Get Orders method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found.
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_INVALID_PARAM_FORMAT this orderNo is not valid

Delete Order

Removes an order from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_order

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_order?key=AUTH_KEY'

Parameters

Request body example:

{
  "orderNo": "ORD001"
}
Property Type / Default Description
orderNo
mandatory
string
-
The user-specified identifier of the order to be deleted.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if order was deleted, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).
planningId
optional
integer
-
The id of the planning process in case optimization is running for this order.

Error and Warning Codes

The following error codes are applicable to Delete Order method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo
ERR_OPT_RUNNING optimization is running for this order

Delete All Orders

Removes all orders and planned routes for the specified date from the system. If no date is set, all orders and routes are removed from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_all_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_all_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "date": "2014-10-14"
}
Property Type / Default Description
date
optional
date (string)
-
Date for which orders and routes will be deleted.
YYYY-MM-DD format, for example 2013-12-20.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if orders were deleted, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).
planningId
optional
integer
-
The id of the planning process in case optimization is running.

Error and Warning Codes

The following error codes are applicable to Delete Order method:

Error Code Description
ERR_OPT_RUNNING optimization is running for this date

Delete Orders (bulk)

Removes one or more orders from the system.

HTTP Request

POST https://api.optimoroute.com/v1/delete_orders

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_orders?key=AUTH_KEY'

Parameters

Request body example:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD999"
    }
  ]
}
Property Type / Default Description
orders
mandatory
list of order objects
-
List of order objects to delete. Each order object must contain an orderNo property with the user-specified identifier of an order. At most 500 orders can be specified.
deleteMultiple
optional
boolean
false
If false, when there are multiple orders matched by one order object, an error will be returned. If true, all the matches will be deleted.

Response

Response example:

{
  "success": true,
  "orders": [
    {
      "orderNo": "ORD001",
      "success": true
    },
    {
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD999",
      "success": false
    }
  ]
}
Property Type / Default Description
success
mandatory
boolean
-
true if at least one order was deleted, false if no orders were deleted.
orders
mandatory
list of delete response objects
-
Each order object in the list corresponds to the respective orderNo in the request. See Delete Response Object section for more information.

Delete Response Object

Property Type / Default Description
success
mandatory
boolean
-
true if deleted, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).
orderNo
mandatory
string
-
The orderNo which was deleted, or whose delete failed.
planningId
optional
integer
-
The id of the planning process in case optimization is running for this order.

Error and Warning Codes

The following per-order error codes are applicable to Delete Orders method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo, but deleteMultiple was set to false
ERR_OPT_RUNNING optimization is running for this order
ERR_INVALID_PARAM_FORMAT this orderNo is not valid

Get Routes

Gets the routes for a specific date.

HTTP Request

GET https://api.optimoroute.com/v1/get_routes

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_routes?key=AUTH_KEY&date=2013-12-20'

Parameters

Property Type / Default Description
date
mandatory
date (string)
-
Queried date.
YYYY-MM-DD format, for example 2013-12-20.
driverSerial
optional
string
-
Optionally filter by Serial number of the Driver.
vehicleRegistration
optional
string
-
Optionally filter by Vehicle registration.
includeRoutePolyline
optional
boolean
false
Optional property to include route polyline in the output. This polyline can be used to display the route on the map. The polyline is a list of coordinates encoded with Encoded Polyline Algorithm.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the query was successful, false if there was an error.
routes
mandatory
list of route objects
[]
List of routes matching the query.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).

Route Object

Property Type / Default Description
success
mandatory
boolean
-
true if the query was successful, false if there was an error.
driverSerial
mandatory
string
-
The serial number assigned to the driver.
driverName
mandatory
string
-
The driver’s name.
vehicleRegistration
mandatory
string
-
Vehicle registration.
vehicleLabel
mandatory
string
-
Vehicle label.
duration
mandatory
integer
-
Route duration in minutes.
distance
mandatory
decimal
-
Route distance in kilometers.
load1
mandatory
integer
0
Route load #1.
load2
mandatory
integer
0
Route load #2.
load3
mandatory
integer
0
Route load #3.
load4
mandatory
integer
0
Route load #4.
stops
mandatory
list of stop objects
[]
An ordered list of stops/orders on the route.
routePolyline
optional
string
-
Route polyline encoded with Encoded Polyline Algorithm. Only included if includeRoutePolyline is set to True.

Stop Object

Property Type / Default Description
stopNumber
mandatory
integer
-
Stop number. Starts at 1.
orderNo
mandatory
string
-
The order number.
locationNo
mandatory
string
-
Location number.
locationName
mandatory
string
-
Location name.
address
mandatory
string
-
Location address.
latitude
mandatory
decimal
-
Location latitude.
longitude
mandatory
decimal
-
Location longitude.
scheduledAt
mandatory
time (string)
-
The scheduled time to begin the service.
24-hour (military) clock format, for example: 16:00.
The valid values range from 00:00 to 23:59.
scheduledAtDt
mandatory
datetime (string)
-
The scheduled date and time to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
arrivalTimeDt
mandatory
datetime (string)
-
The date and time when the driver arrived at the location. Because of time windows the driver might need to wait to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
travelTime
mandatory
integer
-
Travel time from previous stop (in seconds).
distance
mandatory
integer
-
Distance from previous stop (in meters).
type
optional
string
-
Order type only added for lunch breaks (value will be break) and for depot trips (value will be depot).

Error and Warning Codes

None.

Get Scheduling Information

Gets the scheduling information for the specified Order.

HTTP Request

GET https://api.optimoroute.com/v1/get_scheduling_info

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_scheduling_info?key=AUTH_KEY&orderNo=ORD001'

Parameters

Property Type / Default Description
orderNo
mandatory
string
-
The user-specified identifier for the order.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the query was successful, false if there was an error.
orderScheduled
optional
boolean
-
true if the order is scheduled, false otherwise.
scheduleInformation
optional
schedule info object
-
The order scheduling information.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
message
optional
string
-
An error description or a warning description (not set if the operation was successful).

Order Scheduling Information Object

Property Type / Default Description
driverSerial
mandatory
string
-
The serial number assigned to the driver.
driverName
mandatory
string
-
The driver’s name.
vehicleRegistration
mandatory
string
-
Vehicle registration.
vehicleLabel
mandatory
string
-
Vehicle label.
stopNumber
mandatory
integer
-
Stop number on the route. Starts at 1.
scheduledAt
mandatory
time (string)
-
The scheduled time to begin the service.
24-hour (military) clock format, for example: 16:00.
The valid values range from 00:00 to 23:59.
scheduledAtDt
mandatory
datetime (string)
-
The scheduled date and time to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
arrivalTimeDt
mandatory
datetime (string)
-
The date and time when the driver arrived at the location. Because of time windows the driver might need to wait to begin the service. Format: YYYY-mm-dd HH:MM:SS, for example 2018-01-01 13:10:37.
travelTime
mandatory
integer
-
Travel time from previous stop (in seconds).
distance
mandatory
integer
-
Distance from previous stop (in meters).

Error and Warning Codes

The following error codes are applicable to Get Scheduling Information method:

Error Code Description
ERR_ORD_NOT_FOUND the order with the matching orderNo was not found
ERR_MULTIPLE_ORD_FOUND there are multiple orders matching the orderNo

Start Planning

Starts the planning process for the specified date.

HTTP Request

POST https://api.optimoroute.com/v1/start_planning

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/start_planning?key=AUTH_KEY'

Parameters

Request body example:

{
  "date": "2013-12-20"
}
Property Type / Default Description
date
mandatory
date (string)
-
Date to be planned.
YYYY-MM-DD format, for example 2013-12-20.
balancing
optional
string
OFF
Route balancing settings. Allowed values:
OFF – No balancing
ON – Balance routes
ON_FORCE – Balance routes and use all drivers

No balancing: returns the best routes, some drivers might not be used.
Balance routes: balance the work load between drivers, some drivers may not be used.
Balance routes and use all drivers: balance work load between all available drivers.
balanceBy
optional
string
WT
If route balancing is turned on, this defines the criteria for balancing the routes.

Allowed values:
WT – Working time
NUM – Number of orders per driver
balancingFactor
optional
decimal
0.3
Importance of balancing compared to route costs. Increasing the balancing factor will result in more balanced routes.
Only applicable in combination with ON_FORCE (otherwise ignored).

Minimum value: 0.0
Maximum value: 1.0
startWith
optional
string
EMPTY
Start planning from existing routes or from scratch.

Allowed values:
EMPTY – Ignore existing routes and start from scratch
CURRENT – Start planning with the existing routes
lockType
optional
string
NONE
Applicable if startWith is set to CURRENT.

Allowed values:
NONE – Allow all changes to the existing routes
ROUTES - Keep planned Routes unchanged and add new Orders to unused
RESOURCES - Keep Drivers/Vehicles for planned Orders and fit in new Orders
depotTrips
optional
boolean
false
If true drivers will be scheduled to return to the warehouse to reload (or unload in case of pickups) if there is still time within their working hours to do another route.
More information is available on our blog:
https://optimoroute.com/stop-restock-and-continue-on-your-way/.
depotVisitDuration
optional
integer
0
Time in minutes required to reload or unload the goods in the warehouse before the driver goes out for another run.
Only applicable if depotTrips is set to true.
useDrivers
optional
list of SelectedDriver objects
[]
Selected drivers that should be used in the optimization.
By default (if useDrivers is not set or the list is empty) all available drivers for the specified date are used.
useOrders
optional
list of strings
[]
Selected orders that should be included in the optimization.
Orders are specified as a list of order identifiers (orderNo strings).
By default (if useOrders is not set or the list is empty) all orders for the specified date are included.

Orders that are not selected, but are already scheduled to drivers that will be used in the optimization will be unscheduled unless the includeScheduledOrders flag is set to true.
includeScheduledOrders
optional
boolean
true
Determines behavior when a subset of orders is selected but there are other orders already scheduled to the applicable drivers.
If includeScheduledOrders is true, these orders will be included in the optimization, otherwise they will be unscheduled.

SelectedDriver Object

Use either driverExternalId or driverSerial (one field is enough):

Property Type / Default Description
driverExternalId
optional
string
-
The external identifier assigned to the driver in driver administration.
driverSerial
optional
string
-
The driver’s serial number.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the optimization was started, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
planningId
optional
integer
-
Returns id of the started optimization if operation was successful, or the already running optimization in case of ERR_OPT_RUNNING_FOR_DATE error. Planning id can be used later for getting the planning status or stopping the planning process.
missingOrders
optional
list of strings
[]
In case ERR_ORD_NOT_FOUND error is raised this field will contain the list of missing order identifiers (orderNo strings).
missingDrivers
optional
list of SelectedDriver objects
[]
In case ERR_DRIVER_NOT_FOUND error is raised this field will contain a list of missing drivers. Each driver is a SelectedDriver object.

Error and Warning Codes

The following error codes are applicable to Start Planning method:

Error Code Description
ERR_OPT_TRIAL_ENDED free trial has ended for this account
ERR_OPT_RUNNING_FOR_DATE planning is already running for this date
ERR_OPT_RUNNING_FOR_ORDER optimization is already running for one or more orders listed in useOrders
ERR_OPT_NO_REQUESTS no orders exist for the specified date
ERR_OPT_NO_RESOURCES no drivers are available for this date
ERR_OPT_RESOURCES_EXCEEDED number of driver exceeded
ERR_OPT_REQUESTS_EXCEEDED number of orders exceeded
ERR_OPT_COULD_NOT_START internal error, please contact support
ERR_ORD_NOT_FOUND one or more orders specified in useOrders were not found
ERR_DRIVER_NOT_FOUND one or more drivers specified in useDrivers were not found
ERR_MULTIPLE_ORD_FOUND multiple orders with specified identifier have been found
ERR_MULTIPLE_DRV multiple drivers with specified identifier have been found

Stop Planning

Stops the planning process.

HTTP Request

POST https://api.optimoroute.com/v1/stop_planning

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/stop_planning?key=AUTH_KEY'

Parameters

Request body example:

{
  " planningId": 8828
}
Property Type / Default Description
planningId
mandatory
integer
-
The id of the planning process to be stopped.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the optimization was stopped, false if there was an error.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Stop Planning method:

Error Code Description
ERR_JOB_NOT_FOUND planning job with specified id was not found
ERR_OPT_NOT_RUNNING planning job is not running
ERR_OPT_COULD_NOT_STOP internal error, please contact support

Get Planning Status

Returns the status of the planning process.

HTTP Request

GET https://api.optimoroute.com/v1/get_planning_status

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_planning_status?key=AUTH_KEY&planningId=8828'

Parameters

Property Type / Default Description
planningId
mandatory
integer
-
The id of the planning process.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the request was a success, false if an error occurred.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).
status
optional
string
-
N - New
R - Running
C - Cancelled by the user
F - Finished
E - Error occurred
percentageComplete
optional
integer
-
Percentage complete – values range from 0 to 100.

Error and Warning Codes

The following error codes are applicable to Get Planning Status method:

Error Code Description
ERR_JOB_NOT_FOUND the planning job with the specified id was not found

Update Driver Parameters

Updates driver parameters for a particular date and driver start and end location. Any existing routes for the specified date/driver will be unscheduled.

The following parameters can be changed:

HTTP Request

POST https://api.optimoroute.com/v1/update_driver_parameters

reqbody.json is a local file containing the JSON data to be posted. Make sure to replace AUTH_KEY with your API key.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_driver_parameters?key=AUTH_KEY'

Parameters

Request body example:

{
  "externalId": "3945300304540",
  "date": "2019-09-25",
  "workTimeFrom": "09:30",
  "workTimeTo": "18:00"
}
Property Type / Default Description
externalId
mandatory
string
-
The external identifier assigned to the driver in driver administration.
date
mandatory
date
-
Date to be planned.
YYYY-MM-DD format, for example 2013-12-20.
enabled
optional
boolean
unchanged
Enable or disable driver for the specified date.
workTimeFrom
optional
time (string)
unchanged
Driver’s work time from for the specified date.
24-hour (military) clock format, for example: 08:00.
The valid values range from 00:00 to 23:59.
workTimeTo
optional
time (string)
unchanged
Driver’s work time end for the specified date.
24-hour (military) clock format, for example: 08:00. The valid values range from 00:00 to 23:59.
assignedVehicle
optional
string
unchanged
The external identifier of the vehicle to be assigned to the driver for the specified date. This will also update the vehicle load capacity parameters (unless they are overridden with vehicleCapacityX settings).
vehicleCapacity1
optional
integer
unchanged
The new vehicle load capacity #1 for the specified date.
vehicleCapacity2
optional
integer
unchanged
The new vehicle load capacity #2 for the specified date.
vehicleCapacity3
optional
integer
unchanged
The new vehicle load capacity #3 for the specified date.
vehicleCapacity4
optional
integer
unchanged
The new vehicle load capacity #4 for the specified date.
startLatitude
optional
decimal
unchanged
Driver’s start location GPS latitude will be changed (this new location will be used for all future optimizations). If startLongitude is not defined this value will be ignored.
startLongitude
optional
decimal
unchanged
Driver’s start location GPS longitude (this new location will be used for all future optimizations). If startLatitude is not defined this value will be ignored.
startAddress
optional
string
unchanged
Driver’s start location address that will be displayed on reports (this new location will be used for all future optimizations). If startLatitude and startLongitude are not defined this value will be ignored.
endLatitude
optional
decimal
unchanged
Driver’s end location GPS latitude (this new location will be used for all future optimizations). If endLongitude is not defined this value will be ignored.
endLongitude
optional
decimal
unchanged
Driver’s end location GPS longitude (this new location will be used for all future optimizations). If endLatitude is not defined this value will be ignored.
endAddress
optional
string
unchanged
Driver’s end location address that will be displayed on reports (this new location will be used for all future optimizations). If endLatitude and endLongitude are not defined this value will be ignored.

Response

Property Type / Default Description
success
mandatory
boolean
-
true if the driver parameters were updated, false if an error occurred.
code
optional
string
-
An error code or a warning code (not set if the operation was successful).

Error and Warning Codes

The following error codes are applicable to Update Driver Parameters method:

Error Code Description
ERR_DRIVER_NOT_FOUND the driver with the specified externalId was not found
ERR_MULTIPLE_DRV multiple drivers with specified externalId have been found
ERR_VEH_NOT_FOUND the vehicle with the specified externalId was not found
ERR_MULTIPLE_VEH multiple vehicles with specified externalId have been found

Get Mobile Events

Retrieve mobile events such as success, on_duty, failed, … for the currently active plan (i.e. the last plan that was sent to drivers).

Each get_events request returns up to 500 events which occurred after the specified tag. The result will contain a new tag which you can use in the next get_events request to skip already received events.

HTTP Request

GET https://api.optimoroute.com/v1/get_events

Make sure to replace AUTH_KEY with your API key.

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Parameters

Property Type / Default Description
after_tag
optional
string
-
Specify the after_tag to retrieve only the events which occurred since a specific prior call to get_events.
In this case, the after_tag needs to contain the tag returned in the prior call.
See example below.

Response

Property Type / Default Description
success
mandatory
boolean
-
true unless an error occurred.
events
optional
list of event objects
[]
A list of events objects in the order they arrived from drivers’ mobile apps.
tag
optional
string
-
Tag marks the point of time of the last event received in this response. Use it to specify the after_tag query parameter in the next get_events request.
remainingEvents
optional
integer
unchanged
The number of events that occurred but were not fetched in this response (in each response at most 500 events are returned).

Event Object

Property Type Description
event
mandatory
string Event type. Currently one of the following:
on_duty – the driver went on duty
off_duty – the driver went off duty
start_service - the driver started the service
success – the specified order was completed successfully
failed – the driver failed to complete the order
rejected – the driver rejected the order
unixTimestamp
mandatory
integer The time at which event occurred.
Number of seconds elapsed since 00:00 UTC January 1st 1970.
utcTime
mandatory
ISO 8601 date (string) The UTC date and time at which the specified event occurred.
localTime
mandatory
ISO 8601 date (string) The local time at which the specified event occurred.
driverName
optional
string The driver’s name.
Will be sent for events that are related to a specific driver.
driverSerial
optional
string The driver’s serial number.
Will not be sent if empty or if the event is not related to a specific driver.
driverExternalId
optional
string The driver’s external identifier.
Will not be sent if empty or if the event is not related to a specific driver.
orderNo
optional
string The identifier of the affected order.
Not sent for some events such as on_duty.

The returned event fields unixTimestamp, utcTime and localTime all refer to the same moment at which the event occurred, so you can use whichever is more convenient.

Please note that some mobile devices might be offline temporarily and they will sync their events only after they reconnect so the events you’ll receive might arrive out of chronological order. For example, the first driver might successfully complete the order 001 at 9:00 AM, but might be offline until 09:15 AM. The second driver could finish the order 002 at 9:10 AM, but might be online the whole time. The server will receive the event for the order 002 first and only then the event for the order 001.

Examples

In the first request we won’t specify the after_tag parameter (we’ll leave it empty):

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Response:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [
    {
      "unixTimestamp": 1516294800,
      "utcTime": "2018-01-18T17:00:00",
      "localTime": "2018-01-18T09:00:00"
      "driverName": "Charlie",
      "driverSerial": "0011",
      "event": "on_duty",
    },
    {
      "unixTimestamp": 1516296030,
      "event": "success",
      "utcTime": "2018-01-18T17:20:30",
      "localTime": "2018-01-18T09:20:30",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD232"
    }
  ],
  "success": true
}

We’ll retry the query in 10 seconds, but this time we’ll use the tag we received in the last result as our after_tag parameter:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Response:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [],
  "success": true
}

There were no new events in the meantime. We’ll retry the query in 10 seconds:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Response:

{
  "remainingEvents": 0,
  "tag": "qwe9876541213",
  "events": [
    {
      "unixTimestamp": 1516298030,
      "event": "success",
      "utcTime": "2018-01-18T17:53:50",
      "localTime": "2018-01-18T09:53:50",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD771"
    }
  ],
  "success": true
}