NAV Navbar
logo SimpliRoute

Introduction

API Endpoint:

URL: https://api.simpliroute.com/v1/
URL: https://api.simpliroute.com/v1/
URL: https://api.simpliroute.com/v1/

The SimpliRoute API is a set of REST endpoints. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, included error logs.

The main objective of this docs to allow any developer to start working with our API thanks to different examples and use-cases exposed in this documentation. There are 2 basic use-cases to be working with our API:

  • You (or your company) are a SimpliRoute web platform and want to send information from your system to SimpliRoute or vice-versa. If that is the case, you'll be mostly interested in our Visit endpoints

  • You are developer and you are interested in improve our system adding route intelligence. If that is the case, our Route Optimization API is the right path to follow.

If you have feedback, error or out-dated info, feel free to contact us at [email protected].

Authentication

Basic endpoint to show how to make a call with the Authorization Token

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.simpliroute.com/v1/accounts/me/",
  "method": "GET",
  "headers": {
    "content-type": "application/json",
    "authorization": "Token 12345678900987sr"
  }
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/accounts/me/")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();
curl curl -X GET \
  https://api.simpliroute.com/v1/accounts/me/ \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \

Make sure to replace 12345678900987sr with your API key.

To use SimpliRoute API, you have to provide a valid Token through the header "Authorization". If you don't have a Token, you can get it from your account in the url: https://app2.simpliroute.com/#/uprofile/info.

If you don't have an account, you can create a 14-days free trial in this URL: https://app2.simpliroute.com/#/signup.

Visits

If you want to integrate your system with SimpliRoute, the most relevant endpoint in our API is Visit. A visit object is anything that a driver has to do in the street: a service order, a delivery, a pickup. Then, if you want to optimize those orders and track then in SimpliRoute, you have to create a visit object. In this particular object, you have to specify a few simple things:

  • Title
  • Address
  • Planned Date

That is the basic information that a visit must contain to be accepted in the API. As all the endpoints in SimpliRoute API, it implements GET, POST, PUT and DELETE http methods.

The Visit Object

Visit Object example

{
        "id": 123,
        "order": 1,
        "tracking_id": "SR12345678901234",
        "status": "pending",
        "title": "Kwik e mart",
        "address": "742 Evergreen Terrace, Springfield, USA",
        "latitude": 44.052698,
        "longitude": -123.020718,
        "load": 1.2,
        "load_2": 2.0,
        "load_3": 3.1,
        "window_start": "10:00",
        "window_end": "14:00",
        "window_start_2": "15:00",
        "window_end_2": "18:00",
        "duration": "10",
        "contact_name": "Apu Nahasapeemapetilon",
        "contact_phone": "+123413123212",
        "contact_email": "[email protected]",
        "reference": "invoice_id",
        "notes": "Leave at front door",
        "skills_required": [],
        "skills_optional": [],
        "planned_date": "2020-01-01",
        "estimated_time_arrival": null,
        "estimated_time_departure": null,
        "checkin_time": null,
        "checkout_time": null,
        "checkout_latitude": null,
        "checkout_longitude": null,
        "checkout_comment": "Delivery was completed!",
        "pictures": [],
        "priority_level": 1
    }
Attributes Data Type Description
id uuid Unique identifier for the object.
order Integer Visit order when the visit already belongs to a delivery route
tracking_id String Autogenerated tracking code to follow the delivery
status String Visit's status (pending, completed, failed)
title String String to identify the delivery. Usually company or person's name
address String Address text. Best practice is to use Googlemaps format.
planned_date Date Date when the visit will be delivered
latitude Float Visit's latitude location
longitude Float Visit's longitude location
load Double Space of the truck that visit uses.
load_2 Double Space of the truck that visit uses.
load_3 Double Space of the truck that visit uses.
window_start Time Initial Hour when the visit can be visit
window_end Time Final Hour when the visit can be visit
window_start_2 Time Initial Hour when the visit can be visit
window_end_2 Time Final Hour when the visit can be visit
duration Integer Time spent in the delivery (minutes)
contact_name String Name of who will receive the delivery
contact_phone String Phone of who will receive the delivery
contact_email String E-mail of who will receive the delivery
notes String Information to help the driver
skills_required Integer array Array of required skills id that this visit needs
skills_optional Integer array Array of optional skills id that this visit needs
estimated_time_arrival Time SimpliRoute estimation of arrival to the visit.
estimated_time_departure Time SimpliRoute estimation of departure from visit.
checkin_time Timestamp Timestamp when the driver started the delivery.
checkout_time Timestamp Timestamp when the driver completed the delivery.
checkout_latitude Float Latitude of the driver when he completed the delivery
checkout_longitude Float Longitude of the driver when he completed the delivery
checkout_comment String Information provided by the driver when she was completing the delivery
pictures URL array Array with URLs of pictures added with the delivery.
priority_level Integer If the visit is more important than others. It goes from 1 to 5. 1: First of the day, 2: Last of the day. 3: High priority, 4: Medium priority, 5: Low priority.

Create a visit

URL Definition


POST https://api.simpliroute.com/v1/routes/visits/

Example Request

  curl -X POST \
    https://api.simpliroute.com/v1/routes/visits/ \
    -H 'authorization: Token 12345678900987sr' \
    -H 'content-type: application/json' \
    -d '{
    "title": "Kwik e mart",
    "address": "742 Evergreen Terrace, Springfield, USA",
    "latitude": 44.052698,
    "longitude": -123.020718,
    "contact_name": "Apu Nahasapeemapetilon",
    "contact_phone": "+123413123212",
    "contact_email": "[email protected]",
    "reference": "invoice_id",
    "notes": "Leave at front door",
    "planned_date": "2020-01-01"
  }'


OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"title\": \"Kwik e mart\",\n  \"address\": \"742 Evergreen Terrace, Springfield, USA\",\n  \"latitude\": 44.052698,\n  \"longitude\": -123.020718,\n  \"contact_name\": \"Apu Nahasapeemapetilon\",\n  \"contact_phone\": \"+123413123212\",\n  \"contact_email\": \"[email protected]\",\n  \"reference\": \"invoice_id\",\n  \"notes\": \"Leave at front door\",\n  \"planned_date\": \"2020-01-01\"\n}");
Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.simpliroute.com/v1/routes/visits/",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "authorization": "Token 12345678900987sr"
  },
  "processData": false,
  "data": "{\n  \"title\": \"Kwik e mart\",\n  \"address\": \"742 Evergreen Terrace, Springfield, USA\",\n  \"latitude\": 44.052698,\n  \"longitude\": -123.020718,\n  \"contact_name\": \"Apu Nahasapeemapetilon\",\n  \"contact_phone\": \"+123413123212\",\n  \"contact_email\": \"[email protected]\",\n  \"reference\": \"invoice_id\",\n  \"notes\": \"Leave at front door\",\n  \"planned_date\": \"2020-01-01\"\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

To create a visit, the bare minimum information is a title, address and a planned_date. The other parameters in the visit object are optional and you'll need them depending of your implementation.

You can create visits one by one or as an array. The examples in the right side only shows one visit creation per request but if you need to create a batch of visit, the input will be something like this:

Returns

Returns the visit object if the creation succeeded. This call will return an error if some of parameters are invalid.

Retrieve a visit

URL Definition


GET https://api.simpliroute.com/v1/routes/visits/{{visit_id}}

Example Request Using as '12345' as example for visit_id

curl -X GET \
  https://api.simpliroute.com/v1/routes/visits/12345 \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/12345")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.simpliroute.com/v1/routes/visits/12345",
  "method": "GET",
  "headers": {
    "content-type": "application/json",
    "authorization": "Token 12345678900987sr"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Example Response

{
    "id": 12345,
    "order": 1,
    "tracking_id": "SR12345678901123",
    "status": "completed",
    "title": "Duff Beer Company",
    "address": "Suecia 0155, Providencia, Santiago",
    "latitude": "-33.419460",
    "longitude": "-70.611091",
    "load": 1.0,
    "load_2": 2.0,
    "load_3": 3.1,
    "window_start": "09:00",
    "window_end": "11:00",
    "window_start_2": "14:00",
    "window_end_2": "22:00",
    "duration": "20",
    "contact_name": "Bart Simpsons",
    "contact_phone": "+1245721234567",
    "contact_email": "[email protected]",
    "reference": "Leave in the Treehouse",
    "notes": "nota\ncon\nenters\ntest",
    "skills_required": [],
    "skills_optional": [],
    "planned_date": "2017-10-10",
    "route": 12,
    "route_estimated_time_start": null,
    "estimated_time_arrival": null,
    "estimated_time_departure": null,
    "checkin_time": null,
    "checkout_time": null,
    "checkout_latitude": null,
    "checkout_longitude": null,
    "checkout_comment": "",
    "checkout_observation": null,
    "signature": null,
    "pictures": [],
    "created": "2017-10-10T18:35:24.797823Z",
    "modified": "2017-10-10T18:35:24.800917Z",
    "eta_predicted": "2017-10-10T00:00:00-03:00",
    "eta_current": "2017-10-10T00:00:00-03:00",
    "driver": null,
    "vehicle": null,
    "priority": false,
    "sms_enabled": false,
    "has_alert": false,
    "priority_level": null
}

Retrieves the details of an existing visit. Send the unique visit id and SimpliRoute API will return the corresponding visiti information.

Retrieve visits by date

Definition


GET https://api.simpliroute.com/v1/routes/visits/?planned_date={{planned_date}}

Example Request

curl -X GET \
  'https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01' \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json'

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01")
  .get()
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.simpliroute.com/v1/routes/visits/?planned_date=2020-01-01",
  "method": "GET",
  "headers": {
    "content-type": "application/json",
    "authorization": "Token 12345678900987sr"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

GET call to request all the visits for a given date. The expected planned date format is "YYYY-mm-dd" (Year-month-day, 2020-10-22). This is a useful call if you want to track your deliveries in real-time because it returns the whole list of visits and the complete activity of each of them (including checkouts and information provided from the drivers in the street.)

Returns

List all the visits in a given date. Each entry in the array is a separate visit object. If no visits are available, the resulting array will be empty. This request will return and error if the planned_date parameter doesn't have the expected format.

Update a visit

URL Definition


PUT https://api.simpliroute.com/v1/routes/visits/{{visit_id}}

Example Request

curl -X PUT \
  https://api.simpliroute.com/v1/routes/visits/1111/ \
  -H 'authorization: Token 12345678900987sr' \
  -H 'content-type: application/json' \
  -d '{
  "title": "Updated visit",
  "address": "new address",
  "load": 39,
  "duration": "00:00:10",
  "contact_name": "New visit contact",
  "contact_phone": "+12341345",
  "notes": "New information",
  "planned_date": "2020-06-30"
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"title\": \"Updated visit\",\n \"address\": \"New address\",\n \"load\": 39,\n  \"duration\": \"00:00:10\",\n  \"contact_name\": \"New visit contact\",\n  \"contact_phone\": \"+12341345\",\n  \"notes\": \"New information\",\n  \"planned_date\": \"2020-06-30\"\n}");
Request request = new Request.Builder()
  .url("https://api.simpliroute.com/v1/routes/visits/1111/")
  .put(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Token 12345678900987sr")
  .build();

Response response = client.newCall(request).execute();
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.simpliroute.com/v1/routes/visits/1111/",
  "method": "PUT",
  "headers": {
    "content-type": "application/json",
    "authorization": "Token 12345678900987sr"
  },
  "processData": false,
  "data": "{\n  \"title\": \"Updated visit\",\n  \"address\": \"New address\",\n \"load\": 39,\n  \"duration\": \"00:00:10\",\n  \"contact_name\": \"New visit contact\",\n  \"contact_phone\": \"+12341345\",\n  \"notes\": \"New information\",\n  \"planned_date\": \"2020-06-30\"\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Updates the specified argument by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Returns

Returns the charge object if the update succeeded. This call will return an error if update parameters are invalid.

Example Response

Webhooks

Use webhooks to be notified about events that happen in a SimpliRoute account.

How to work with SimpliRoute's webhooks

SimpliRoute can send webhook events that notify your application any time an event happens on your account. This is especially useful for events—like completed or failed deliveries that are not triggered by a direct API request. This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

You can register webhook URLs that we will notify any time an event happens in your account. When the event occurs, SimpliRoute will send a POST evento to your URL.

This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. SimpliRoute then sends the Event object, via an HTTP POST request, to any endpoint URLs that you have defined in your account’s Webhooks settings.

Which events can be notified

Currently, SimpliRoute can notify this events:

  • Completed delivery
  • Failed delivery

We're working to add a few more events. Some of the ones in our roadmap:

  • Plan created
  • Route created
  • Visit created
  • Visit updated

If you need some other events, let us know to add them to our roadmap. Feel free to reach us over email to [email protected]

Webhook event json

Because our current version of webhooks are checkout-related, the webhook event is a visit object. The information provided will be the same as is found in the visit object section

Configuring your Webhooks settings

Currently, we don't offer a web interface for the configuration of those events. The way to do it is with our Customer Success team. This is the process:

  • Send an emails to our team [email protected]
  • In this email, send the URL that you want to receive the webhook.
  • We'll let you know when the configuration is ready.

We are adding the web interface to self-administration of this funcionality soon.

Optimization

Optimization Endpoint


https://optimizator.simpliroute.com/vrp/optimize/sync/

Because our wide experience in route optimization, we warranty this is the best way to create your company's delivery routes. We believe that everyday problems deserve simple solutions so that is why you now have available the API of our algorithm. Solve in the quickest and easiest possible way your logistics delivery problems.

SimpliRoute gets this restrictions in consideration:

  • Capacities of your vehicles.
  • Different start and end points for your vehicles.
  • Drivers' shifts.
  • Time windows of your clients.
  • And a lot more

In the next couple of sections, we'll go in deep detail about our API, which objects it contains and a lot of practical examples to start developing your app using our API. If you have questions, you can send to us an email to [email protected]

Optimization Instance

Input json


{
    "vehicles": [
        {
            "ident": "Vehicle 1",
            "location_start": {
                "ident": "warehouse A",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "location_end": {
                "ident": "warehouse C",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "capacity": 3500,
            "capacity_2": 3500,
            "capacity_3": 3500,
            "shift_start": "9:00",
            "shift_end": "22:00",
            "skills":[]
        },
        {
            "ident": "Vehicle 2",
            "location_start": {
                "ident": "warehouse B",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "location_end": {
                "ident": "warehouse C",
                "lat": -33.4233926,
                "lon": -70.6104996
            },
            "capacity": 3500,
            "capacity_2": 3500,
            "capacity_3": 3500,
            "shift_start": "9:00",
            "shift_end": "22:00",
            "skills":[]
        }
    ],
    "nodes": [
        {
            "ident": "El Salto 4875",
            "lat": -33.3887,
            "lon": -70.62304,
            "window_start": "09:00",
            "window_end": "17:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
             "duration": 15
        },
        {
            "ident": "Avenida Del Valle 7",
            "lat": -33.39124,
            "lon": -70.61387,
            "load": 2530,
            "window_start": "9:00",
            "window_end": "11:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
            "duration": 15
        },
        {
            "ident": "Larrain 5862",
            "lat": -33.45066,
            "lon": -70.54915,
            "load": 77,
            "window_start": "09:00",
            "window_end": "17:00",
            "window_start_2": "19:00",
            "window_end_2": "22:00",
            "priority_level": 1,

            "duration": 10
        }
    ],
      "balance": true,
      "all_vehicles": false,
      "join": true,
      "open_ended": false,
      "single_tour": true,
      "fmv":1.0

}

Our API receives JSON object as input. The Optimization json can be divided in this sections:

  • Vehicles: Array of vehicles with their information to be optimized with our API.
  • Nodes: Array of deliveries with their constraints to be routed with our API.
  • Optimization options: Different optimizations criteria to adjust the optimization to your requirements.

In the next couple of section we'll discuss more in detail each of this objects. Also, we'll show a few examples of how to make a request to our API with different use-cases to make easier for you to start coding with SimpliRoute.

Vehicles

Vehicle's object example:

{
    "ident": "Vehicle 1",
    "location_start": {
        "ident": "warehouse B",
        "lat": -33.4233926,
        "lon": -70.6104996
    },
    "location_end": {
        "ident": "warehouse C",
        "lat": -33.345523,
        "lon": -70.456992
    },
    "capacity": 3500,
    "capacity_2": 3500,
    "capacity_3": 3500,
    "shift_start": "09:00",
    "shift_end": "18:00",
    "skills": ["north-east", "electricity", "cold"],
    "refill": 30
}

When using our API, the first object that you have to understand is the vehicle object. In our API, a vehicle is any moving device in your city, then if you are working with fleet, field services or sales people, all of them should be created as a "vehicle" in our API. Each of the attributes are described below:

Attributes Mandatory Type Description
ident Mandatory String Unique identifier for the object.
location_start Mandatory Object Location of the vehicle when the optimization was called
location_end Optional Object Location where the vehicle should end its route
capacity Optional Float Vehicle's capacity load
capacity_2 Optional Float Vehicle's second capacity load
capacity_3 Optional Float Vehicle's third capacity load
shift_start Optional String String "HH:mm" (military time). When the vehicle's shift starts.
shift_end Optional String String "HH:mm" (military time). When the vehicle's shift ends.
skills Optional String array Skills that the vehicles supports. Deliveries must have skills in order to be used.
refill Optional Integer Minutes that takes to refill the vehicle when it returns to the depot before starts a new route.

Deliveries

Delivery's object example:

{
    "nodes": [
        {
            "ident": "Delivery 1",
            "lat": -33.3887,
            "lon": -70.62304
        },
        {
            "ident": "Delivery 2",
            "lat": -33.39124,
            "lon": -70.61387,
            "load": 253.1,
            "load_2": 2.0,
            "load_2": 3.2,
            "window_start": "09:00",
            "window_end": "11:00",
            "window_start_2": "13:00",
            "window_end_2": "15:00",
            "duration": 15,
            "skills_required": ["north-east"],
            "skills_optional": ["electricity"],
            "priority_level": 2

        }
    ]
}

A delivery is something that your vehicle has to do in the street: delivery orders, sales opportunities, field service orders, etc.

Attributes Mandatory Type Description
ident Mandatory String Unique identifier for the object.
lat Mandatory Object Latitude of the delivery's location.
lon Optional Object Longitude of the delivery's location.
load Optional Float Load of this delivery. Must be on same units as vehicle's load.
load_2 Optional Float Secondary load of this delivery. Must be on same units as vehicle's load 2.
load_3 Optional Float Third load of this delivery. Must be on same units as vehicle's load 3.
window_start Optional String String "HH:mm" (military time). Minimum time this delivery can be attended.
window_end Optional String String "HH:mm" (military time). Maximum time this delivery can be attended.
window_start_2 Optional String String "HH:mm" (military time). Secondary minimum time this delivery can be attended. (Ex: I can visit this place from 10:00 to 12:00 and from 15:00 to 19:00)
window_end_2 Optional String String "HH:mm" (military time). Secondary maximum time this delivery can be attended.
duration Optional Integer Minutes that the vehicle will stay on the delivery.
skills_required Optional String array Skills this delivery needs to be fulfilled. Only the vehicles who have all of these skills will attend the delivery
skills_optional Optional String array Skills this delivery needs to be fulfilled. Only the vehicles who have at least one of these skills will attend the delivery
priority_level Optional Integer Used to indicate this delivery is more important than others. Possible values are 1: First of the day, 2: Last of its route, 3: High Priority, 4: Medium Priority, 5: Low Priority.

Optimization options

SimpliRoute has some additional features allowing you to configure the optimization in the best possible way that fits your company.

Attributes Mandatory Type Description
balance Optional Boolean Default: False. If true, there will be an enforced balance between all the vehicles, in time and number of locations for the algorithm procedure
fmv Optional Integer Default: 2.0, Speed traffic factor. It could be 1.0 = Low Traffic, 1.5 = Medium Traffic, 2.0 = High Traffic or 3.0 = Intense Traffic.
all_vehicles Optional Boolean Default: False. If true, the algorithm will use all the selected vehicles. If false, will minimize the number of vehicles.
open_ended Optional Boolean Default: False. If true, the route will be created assuming the vehicle won't return the depot at the end of the day.
single_tour Optional Boolean Default: False. If true, all vehicles will have only one route.

Example - Basic Optimization

JSON input

{
    "vehicles": [
        {
            "ident": "Vehicle 1",
            "location_start": {
                "ident": "depot_1_start",
                "lat": -33.4233926,
                "lon": -70.6104996
            }
        }
    ],
    "nodes": [
        {
            "ident": "1",
            "lat": -33.436135,
            "lon": -70.6509688
        },
        {
            "ident": "2",
            "lat": -33.4334123,
            "lon": -70.653234
        },
        {
            "ident": "3",
            "lat": -33.333413,
            "lon": -70.5534688
        }
    ]
}

JSON output

{
    "vehicles": [{
        "ident": "Vehicle 1",
        "tours": [{
            "nodes": [{
                "arrival": "00:00",
                "ident": "depot_1_start",
                "lon": -70.6104996,
                "departure": "00:00",
                "lat": -33.4233926,
                "order": 0
            }, {
                "load": 0,
                "arrival": "00:17",
                "ident": "3",
                "lon": -70.5534688,
                "departure": "00:17",
                "lat": -33.333413,
                "order": 1
            }, {
                "load": 0,
                "arrival": "00:39",
                "ident": "2",
                "lon": -70.653234,
                "departure": "00:39",
                "lat": -33.4334123,
                "order": 2
            }, {
                "load": 0,
                "arrival": "00:40",
                "ident": "1",
                "lon": -70.6509688,
                "departure": "00:40",
                "lat": -33.436135,
                "order": 3
            }, {
                "arrival": "01:42",
                "ident": "depot_1_start",
                "lon": -70.6104996,
                "departure": "01:42",
                "lat": -33.4233926,
                "order": 11
            }]
        }]
    }],
    "num_vehicles_used": 1
}

The most basic example of routing optimization using our API is when there's only one depot, from which all of your vehicles will start and end the day.

Additionally, on every location your vehicles need to visit there are no restrictions regarding load or time windows. This happens usually on cases like:

  • Delivery of letters and documents
  • Food delivery with vehicles on which load restrictions are not an issue

You can see an input and output JSON example on the right.

In this example there are two relevant entities: vehicles and nodes. The first of them must contain:

"Ident" is required and is the vehicle's id. The object "location_start" is the location from where the vehicle will begin its daily operation. Since in this example we didn't define a "location_end" our algorithm will assume that the vehicle will end its day on "location_start".

In the nodes case, you must define the following:

We use "ident" as an ID for the visit, and "lat" and "lon" to specify the latitude and longitude of the node. Since in this example there are no time windows nor loads, there's no need to specify anything else on each visit.

Vehicle Time Windows

If no time windows are specified for the vehicle, our algorithm will assume that the vehicle will work between "00:00" and "23:59" hours of that day. If you wish to specify a time window for the vehicle, you must add the values "shift_start" and "shift_end". An example of this:

Service Times

If service time is not specified, our algorithm will assume that service time in that location is 0 (zero) minutes. If you wish to add a value, you can specify it on the node object as it follows:

"Duration" must be an integer in minutes. It represents how long will the vehicle stay on that location.

Example - Multiple depots

Similar to last case, you can define for each vehicle a different location to start and end the day. This way, you can simulate more complex operations in which a vehicle must begin the day on a city and end the day on another place. An example JSON of this is on the right.

JSON input:

{
    "vehicles": [{
        "ident": "Vehicle 1 different start and end",
        "shift_start": "09:00",
        "shift_end": "19:00",
        "location_start": {
            "ident": "depot_1_start",
            "lat": -33.4233926,
            "lon": -70.6104996
        },
        "location_end": {
            "ident": "depot_2_end",
            "lat": -33.436662,
            "lon": -70.577584
        }
    }],
    "nodes": [{
        "ident": "1",
        "lat": -33.436135,
        "lon": -70.6509688
    }, {
        "ident": "2",
        "lat": -33.4334135,
        "lon": -70.6534688,
        "duration": 5
    }, {
        "ident": "3",
        "lat": -33.333413,
        "lon": -70.5534688,
        "duration": 5
    }]
}

JSON output:

{
    {
    "vehicles": [{
        "ident": "Vehicle 1 different start and end",
        "tours": [{
            "nodes": [{
                "arrival": "09:00",
                "ident": "depot_1_start",
                "lon": -70.6104996,
                "departure": "09:00",
                "lat": -33.4233926,
                "order": 0
            }, {
                "load": 0,
                "arrival": "09:17",
                "ident": "2",
                "lon": -70.6534688,
                "departure": "09:22",
                "lat": -33.4334135,
                "order": 1
            }, {
                "load": 0,
                "arrival": "10:05",
                "ident": "1",
                "lon": -70.6509688,
                "departure": "10:35",
                "lat": -33.436135,
                "order": 2
            }, {
                "load": 0,
                "arrival": "10:49",
                "ident": "3",
                "lon": -70.5534688,
                "departure": "11:19",
                "lat": -33.333413,
                "order": 3
            },{
                "arrival": "11:56",
                "ident": "depot_2_end",
                "lon": -70.577584,
                "departure": "11:56",
                "lat": -33.436662,
                "order": 4
            }]
        }]
    }],
    "num_vehicles_used": 1
}

Backhaul Optimization (Routes with picks and drop offs)

Example of Nodes Object with Loads and Pickloads

{
    "nodes": [
        {
            "ident": "Regular Delivery",
            "lat": -33.3887,
            "lon": -70.62304,
            "load": 10.1,
            "load_2": 2.0,
            "load_3": 3.2
        },
        {
            "ident": "Regular Pick up",
            "lat": -33.39124,
            "lon": -70.61387,
            "pickload": 5.1,
            "pickload_2": 1.0,
            "pickload_3": 1.2
        },
        {
            "ident": "Pick up and Delivery",
            "lat": -33.4887,
            "lon": -70.92304
            "load": 7.2,
            "load_2": 1.0,
            "load_2": 2.2,
            "pickload": 4.1,
            "pickload_2": 3.0,
            "pickload_3": 3.2
        }
    ]
}

Our algorithm is extended to also support routes in which your vehicles must deliver products to your customers and also pick up products from your customers that must come back to your depot or warehouse. In this scenario, on each customer you can either deliver, pick up or both pick up and deliver products.

This type of routing is commonly known as Backhaul Route Optimization, which must not be confused with Pick up And Delivery Optimization which is a slightly different problem. In this type of route optimization, the capacity of the vehicle must be checked on each stop, in order not to overbook it on the middle of the route.

In order to use our Backhaul Optimization you must use the same route optimization endpoint that is used for regular optimizations, but adding some optional parameters into the nodes object for each visit.

These are the new parameters you can add, and how they are related to the parameters of regular route optimization:

Attributes Mandatory Type Description
load Optional Float Load that must be delivered on this client. Must be on the same unit as vehicle's load.
load_2 Optional Float Secondary Load that must be delivered on this client. Must be on the same unit as vehicle's secondary load.
load_3 Optional Float Third Load that must be delivered on this client. Must be on the same unit as vehicle's third load.
pickload Optional Float Load that must be picked up on this client. Must be on the same unit as vehicle's load and this visit's load.
pickload_2 Optional Float Secondary Load that must be picked up on this client. Must be on the same unit as vehicle's secondary load and this visit's load_2.
pickload_3 Optional Float Third Load that must be picked up on this client. Must be on the same unit as vehicle's third load and this visit's load_3.

Estimated Time Calculation

ETC Update Endpoint


https://optimizator.simpliroute.com/etc/sync

JSON input

{
  "vehicle": {
    "vehicle_id": "Vehicle 1",
    "lat": -33.45754,
    "lon": -70.92697,
    "departure_time": "09:00"
  },
  "tours": [{
    "nodes": [{
        "id": "id1",
        "lat": -33.45754,
        "lon": -70.62697,
        "service_time": 30.0,
        "order": 0
      },
      {
        "id": "id2",
        "lat": -33.45744,
        "lon": -70.77532,
        "service_time": 90.0,
        "order": 1
      },
      {
        "id": "id3",
        "lat": -33.45742,
        "lon": -70.60364,
        "service_time": 90.0,
        "order": 2
      }
    ]
  }],
  "fmv":2.0
}

After your vehicle is on route, a lot of things can happen:

  • Traffic jams
  • Longer service times than expected
  • Unexpected street situations
  • New priorities along the days

Then, after a while, the initial calculated ETA is not longer valid and you need to recalculated it. For this cases, we have a dedicated endpoint to solve the issue. A few considerations about this endpoint:

  • You have to provide the current time to recalculate the ETA ("departure_time")
  • It only accepts one vehicle with one tour per request
  • It will maintain the provided order, it will not compute any optimization (VRP or TSP)
  • The predicted ETA/ETD will be based in our traffic estimations.

Below you can see the input information and their corresponding vehicle's data types:

Attributes Mandatory Type Description
vehicle_id Mandatory String The vehicle id identifier
lat Mandatory Double Current vehicle's latitude
lon Mandatory Double Current vehicle's longitude
departure_time Mandatory Time Current time to start the ETA recalculation "HH:mm"

In the tours and node side, this is the attributes:

Attributes Mandatory Type Description
id Mandatory String Visit identifier
lat Mandatory Double Visit latitude
lon Mandatory Double Visit longitude
service_time Mandatory Double Minutes to unload deliveries from the vehicle
order Mandatory Integer Order of visit inside of the tour.

At the moment there is only support one route per tour. If more than one route is sent it will respond with an error.

The request can also include Traffic factor

Attributes Mandatory Type Description
fmv Optional Integer Default: 2.0, Speed traffic factor. It could be 1.0 = Low Traffic, 1.5 = Medium Traffic, 2.0 = High Traffic or 3.0 = Intense Traffic.

You can see an example of the response in the right side of this documentation.

JSON response:

{
    "vehicle": {
        "vehicle_id": "Vehicle 1",
        "lat": -33.45754,
        "lon": -70.92697,
        "departure_time": "09:00"
    },
    "tours": [
        {
            "nodes": [
                {
                    "id": "id1",
                    "lat": -33.45754,
                    "lon": -70.62697,
                    "service_time": 30,
                    "order": 0,
                    "arrival": "09:48",
                    "departure": "10:18"
                },
                {
                    "id": "id2",
                    "lat": -33.45744,
                    "lon": -70.77532,
                    "service_time": 90,
                    "order": 1,
                    "arrival": "10:50",
                    "departure": "12:20"
                },
                {
                    "id": "id3",
                    "lat": -33.45742,
                    "lon": -70.60364,
                    "service_time": 90,
                    "order": 2,
                    "arrival": "13:00",
                    "departure": "14:30"
                }
            ]
        }
    ]
}

Errors

The SimpliRoute API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Review the data type and information sent.
401 Unauthorized -- You are using the wrong API key to request the information.
404 Not Found -- The request didn't found results.
405 Method Not Allowed -- You tried to access to the endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.