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

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, these are the only mandatory fields to create a visit in Simpliroute.

• 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": 200189436,
    "order": null,
    "tracking_id": "SR98278668985242",
    "status": "pending",
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "latitude": "-33.413433",
    "longitude": "-70.585503",
    "load": 39.0,
    "load_2": 100.0,
    "load_3": 0.0,
    "window_start": null,
    "window_end": null,
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": null,
    "reference": "",
    "notes": "",
    "skills_required": [],
    "skills_optional": [],
    "tags": [],
    "planned_date": "2016-06-30",
    "programmed_date": null,
    "route": 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": "2022-09-03T01:19:42.786633Z",
    "modified": "2022-09-03T01:19:42.786633Z",
    "eta_predicted": "2016-06-30T00:00:00-04:00",
    "eta_current": "2016-06-30T00:00:00-04:00",
    "priority": false,
    "has_alert": false,
    "priority_level": null,
    "extra_field_values": null,
    "geocode_alert": null,
    "visit_type": null,
    "current_eta": null,
    "fleet": null,
    "properties": {
      "city": "Santiago"
    },
    "items": [
        {
            "id": 221544,
            "title": "bar",
            "status": "pending",
            "load": 2.0,
            "load_2": 1.5,
            "load_3": 0.0,
            "reference": "bar",
            "visit": 200189436,
            "notes": "",
            "quantity_planned": 2.0,
            "quantity_delivered": 0.0
        },
        {
            "id": 221543,
            "title": "foo",
            "status": "pending",
            "load": 15.0,
            "load_2": 0.0,
            "load_3": 0.5,
            "reference": "foo",
            "visit": 200189436,
            "notes": "",
            "quantity_planned": 1.0,
            "quantity_delivered": 0.0
        }
    ],
    "on_its_way": null
}

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	Timestamp	Time spent in the delivery (HH:mm:ss)
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
reference	String	Reference or internal identifier of the company. Example: Invoice or order number.
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
Tags	Integer array	Array of tag IDs that characterize the visit.
route*	UUID	Unique identifier of the route.YYYY-MM-DD
route_estimated_time_start*	Time	Estimated time that the vehicle will start the route in "HH:mm:ss"
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
checkout_observation*	UUID	Unique identifier of the observation.
signature*	String	Contains the URL with the image of the client's signature..
pictures	URL array	Array with URLs of pictures added with the delivery.
created*	Timestamp	Timestamp of the creation of the visit.
modified*	Timestamp	Timestamp of the last edition of the visit.
driver*	Integer	Driver ID
vehicle*	Integer	Vehicle ID.
has alert*	Boolean	Contains a boolean value to identify an alert...
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.
extra_field_values	String	json object containing attributes and values ​​pre-configured by SimpliRoute.
geocode_alert*	String	Geocoding alert.
visit_type*	String	Contains the URL with the image of the client's signature..
fleet	Integer	Fleet ID.
items	Array Object	Arrangement containing the elements to deliver on the visit.
on its way	Boolean
properties	Object	Extra properties of a visit

The Property Object

Attributes	Data Type	Description
city	String	The city of the visit address
delivery_type	String	Specifies the delivery type: DELIVERY or PICKUP
source	String	The source of the data to be saved: CLIENT
source_ident	String	An identifier used to reference the source, e.g., client ID
merchant	String	The merchant associated with the data

The Items Object

The items object is presented, where you can manage quantities of items for each visit, as well as their partial delivery. To do this, they will be able to create visits with item arrangements by establishing up to 3 loads of the item, reference, notes, quantity planned and delivered.

Items Object example

{
        {
        "id": 64,
        "title": "prueba2",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    }
}

Attributes	Data Type	Description
id	uuid	Unique identifier for the object.
title	String	Title of the item to deliver.route
status	String	Element status: pending, failed, or completed.
load	Double	Space or load that the element occupies in the vehicle.
load_2	Double	Second load unit complementary to the first.
load_3	Dounle	Third load unit complementary to the first and the second
reference	Date	Internal element identifier
notes	String	Additional item notes.
quantity_planned	Float	Planned quantity of the item.
quantity_delivered	Float	Delivered quantity of the item.

Create a visit with items

You can create visit adding quantities of items for each visit, these fields are optional.

URL Definition

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

Example Request

curl --location --request POST 'https://api.simpliroute.com/v1/routes/visits' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "load": 39,
    "load_2": 100,
    "window_start": null,
    "window_end": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "planned_date": "2016-06-30",
    "items": [
      {
          "title": "foo",
          "load": 15,
          "load_3": 0.5     ,
          "reference": "foo",
          "quantity_planned": 1
      },
      {
          "title": "bar",
          "load": 2,
          "load_2": 1.5,
          "reference": "bar",
          "quantity_planned": 2
      }
  ]
}'

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:

Example Request

[ 
    {
    "title": "SimpliRoute3",
    "address": "vespucio norte 22, las condes",
    "load": 39,
    "load_2": 100,
    "window_start": null,
    "window_end": null,
    "duration": "00:00:10",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "planned_date": "2016-06-30",
    "items":
    [
        {
            "title": "foo",
            "load": 15,
            "load_3": 0.5     ,
            "reference": "foo",
            "quantity_planned": 1
        },
        {
            "title": "bar",
            "load": 2,
            "load_2": 1.5,
            "reference": "bar",
            "quantity_planned": 2
            }
        ]
    }
    ]

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/{{visit_id}}\
  -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": 199285905,
        "order": null,
        "tracking_id": "SR17562640764438",
        "status": "pending",
        "title": "SimpliRoute3",
        "address": "vespucio norte 22, las condes",
        "latitude": "-33.413433",
        "longitude": "-70.585503",
        "load": 39.0,
        "load_2": 100.0,
        "load_3": 0.0,
        "window_start": null,
        "window_end": null,
        "window_start_2": null,
        "window_end_2": null,
        "duration": "00:00:10",
        "contact_name": "",
        "contact_phone": "",
        "contact_email": null,
        "reference": "",
        "notes": "",
        "skills_required": [],
        "skills_optional": [],
        "tags": [],
        "planned_date": "2016-06-30",
        "programmed_date": null,
        "route": 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": "2022-08-31T17:32:55.626342Z",
        "modified": "2022-08-31T17:32:55.626342Z",
        "eta_predicted": "2016-06-30T00:00:00-04:00",
        "eta_current": "2016-06-30T00:00:00-04:00",
        "priority": false,
        "has_alert": false,
        "priority_level": null,
        "extra_field_values": null,
        "geocode_alert": null,
        "visit_type": null,
        "current_eta": null,
        "fleet": null,
        "items": [
            {
                "id": 211775,
                "title": "bar",
                "status": "pending",
                "load": 2.0,
                "load_2": 1.5,
                "load_3": 0.0,
                "reference": "bar",
                "visit": 199285905,
                "notes": "",
                "quantity_planned": 2.0,
                "quantity_delivered": 0.0
            },
            {
                "id": 211774,
                "title": "foo",
                "status": "pending",
                "load": 15.0,
                "load_2": 0.0,
                "load_3": 0.5,
                "reference": "foo",
                "visit": 199285905,
                "notes": "",
                "quantity_planned": 1.0,
                "quantity_delivered": 0.0
            }
        ],
        "on_its_way": null
    }
]

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

Adding items to a visit

By means of the following endpoint, one or more items can be added to a certain visit, for this we must have the visit id, which must be entered as part of the structure in the url.

Definition

POST https://api.simpliroute.com/v1/routes/visits/{{VISIT_ID}}/items

Example JSON

[
    {
        "id": 63,
        "title": "prueba1",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    },
    {
        "id": 64,
        "title": "prueba2",
        "status": "pending",
        "load": null,
        "load_2": null,
        "load_3": 5.0,
        "reference": "",
        "notes": "",
        "quantity_planned": 4.0,
        "quantity_delivered": 1.0
    }
]

Delete a visit

To delete a visit, a DELETE call must be made to the SimpliRoute visits service. This is done in the following way:

Definition

DELETE  https://api.simpliroute.com/v1/routes/visits/{{VISIT_ID}}/

Something important is that the elimination of a visit in an already built route does NOT trigger a recalculation of the arrival times of the following points of the route. The only way to do this currently is via the SimpliRoute web interface or manually update the ETAs for each visit with an external calculation.

Delete visit masive

To eliminate multiple visits, a POST type call must be made to the SimpliRoute bulk service. This is done in the following way:

Definition

POST https://api.simpliroute.com/v1/bulk/delete/visits/

Example Request body ``` json { visits: [000000, 000001...] }

The visits array must have the id of the visits that you want to delete.

## Retrieve visits by date

> Definition

```url

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.)

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.

Visit detail

By using the following endpoint you can obtain the detail information of a visit

GET https://api.simpliroute.com/plans/v1/visits/{{VISIT_ID}}/detail/

Example response

{
"window_start":"09:00:00",
"reference":"",
"planned_date":"2017-03-13",
"time_service":"00:00:03",
"window_end":"19:00:00",
"checkout_comment":"",
"duration":"00:20:00",
"estimated_time_arrival":"09:05:00",
"id":89273,
"checkin_time":"2017-03-13T20:17:08Z",
"pictures":[],
"window_start_2":"23:59:00",
"checkout_observation":"Testing",
"latitude":"-33.442880",
"status":"completed",
"checkout_time":"2017-03-13T20:17:11Z",
"window_end_2":"23:59:00",
"vehicle_name":"KILASK31",
"address":"FANOR VELASCO 85, SANTIAGO, Santiago",
"title":"PELUQUERIA DI GIANCARLO",
"longitude":"-70.659729",
"driver_name":"Paperito",
"order":1
}

This endpoint provides more information, including Checkout Comment and Images

Obtain details of the visit

By using the following endpoint you can obtain the detail information of a bulk of visit

URL Definition

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

API validation of time windows - visits

Current situation

When creating/editing a visit, the API does not validate the time windows that are reported in it. This causes that there are eventualities in the optimization.

The two problems found are: - It is not validated that the start time is less than the end - Overlapping time windows is not validated when loading both possible time windows for a visit.

This problem appears only through the API integration, since there are validations in both the manual upload and the Excel upload.

Expected situation

When creating a visit that it has a time windows, the same validation that is used today for manual loading must be replicated, which consists of: - The start time cannot be greater than the end time (Ex: start time 19:00 - end time: 16:00)

• The time window does not extend to the next day (Ex: start time 23:00 - end time: 04:00). Although it complies with the aforementioned validation, it is important to clarify that there is no "Night" time window.

The error message that the API will return is:

Example Time error: the time window order is inverted. Both manual and Excel handle the same messages as before.

For the second mentioned problem you need to validate:

• That time window 1 is NOT later than time window 2 (Ex: window 1 from 12:00 to 14:00 and window 2 from 08:00 to 10:00).

• That there is NO intersection between the two windows (Ex: Window 1 from 12:00 to 14:00 and window 2 from 13:00 to 18:00).

The error message that the API will return is: Time error: the time window order is inverted. Both manual and Excel handle the same messages as before.

For more information, contact your account executive, the support chat or write us an email to [email protected].

Plans management

A plan is a series of Vehicle and Driver pairings for a specific day.

Plan is the entity that encompasses a system execution. To avoid problems, it is suggested that plan creation be done with the plan name as a timestamp. The start-end date of the plan, for general cases, is the day of execution of the plan.

Create Plan

First of all, there are two main objects to consider in a plan:

• Routes → The system entity that encompasses a set of visits
• Visits → Anything that a driver has to do in the street: a service order, a delivery, a pickup Also, we need to know the id of the driver and vehicle that we are going to route, this can be done with the following endpoints: >URL Definition ```url

GET Vehicles: https://api.simpliroute.com/v1/routes/vehicles/ ```

URL Definition url GET Driver: https://api.simpliroute.com/v1/accounts/drivers/

Where we should save the ‘id’ field of each endpoint to use it later on. Once we get those fields, we should be able to create a complete plan using all from above

URL Definition

POST https://api.simpliroute.com/v1/plans/create-plan/

Example request

{
  "name": "Plan created through API 2022-09-02 12:55:18",
  "start_date": "2022-09-02",
  "end_date": "2022-09-02",
  "routes": [
    {
      "driver": "183371",
      "vehicle": "288202",
      "planned_date": "2022-09-02",
      "total_distance": "0",
      "total_duration": "00:38:00",
      "total_load": 0,
      "total_load_percentage": 0,
      "total_load_2": 0,
      "total_load_2_percentage": 0,
      "total_load_3": 0,
      "total_load_3_percentage": 0,
      "estimated_time_start": "08:00:00",
      "estimated_time_end": "08:38:00",
      "request_status": "created",
      "comment": null,
      "location_start_address": "Av. San Borja Sur 486, Cercado de Lima 15036",
      "location_start_latitude": -12.101389,
      "location_start_longitude": -77.004534,
      "location_end_address": "Av. San Borja Sur 486, Cercado de Lima 15036",
      "location_end_latitude": -12.101389,
      "location_end_longitude": -77.004534,
      "visits": [
        {
          "title": "Order 1234",
          "address": "Jirón Vesalio 252, San Borja",
          "latitude": -12.105329,
          "longitude": -77.005524,
          "order": 1,
          "load": 1,
          "window_start": "09:00:00",
          "window_end": "17:00:00",
          "duration": "00:10:00",
          "contact_name": "David Rosales",
          "contact_email": "[email protected], [email protected]",
          "reference": "",
          "notes": "Watch out with the dog!",
          "planned_date": "2022-09-02",
          "estimated_time_arrival": "08:02",
          "estimated_time_departure": "08:12",
          "request_status": "created"
        },
        {
          "title": "Order 4567",
          "address": "Jirón Tasso 423, San Borja",
          "latitude": -12.105779,
          "longitude": -77.019189,
          "order": 2,
          "load": 1,"window_start": "09:00:00",
          "window_end": "17:00:00",
          "duration": "00:10:00",
          "contact_name": "David Rosales",
          "contact_email": "[email protected]",
          "reference": "",
          "notes": "Ask for David",
          "planned_date": "2022-09-02",
          "estimated_time_arrival": "08:20",
          "estimated_time_departure": "08:30",
          "request_status": "created"
        }
      ]
    }
  ]
}

Example response

{
"id": "4363095e-8d7c-46d0-9a14-8c895c37fa88",
"name": "Plan created through API 2022-09-02 12:55:18",
"start_date": "2022-09-02",
"end_date": "2022-09-02",
"reset_day": 1,
"created": "2022-09-02T06:51:24.937690Z",
"modified": "2022-09-02T06:51:24.937690Z",
"is_cluster": false,
"routes": [
"349cd8a2-5149-4732-b46f-1073fb90ea07"
],
"plan_metadata": null,
"start_time": null,
"end_time": null
}
> Example request

```json
{
        "name": "Agosto",
        "start_date": "2016-08-01",
        "end_date": "2016-08-01"
    }

Example response

[{
        "id": "fc65b49f-1f5c-4ca5-9b03-98565e1589f3",
        "name": "Agosto",
        "start_date": "2016-08-01",
        "end_date": "2016-08-01",
        "created": "2016-08-25T15:28:32.400027Z",
        "modified": "2016-08-25T15:28:32.400365Z",
        "is_cluster": false
}]

Important considerations

All parameters in bold are considered important to create plans

Plan

• name must be unique
• start_date and end_date must be the same

Routes

• driver → driver id
• vehicle → vehicle id
• planned_date must be equal to plan’s start_date and end_date
• estimated_time_start → when the vehicle starts to work
• estimated_time_end → when vehicle will end working
• request_status → create a new route

Visits

An array with all the visits of a route. - title → Identifier of the shop or person to deliver (will be displayed on mobile app) - address → Address of the delivery (will be displayed on mobile app) - order → The order in which will be delivered - planned_date → Delivery date - estimated_time_arrival → Arrival - estimated_time_departure → Departure - request_status → create a new visit

The rest of the parameters are not mandatory and should be setted with dummy data if the i nformation is not available.

Routes

Route is the system entity that encompasses a set of visits. On this you can do the typical CRUD operations:

Create routes

URL Definition

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

Example request

[
  {
    "vehicle": 2032,
    "driver": null,
    "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
    "planned_date": "2016-05-20",
    "estimated_time_start": "03:00:00",
    "estimated_time_end": "19:33:00",
    "status": "pending",
    "total_duration": "16:33:00",
    "total_distance": 0,
    "total_load": 2086,
    "total_load_percentage": 0,
    "location_start_address": "Enrique Mac Iver 524, Santiago, Chile",
    "location_start_latitude": "-33.436571",
    "location_start_longitude": "-70.647308",
    "location_end_address": "Suecia 151, Providencia, Chile",
    "location_end_latitude": "-33.421958",
    "location_end_longitude": "-70.607270",
    "reference": "my reference"
  }
]

Example response

[
  {
    "id": "33ddc43b-5ca8-4455-b3af-16a2f1971c1e",
    "vehicle": 2032,
    "driver": null,
    "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
    "status": "pending",
    "planned_date": "2016-05-20",
    "estimated_time_start": "03:00:00",
    "estimated_time_end": "19:33:00",
    "total_duration": "16:33:00",
    "total_distance": 0,
    "total_load": 2086,
    "total_load_percentage": 0,
     "total_load_2": 0.0,
    "total_load_2_percentage": 0,
    "total_load_3": 0.0,
    "total_load_3_percentage": 0,
    "location_start_address": "Enrique Mac Iver 524, Santiago, Chile",
    "location_start_latitude": "-33.436571",
    "location_start_longitude": "-70.647308",
    "location_end_address": "Suecia 151, Providencia, Chile",
    "location_end_latitude": "-33.421958",
    "location_end_longitude": "-70.607270",
    "comment": "Route 1",
    "start_time": null,
    "end_time": null,
    "created": "2016-08-01T20:45:25.672207Z",
    "modified": "2016-08-01T20:45:25.674460Z",
    "kilometers": null,
    "total_visits": 0,
    "latitude_init": null,
    "longitude_init": null,
    "latitude_finish": null,
    "longitude_finish": null,
    "is_revised": false,
    "reference": "my reference"
  }
]

List of Vehicles with routes for a date

URL Definition

GET https://api.simpliroute.com/v1/plans/{{planned_date}}/vehicles/

Example response

[
  {
    "color": "#FFCC33",
    "routes": [
      {
        "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
        "id": "e708c5ba-6d49-4418-b87e-9061e1194b1b"
      }
    ],
    "driver":{
      "id": 742,
      "name": "Conductor Demo"
    },
    "name": "Mi auto",
    "id": 287
  }
]

A Vehicle can have multiple routes for a day. A route is identified by a uuid.

List of Visits by Route

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

Example response

[
  {
    "status": "failed",
    "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
    "reference": "",
    "title": "STARK INDUSTRIES",
    "checkout_time": "2017-03-13T20:17:20Z",
    "longitude": "-70.651066",
    "id": 89274,
    "route_id": "e708c5ba-6d49-4418-b87e-9061e1194b1b",
    "address": "HUERFANOS 1011, SANTIAGO, Santiago",
    "latitude": "-33.439626",
    "estimated_time_arrival": "09:28:00",
    "order": 2
  },
  {
    "status": "completed",
    "plan_id": "f61cd65a-075e-454f-a080-d2c573d2be3e",
    "reference": "",
    "title": "PELUQUERIA DI GIANCARLO",
    "checkout_time": "2017-03-13T20:17:11Z",
    "longitude": "-70.659729",
    "id": 89273,
    "route_id": "2d3ced6c-70e4-414e-8313-d5abe9166a15",
    "address": "FANOR VELASCO 85, SANTIAGO, Santiago",
    "latitude": "-33.442880",
    "estimated_time_arrival": "09:05:00",
    "order": 1
  }
]

A Vehicle can have multiple routes for a day. A route is identified by a uuid.

Update reference field by Route

PATCH https://api.simpliroute.com/v1/routes/routes/{{route_id}}/

Example request

{
  "reference": "my own reference"
}

Example response

{
  "id": "32024005-7b45-455d-b901-f3f9afa2679e",
  "vehicle": 278533,
  "driver": 129373,
  "plan": "ab20be8f-e98e-4402-8519-98d6752e0f1a",
  "status": "pending",
  "planned_date": "2024-02-28",
  "estimated_time_start": "09:00:00",
  "estimated_time_end": "10:54:00",
  "total_duration": "01:54:00",
  "total_distance": 60992,
  "total_load": 0.0,
  "total_load_percentage": 0,
  "total_load_2": 0.0,
  "total_load_2_percentage": 0,
  "total_load_3": 0.0,
  "total_load_3_percentage": 0,
  "location_start_address": "Lord Cochrane 298, Santiago, Chile",
  "location_start_latitude": "-33.449977",
  "location_start_longitude": "-70.654465",
  "location_end_address": "Av. Vicuña Mackenna 2365, Ñuñoa, San Joaquín, Región Metropolitana, Chile",
  "location_end_latitude": "-33.473420",
  "location_end_longitude": "-70.624235",
  "comment": "Route 1",
  "start_time": null,
  "end_time": null,
  "created": "2024-02-28T17:20:37.919471Z",
  "modified": "2024-04-02T20:14:46.945819Z",
  "kilometers": null,
  "total_visits": 2,
  "latitude_init": null,
  "longitude_init": null,
  "latitude_finish": null,
  "longitude_finish": null,
  "is_revised": false,
  "reference": "my own reference"
}

Vehicles

To facilitate the integration flow, the loading of the vehicles of each client can be done via API using the following endpoints. The delivery entity is separate from the vehicle entity in SimpliRoute. This in order to better track vehicle performance or other internal user metrics.

Create vehicles

URL Definition

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

Example Request

{"name": "ASDFQWER",
    "capacity": 2000,
    "default_driver": null,
    "location_start_address": "Direccion A",
    "location_start_latitude": -33.3456,
    "location_start_longitude": -70.2345,
    "location_end_address": "Direccion B",
    "location_end_latitude": -33.34234,
    "location_end_longitude": -70.23456,
    "skills": []
}

Example Response

{
    "name": "ASDFQWER",
    "capacity": 2000,
    "default_driver": null,
    "location_start_address": "a", //(warehouse starting point of the vehicle)
    "location_start_latitude": 0,
    "location_start_longitude": 0,
    "location_end_address": "b",
    "location_end_latitude": 0,
    "location_end_longitude": 0,
    "skills": []
}

List Vehicle

URL Definition

GET https://api.simpliroute.com/v1/routes/vehicles/

Example Response

[{
    "id": 1611,
    "name": "C1-1",
    "capacity": 15000000,
    "default_driver": null,
    "location_start_address": "Avenida Santiago 123, Santiago, Chile",
    "location_start_latitude": "-33.230759",
    "location_start_longitude": "-70.421551",
    "location_end_address": "Suecia, Providencia, Chile",
    "location_end_latitude": "-33.431984",
    "location_end_longitude": "-70.707261",
    "skills": [],
    "created": "2016-04-22T09:35:52.731696Z",
    "modified": "2016-05-01T15:12:05.279745Z"
  }]

Delete vechicle

URL Definition

DELETE https://api.simpliroute.com/v1/routes/vehicles/{VECHICLE_ID}

Customers

A customer is an individual or company. Customers are the end users.

Create Customers

By using the following POST method, the clients/customers can be uploaded to the Simpliroute application, this generates the client master for each one of the accounts that will be registered and that will connect with the Web services of each ERP. Each main Client must have its own token to make the connection and inject the data to the platform

URL Definition

POST https://api.simpliroute.com/v1/accounts/clients/

Example Request

[{
    "key": "123456",
    "title": "Coop Enargas",
    "address": "",
    "latitude": null,
    "longitude": null,
    "load": null,
    "load_2": 0.0,
    "load_3": 0.0,
    "window_start": null,
    "window_end": null,
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:00",
    "contact_name": null,
    "contact_phone": null,
    "contact_email": null,
    "notes": null,
    "priority_level": null
}]

When you create clients, it can be viewed from the client master extension on the Simpliroute platform.

Obtain Customers

Through the GET client method, you can obtain the id and the information related to the client via API, with this information we can generate the visits.

URL Definition

GET https://api.simpliroute.com/v1/accounts/clients/?key={{CLIENT_ID}}

Example Request

[{
  "id": 68156,
    "key": "123456",
    "title": "Cliente Ejemplo",
    "address": "Pedro Montt 2245, Valparaíso, V Región",
    "latitude": "-33.464115",
    "longitude": "-70.652859",
    "load": 4.0,
    "load_2": 2.0,
    "load_3": 1.0,
    "window_start": "09:00:00",
    "window_end": "17:00:00",
    "window_start_2": null,
    "window_end_2": null,
    "duration": "00:00:00",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": "[email protected]",
    "notes": "Notas de Texto",
    "priority_level": null
    }
]

Users

A user for SimpliRoute is a courier who will make deliveries through our mobile app

List users

URL Definition

 GET https://api.simpliroute.com/v1/accounts/drivers/

Example Response ```json [{ "id": 114, "username": "user2", "name": "", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1477, "created": "2016-06-24T20:47:06.859895Z", "modified": "2016-06-30T20:04:51.043122Z", "last_login": null }, { "id": 24, "old_id": 930, "username": "test", "name": "Test", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1477, "created": "2016-06-24T20:47:06.859895Z", "modified": "2016-06-30T20:04:51.043122Z", "last_login": null }]

## Create user

With the following endpoint you can create via API a user

> URL Definition

```url

POST https://api.simpliroute.com/v1/accounts/drivers/

Example Body ```json [{ "username": "testtest2", "name": "Conductor 1", "phone": "", "email": "", "is_admin": false, "password": "driver", "is_driver": true }]

> Example Response
```json
[{
    "id": 40779,
    "username": "testtest2",
    "name": "Conductor 1",
    "phone": "",
    "email": "",
    "is_owner": false,
    "is_admin": false,
    "is_driver": true,
    "is_router_jr": false,
    "is_monitor": false,
    "is_coordinator": false,
    "is_router": false,
    "is_staff": false,
    "old_id": null,
    "created": "2020-03-19T19:13:45.178268Z",
    "modified": "2020-03-19T19:13:45.223900Z",
    "last_login": null
}]

Get a determine user

URL Definition

GET https://api.simpliroute.com/v1/accounts/drivers/{{user_id}}/

Example Response json [ {"id": 203, "username": "driver33", "name": "Driver 3", "phone": "", "email": "", "is_owner": false, "is_admin": false, "is_driver": true, "old_id": 1979, "created": "2016-08-01T20:23:31.966307Z", "modified": "2016-08-01T20:23:32.158526Z", "last_login": null } ]

Update user

URL Definition

PUT https://api.simpliroute.com/v1/accounts/drivers/{{USER_ID}}/

Example Body ```json [{ "username": "driver3", "name": "Driver 3", "email": "", "is_admin": false, "password": "driver" }]

> Example Response
``` json
[{
    "id": 24,
  "old_id": 930,
  "username": "test",
  "name": "Test",
  "created": "2016-03-08T15:54:03.095458Z",
  "modified": "2016-03-08T15:54:03.268615Z",
  "last_login": null}]

Delete user

URL Definition

DELETE https://api.simpliroute.com/v1/accounts/drivers/{{user_id}}/

Skills

Skills are ways to tag our visitors and vehicles so that the algorithm uses those tags as constraints. If a visitor has the required skill "COLD" the vehicles that can transport that dispatch must also have the skill "COLD".

To get the list of skills

URL Definition

GET https://api.simpliroute.com/v1/routes/skills/

Example response

[
  {
    "id": 295,
    "skill": "armijo",
    "created": "2017-01-24T21:06:42.545448Z",
    "modified": "2017-01-24T21:06:42.545683Z"
  },
  {
    "id": 296,
    "skill": "calderon",
    "created": "2017-01-24T21:06:46.328027Z",
    "modified": "2017-01-24T21:06:46.328273Z"
  }
 ]

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 deliverURLs 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.ies 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.

Which events can be notified

Currently, SimpliRoute can notify this events:

• Plan created
• Plan edition
• Route creation
• Route edition
• Route deletion
• Route started
• Route Finish
• Visit created
• Visit updated
• On it`s way
• Checkout
  • Completed delivery
  • Failed delivery
  • Partial Delivery
• Checkout detailed

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]

Configuring your Webhooks settings

We describe the steps to follow to read, create, update and delete webhooks via API

Available webhooks

• plan_created
• plan_edited
• route_created
• route_edited
• route_started
• route_finished
• on_its_way
• visit_checkout
• visit_checkout_detailed

Important: Each webhook is related to a url and headers. For example: route_created is related to: - route_created_webhook_url - route_created_webhook_headers

Additionally, requests must include the header:

Example Headers

[{
    Content-Type: application/json
    authorization: token {{TOKEN}}
}]

// Where {{TOKEN}} equals the SR account token.

Attributes			Description
webhook			Name of the available webhook object.
url			URL provided by the customer
headers			Necessary parameters for communication towards the final server

If you have doubts or problems to configure Webhooks - 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.

Create Webhook

URL Definition

POST https://api.simpliroute.com/v1/addons/webhooks

Example body

{
  "webhook": "plan_created",
  "url": "https://estoesunwebhookdeprueba.com",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Token 16a57ec5ad76c627959c75323274d33d8cc0451e"
  }
}

Example response

[
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Token 16a57ec5ad76c627959c75323274d33d8cc0451e\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  }
]

List Webhooks

URL Definition

GET https://api.simpliroute.com/v1/addons/webhooks

Example response

[
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Token 16a57ec5ad76c627959c75323274d33d8cc0451e\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team",
    "add_on_id": 29950
  }
]

Update Webhooks

URL Definition

PUT https://api.simpliroute.com/v1/addons/webhooks

Example body

{
  "webhook": "plan_created",
  "url": "https://estoesunwebhookdeprueba.com/nueva-url",
  "headers": {
    "Content-Type": "application/json"
  }
}

Example response

[
  {
    "title": "plan_created_webhook_url webhook url",
    "key": "plan_created_webhook_url",
    "value": "https://estoesunwebhookdeprueba.com/nueva-url",
    "description": "plan_created_webhook_url webhook url Luis Bermudez SR Team"
  },
  {
    "title": "plan_created_webhook_headers webhook headers",
    "key": "plan_created_webhook_headers",
    "value": "{\"Content-Type\":\"application/json\"}",
    "description": "plan_created_webhook_headers webhook url Luis Bermudez SR Team"
  }
]

Delete Webhooks

URL Definition

DELETE https://api.simpliroute.com/v1/addons/webhooks

Example body

{
    "webhook": "plan_created"
}

Example response

[{
  "message": "The webhook was deleted"
}]

Webhook Plan creation

SimpliRoute is able to send Webhook for Plan creation, the information available is detailed in the table above at the moment the Plan is created using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

URL Definition

POST https://api.simpliroute.com/v2/plans/create-plan/ 

Example

[{
  "account_id": 295,
  "id": "9503f703-ba7c-41a0-b91f-3bcebeca7b17",
  "start_date": "2020-03-19",
  "end_date": "2020-03-19",
  "reset_day": 1,
  "route_ids": [
    "9894ddcd-e844-4c77-90e8-9d9a2a226f05"
  ],
  "fleet_id": 647
}]

Attributes	Type		Description
id	UUID		Plan ID
account_id	int		Account id.
start_date	Date format YYYY-MM-DD		The date when the plan starts.
end_date	Date format YYYY-MM-DD		The date when the plan ends.
reset_day	Int, 1=Monday, 2=Tuesday…, 100=no reset		The day when the plan resets.
route_ids	Array of uuid		List of the routes in the plan.
fleet_id	int		Id of the fleet assigned to the plan

Webhook Plan edition

SimpliRoute is able to send Webhook when a plan is edited. To use this webhook, the customer should provide a webservice prepared to process POST requests with the information detailed in the tables above.

The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

URL Definition

POST https://api.simpliroute.com/v2/plans/edit-plan/ 

Example

{
 "id": "9b420e42-m492-29m1-a214-f2ad927707b4",
 "account": {
   "id": 1,
   "name": "[email protected]"
 },
 "end_date": "2019-12-24",
 "reset_day": 1,
 "start_date": "2019-12-24",
 "fleet_id": 647,
 "routes": [
   {
     "id": "900787e1-k582-0185-9eeb-d93b68c98b85",
     "planned_date": "2019-12-24",
     "total_load": 50,
     "total_load_2": 0,
     "total_load_3": 0,
     "estimated_time_end": "11:37:00",
     "estimated_time_start": "09:00:00",
     "comment": null,
     "driver": {
       "id": 1,
       "name": "Driver Demo"
     },
     "vehicle": {
       "id": 1,
       "reference": "XXXX11",
       "name": "Vehicle Demo"
     },
     "visits": [
       {
         "id": 20661418,
         "title": "foo",
         "planned_date": "2019-12-24",
         "latitude": "-33.370405",
         "longitude": "-70.684798",
         "load": 0,
         "load_2": 0,
         "load_3": 0,
         "duration": "0:10:00",
         "estimated_time_departure": "09:30:00",
         "estimated_time_arrival": "09:20:00",
         "notes": "",
         "order": 1
       },
       {
         "load": 25,
         "estimated_time_departure": "10:00:00",
         "planned_date": "2019-12-24",
         "load_3": 0,
         "load_2": 0,
         "duration": "0:15:00",
         "estimated_time_arrival": "09:45:00",
         "id": 20661406,
         "title": "bar",
         "notes": "",
         "longitude": "-70.758134",
         "latitude": "-33.384390",
         "order": 2
       },
       {
         "load": 0,
         "estimated_time_departure": "10:24:00",
         "planned_date": "2019-12-24",
         "load_3": 0,
         "load_2": 0,
         "duration": "0:10:00",
         "estimated_time_arrival": "10:14:00",
         "id": 20661420,
         "title": "foo-bar",
         "notes": "",
         "longitude": "-70.703681",
         "latitude": "-33.427045",
         "order": 3
       }       
     ]     
   }
 ]
}

Plan Object

Attributes	Type		Description
id	UUID		Plan ID
account {id, name}	id: int - name: string.		Account information.
start_date	Date format YYYY-MM-DD		The date when the plan starts.
end_date	Date format YYYY-MM-DD		The date when the plan ends.
reset_day	Int, 1=Monday, 2=Tuesday…, 100=no reset		The day when the plan resets.
fleet_id	int		Id of the fleet assigned to the plan
routes	list(Route)		List of the routes in the plan. See Route Object for details.

Route Object

Attributes	Type		Description
id	UUID		Id of the route in SimpliRoute.
planned_date	date (YYYY-MM-DD)		Date of the route
total_load	double		The total load 1 of the route.
total_load2	double		The total load 2 of the route.
total_load_3	double		The total load 3 of the route.
estimated_time_start	time (hh:mm:ss)		Estimated time of the route to start in local timezone of the account.
estimated_time_end	time (hh:mm:ss)		Estimated time of the route to end in local timezone of the account.
comment	string		Comment of the route.
driver {id, name}	id: id of the driver in SimpliRoute- name: name of the driver		Driver information.
vehicle {id, reference, name}	id: id of the vehicle in SimpliRoute.reference: reference id, it could be the licence plate for example.name: name of the vehicle in SimpliRoute		Vehicle information
visits	list(Visit)		List of the visits in the route. See Visit Object for details.

Visit Object

Attributes	Type		Description
id	int		Id of the visit in SimpliRoute.
title	string		Title of the visit.
planned_date	Date format YYYY-MM-DD		Date of the delivery.
latitude	double		The date when the plan ends.
longitude	double		The day when the plan resets.
load	double		Load 1.
load2	double		Load 2.
load3	double		Load 3.
duration	double		Service time of the visit.
estimated_time_arrival	double		Estimated time to arrive to the visit.
estimated_time_departure	double		Estimated time of departure from the visit. It should be estimated_time_arrival + duration.
notes	string		Notes of the visit.
order	int		Order of the visit in the route

Webhook Route creation

SimpliRoute can send Webhooks for route creation, the available information is detailed in the table below. At the time the route is created using the POST method with headers that the client can specify. The webhook expects a response with status code 200; otherwise, it will try again after 30 seconds, a maximum of 3 times in total.

Example body

{
  "id": "e5bb5b51-d494-483f-8180-ace00c89c06d",
  "comment": null,
  "planned_date": "2024-01-12",
  "plan": {
    "id": "1ef9f5c4-2197-41da-8f23-adfcabd272b5",
    "name": "12-01-2024 14:53:03"
  },
  "driver": {
    "id": 118553,
    "name": "rapidoqa1"
  },
  "route_start": {
    "lat": "-33.449977",
    "lon": "-70.654465",
    "address": "Lord Cochrane 298, Santiago, Chile",
    "start_time": null,
    "estimated_time_start": "09:42:00"
  },
  "route_end": {
    "lat": "-33.449977",
    "lon": "-70.654465",
    "address": "Lord Cochrane 298, Santiago, Chile",
    "estimated_time_end": "10:08:00",
    "end_time": null
  },
  "visit_ids": [
    370679703
  ],
  "info_visits": [
    {
      "id": 370679703,
      "reference": "",
      "tracking_id": "SR68561793642931",
      "order": 1
    }
  ],
  "vehicle": {
    "id": 266603,
    "name": "VEH1F",
    "reference": "XXX333"
  },
  "timestamp": "2024-01-30 15:14:45.708968",
  "order": 3,
  "status": "created"
}

Attributes	Type		Description
vehicle {id, name}	id: int - name: string		Vehicle information.
plan {id, name}	id: int - name: string		Plan information
timestamp	timestamp		UTC timestamp of the creation of the route.
route_start {lat, lon, start_time, estimated_time_start, address}	lat: float - lon: float - start_time: time - estimated_time_start: time - address: string		Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
route_end {lat, lon, end_time, estimated_time_end, address}	lat: float - lon: float - end_time: time - estimated_time_end: time- address: string.		Route end information
planned_date	Date in format YYYY-MM-DD.		Date for the route.
visit_ids	id		List of the visit ids in the route.
driver {id, name}	id: int - name: string.		Driver information.
order	int		show the order of the vehicle route.
status	string		Display the operation's status event, 'created'

Webhook Route edition

SimpliRoute can send Webhooks for route edition, the available information is detailed in the table below. At the time the route is updated using the POST method with headers that the client can specify. The webhook expects a response with status code 200; otherwise, it will try again after 30 seconds, a maximum of 3 times in total.

Example body

[
  {  
   "vehicle":{  
      "id":1,
      "name":"Test",
      "reference": "1234FF"
   },
   "plan":{  
      "id":"528e6fa8-129d-4049-9a3c-8ad5ea12502e",
      "name":"Plan name"
   },
   "timestamp":"2019-07-17 14:32:14.799962",
   "route_start":{  
      "lat":"-33.448890",
      "start_time":null,
      "estimated_time_start":"09:00:00",
      "lon":"-70.669265",
      "address":"Santiago, Chile"
   },
   "route_end":{  
      "lat":"-33.448890",
      "lon":"-70.669265",
      "end_time":null,
      "estimated_time_end":"16:23:00",
      "address":"Santiago, Chile"
   },
   "planned_date":"2019-07-17",
   "visit_ids":[15901924, 15901923, 15901922, 15901921, 15901920, 15901919, 15901918, 15901917, 15901916, 15901915, 15901914, 15901913, 15901912, 15901911, 15901910, 15901909],
   "info_visits": [
        {
          "id": 15901924, "reference": "", "tracking_id": "SR88515397622033", "order": 1,
          "id": 15901923, "reference": "", "tracking_id": "SR88515397622034", "order": 2,
          "id": 15901922, "reference": "", "tracking_id": "SR88515397622035", "order": 3,
          "id": 15901921, "reference": "", "tracking_id": "SR88515397622036", "order": 4
        }
    ],
   "driver":{  
      "id":23870,
      "name":"Conductor 1"
   },
   "order":1,
   "status":"edited",
   "id":"51019ab7-c464-4503-bcd6-d00c3d6209f2"
}]

Attributes	Type		Description
vehicle {id, name}	id: int - name: string		Vehicle information.
plan {id, name}	id: int - name: string		Plan information
timestamp	timestamp		UTC timestamp of the creation of the route.
route_start {lat, lon, start_time, estimated_time_start, address}	lat: float - lon: float - start_time: time - estimated_time_start: time - address: string		Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
route_end {lat, lon, end_time, estimated_time_end, address}	lat: float - lon: float - end_time: time - estimated_time_end: time- address: string.		Route end information
planned_date	Date in format YYYY-MM-DD.		Date for the route.
visit_ids	id		List of the visit ids in the route.
info_visits	list(visit)		List of the visits in the route.
driver {id, name}	id: int - name: string.		Driver information.
order	int		show the order of the vehicle route.
status	string		Display the operation's status event, indicating whether the route has been edited or deleted.

Webhook Route started

SimpliRoute is able to send Webhook for route started, the information available is detailed in the table above at the moment the route is started using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

Url Definition

POST https://api.simpliroute.com/v1/events/register/

Example request

curl 
--location 
--request POST 'http://localhost:8000/v1/events/register/' \
--header 'Authorization: Token b2de5a16bccec465aeb9083a4db41e1666520uij' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "date_time" : "2020-05-27 16:35:00",
    "route_id": "402ecd99-a0c9-418c-9cd9-088a0cb70242",
    "type" : "ROUTE_STARTED"
}'

Example

[
{
  "vehicle": {
    "id": 101174,
    "name": "KGST"
  },
  "plan": {
    "id": "728c5d34-ff14-4ccf-9fd8-16257f4332e9",
    "name": "26-05-2020 21:37:25"
  },
  "timestamp": "2020-05-27 20:43:40.650476",
  "route_start": {
    "lat": "-33.459425",
    "start_time": "2020-05-27 16:35:00+00:00",
    "estimated_time_start": "09:00:00",
    "lon": "-70.654531",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "route_end": {
    "lat": "-33.459425",
    "lon": "-70.654531",
    "end_time": null,
    "estimated_time_end": "09:15:00",
    "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile"
  },
  "planned_date": "2020-05-26",
  "visit_ids": [
    32397185
  ],
  "driver": {
    "id": 26351,
    "name": "Flash"
  },
  "id": "e1d12cf7-25c6-4f01-98d5-83a52c9b3aed"
}
]

Attributes	Type		Description
vehicle {id, name}	id: int - name: string		Vehicle information.
plan {id, name}	id: int - name: string		Plan information
timestamp	timestamp		UTC timestamp of the creation of the route.
route_start {lat, lon, start_time, estimated_time_start, address}	lat: float - lon: float - start_time: time - estimated_time_start: time - address: string		Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
route_end {lat, lon, end_time, estimated_time_end, address}	lat: float - lon: float - end_time: time - estimated_time_end: time- address: string.		Route end information
planned_date	Date in format YYYY-MM-DD.		Date for the route.
visit_ids	id		List of the visit ids in the route.
driver {id, name}	id: int - name: string.		Driver information.
id	id		String with the route id.

Webhook Route Finish

SimpliRoute is able to send Webhook for finished route, the information available is detailed in the table above at the moment the route is started using POST method with headers that can be specified by the customer. The webhook is expecting a response with status code 200, otherwise it will retry after 30 seconds a maximum of 3 times total.

Url Definition

POST https://api.simpliroute.com/v1/events/register/

Example request

curl 
--location 
--request POST 'http://localhost:8000/v1/events/register/' \
--header 'Authorization: Token b2de5a16bccec465aeb9083a4db41e1666520uij' \
--header 'content-type: application/json;charset=UTF-8' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "date_time" : "2020-05-27 17:35:00",
    "route_id": "402ecd99-a0c9-418c-9cd9-088a0cb70242",
    "type" : "ROUTE_FINISHED"
}'

Example json [{ "vehicle": { "id": 101174, "name": "KGST" }, "plan": { "id": "728c5d34-ff14-4ccf-9fd8-16257f4332e9", "name": "26-05-2020 21:37:25" }, "timestamp": "2020-05-27 20:46:01.471879", "route_start": { "lat": "-33.459425", "start_time": "2020-05-27 16:35:00+00:00", "estimated_time_start": "09:00:00", "lon": "-70.654531", "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile" }, "route_end": { "lat": "-33.459425", "lon": "-70.654531", "end_time": "2020-05-27 17:35:00+00:00", "estimated_time_end": "09:15:00", "address": "Aldunate 1047, Santiago, Región Metropolitana, Chile" }, "planned_date": "2020-05-26", "visit_ids": [ 32397185 ], "driver": { "id": 26351, "name": "Flash" }, "id": "e1d12cf7-25c6-4f01-98d5-83a52c9b3aed" } ]

Attributes	Type		Description
vehicle {id, name}	id: int - name: string		Vehicle information.
plan {id, name}	id: int - name: string		Plan information
timestamp	timestamp		UTC timestamp of the creation of the route.
route_start {lat, lon, start_time, estimated_time_start, address}	lat: float - lon: float - start_time: time - estimated_time_start: time - address: string		Route start information. start_time is the time that the driver started the route, so it will be null always at this point, but if we extend this webhook in the future for edition it will have the “real” start_time.
route_end {lat, lon, end_time, estimated_time_end, address}	lat: float - lon: float - end_time: time - estimated_time_end: time- address: string.		Route end information
planned_date	Date in format YYYY-MM-DD.		Date for the route.
visit_ids	id		List of the visit ids in the route.
driver {id, name}	id: int - name: string.		Driver information.

Webhook On it`s way

SimpliRoute can send visit information at the time an on 'its way' event is launched by calling a POST method to a webservice provided by clients, the available information is described in the following table (not necessarily in that order) . The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

Example body

Attributes	Type		Description
id	int	Id of the visit in SimpliRoute.
load	double	Load 1.
load2	double	Load 2.
load3	double	Load 3.
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
reference	String	Reference or internal identifier of the company. Example: Invoice or order number.
planned_date date	YYYY-MM-DD	Date for the route.
order	int	planned delivery order
checkout_comment	text	Comments on delivery time
duration	time	Service time
calculated_service_time	time	Calculated service time
title	varchar(254)	Visit Title.
contact_name	varchar(254)	Contact name
contact_email	text	e-mail contat
contact_phone	varchar(254)	Contact phone
notes	text	Notes of the visit	.
latitude	numeric(9,6)	Latitud of the visit
longitude	numeric(9,6)	Longitud of the visit
status	varchar(100)	Status of the visit: pending, completed or failed.
address	varchar(254)	Address of the visit
account	varchar(254)	Account name
route	varchar(254)	Route name.
status_changed	timestamp	Date and time of the last status change.
priority_level	int	Visit priority.
created	timestamp	Creation time of the visit.
modified	timestamp	Time of the last modification of the visit.
estimated_time_arrival	time	estimated time of arrival to the visit.
current_eta	date	Estimated time of arrival of the visit.
estimated_time_departure	time	estimated time of departure from the visit.
tracking_id	varchar(254)	Tracking id.
signature	varchar(100)	Address where the signature is stored
checkin_time	timestamp	Arrival time at visit (by GPS driver).
checkin_latitude	numeric(9,6)	Latitude of arrival at the visit.
checkin_longitude	numeric(9,6)	Longitude of arrival at visit.
checkout_longitude	numeric(9,6)	Longitude of checkout.
checkout_observation	uuid	Id of the observation selected at checkout.
checkout_latitude	numeric(9,6)	Latitude of checkout
checkout_time	timestamp	Checkout date and time.
geocode_alert	varchar(22)	Alert when georeferencing the address.
postal_code	varchar(15)	Zip Code if the visit.
programmed_date	date	Scheduled date of visit.
visit_type	json	Type of the visit that is being made.
fleet	json	Information of the fleet to which the visit belongs.
has_alert	boolean	Deprecated.
priority	boolean	Deprecated.

Webhook Checkout

SimpliRoute can send information about the visit at the time of checkout through a POST method call to a webservice provided by clients, the available information is described in the following table (not necessarily in that order). The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

Example body

Ejemplo:
[{
   "id": 18843965,
   "load": 0.0,
   "load_2": 0.0,
   "load_3": 0.0,
   "window_start": "09:00:00",
   "window_end": "19:00:00",
   "window_start_2": "23:59:00",
   "window_end_2": "23:59:00",
   "reference": "",
   "planned_date": "2019-09-09",
   "order": 4,
   "checkout_comment": "Test",
   "duration": "0:20:00",
   "calculated_service_time": "0:00:00",
   "title": "INDUSTRIAS RIC\u00d3N",
   "contact_name": "Victor Gonzalez",
   "contact_email": "",
   "contact_phone": "978567812",
   "notes": "",
   "latitude": "-33.439046",
   "longitude": "-70.648752",
   "status": "completed",
   "address": "HUERFANOS 835 OF. 202, SANTIAGO, Santiago",
   "account": "[email protected]",
   "route": "2019-09-09 - Test",
   "status_changed": "2019-09-09 21:23:01.251595+00:00",
   "priority_level": 0,
   "created": "2019-08-29 22:33:44.015108+00:00",
   "modified": "2019-09-09 21:23:01.251582+00:00",
   "estimated_time_arrival": "10:12:00",
   "estimated_time_departure": "10:32:00",
   "tracking_id": "SR67118024023080",
   "signature": "visit-signatures/2019/09/09/ac6bf49a-35b.png",
   "checkin_time": null,
   "checkin_latitude": null,
   "checkin_longitude": null,
   "checkout_observation": null,
   "checkout_latitude": "-33.420471",
   "checkout_longitude": "-70.603384",
   "checkout_time": "2019-09-09 21:22:56.068000+00:00",
   "on_its_way": null,
   "geocode_alert": null,
   "has_alert": false,
   "priority": false
}]

Attributes	Type		Description
id	int		Id of the visit in SimpliRoute
load	double		Load 1
load2	double		Load 2
load3	double		Load 3
window_start	time		Start time window 1. Format HH:MM:SS
window_end	time		End time window 1. Format HH:MM:SS
window_start_2	time		Start time window 2. Format HH:MM:SS
window_end_2	time		End time window 2. Format HH:MM:SS.
reference	varchar(254)		Visit reference
planned_date	date		Delivery date. Format YYYY-MM-DD
order	int		Planned delivery order
checkout_comment	string		Comments upon delivery
duration	time		Service time of the visit
checkout_comment	string		Comments upon delivery
duration	time		Service time
calculated_service_time	time		Calculated service time
title	varchar(254)		Title of the visit
contact_name	varchar(254)		Contact name
contact_email	string		Contact e mail
contact_phone	varchar(254)		Contact phone number
notes	string		Notes of the visit
latitude	double		Latitude of the visit
longitude	double		Longitude of the visit
status	varchar(100)		Status of the visit: pending, completed, failed, partial
address	varchar(254		Address of the visit
account	varchar(254		Account name
route	varchar(254		Route name
status_changed	timestamp		Date and time of the last status change
priority_level	integer		Priority of the Visit. Ej 1 high priority, 2 second priority
created	timestamp		Creation time of the visit.
modified	timestamp		Time of the last modification of the visit.
estimated_time_arrival	time		Estimated time of arrival for the visit
estimated_time_departure	time		Estimated time of departure from the visit.
tracking_id	varchar(254)		Id of tracking
signature	varchar(100)		Address where the signature is stored.
checkin_time	timestamp		Arrival time for the visit (by GPS driver).
checkin_latitude	double		Latitude of arrival at the visit
checkin_longitude	doube		Longitude of arrival at the visit
checkout_observation	uuid		Id of the observation selected at checkout
checkout_latitude	double		Checkout latitude
checkout_longitude	double		Checkout longitude
checkout_time	timestamp		Checkout date and time
on_its_way	timestamp		Date and time when “On its way” was marked.
geocode_alert			Alert when georeferencing the address

Webhook Checkout detailed

SimpliRoute can send detailed information about the visit at the time of checkout through a POST method call to a webservice provided by the clients, the information available is described in the following table (not necessarily in that order). The webhook expects to get a response with code 200, it will retry every 30 seconds with a maximum of 3 attempts.

Example

[{
    "load": 50.0,
    "window_start": "09:00:00",
    "reference": "96018725010003",
    "planned_date": "2020-09-02",
    "has_alert": false,
    "address": "SANTA MARIA 2670, PROVIDENCIA, Santiago",
    "load_3": 0.0,
    "load_2": 0.0,
    "programmed_date": null,
    "window_end": "19:00:00",
    "postal_code": null,
    "longitude": "-70.609643",
    "duration": "0:20:00",
    "status_changed": "2020-09-02 22:36:12.886508+00:00",
    "contact_name": "Paulina Mu\u00f1oz",
    "id": 44678051,
    "window_start_2": "23:59:00",
    "visit_type": null,
    "title": "CONFITERIA SAN RODRIGO",
    "pictures": [
    "https://simpli-visit-images-dev.s3.amazonaws.com/visit-pictures/2020/09/02/vi93grwrv.jpg"
    ],
    "checkout_longitude": "-122.406417",
    "priority": false,
    "checkout_observation": null,
      "latitude": "-33.416713",
    "contact_phone": "967603803",
    "status": "completed",
    "estimated_time_departure": "09:37:00",
    "route": {
    "comment": "Comentario",
    "vehicle": { 
    "id": 153969, 
    "name": "asd",
    "reference": "1234FF"
},
"plan": {
"id": "9ab4c716-020d-44cd-a90c-4dc88cabf884",
                "name": "2-09-2020 18:34:49"
        },
        "timestamp": "2020-09-02 22:36:16.361577",
        "route_start": {
                "lat": "-33.415468",
                "start_time": "2020-09-02 22:35:48.034000+00:00",
                "estimated_time_start": "09:00:00",
                "lon": "-70.667961",
                "address": "Avenida Domingo Santa Mar\u00eda 12, Independencia, Chile"
        },
        "route_end": {
                "lat": "-33.415468",
                "lon": "-70.667961",
                "end_time": null,
                "estimated_time_end": "11:41:00",
                "address": "Avenida Domingo Santa Mar\u00eda 12, Independencia, Chile"
        },
        "planned_date": "2020-09-02",
        "visit_ids": [44678051, 44678052, 44678053, 44678054, 44678055],
        "driver": { "id": 75388, "name": "f" },
        "id": "e05b954e-754d-4774-b91b-000859eef55b"
    },
    "window_end_2": "23:59:00",
    "extra_field_values": {
        "numero_interior": null,
        "cantidad": null,
        "codigo_postal": null,
        "entre_calles_1": null,
        "edificio": null,
        "comentarios": null,
        "remision": null
    },
    "checkout_time": "2020-09-02 22:36:12.330000+00:00",
    "geocode_alert": null,
    "contact_email": "[email protected]",
    "current_eta": null,
    "calculated_service_time": "0:00:00",
    "account": { "id": 28387, "name": "11FabianUrrutia" },
    "priority_level": 0,
    "checkout_latitude": "37.785834",
    "observation": {},
    "created": "2020-09-02 22:35:01.950457+00:00",
    "on_its_way": null,
    "checkin_time": null,
    "modified": "2020-09-02 22:36:12.886496+00:00",
    "checkout_comment": "Comentario del conductor",
    "order": 1,
    "estimated_time_arrival": "09:17:00",
    "tracking_id": "SR99086101951738",
    "signature": "",
    "checkin_latitude": null,
    "fleet": null,
"notes": "",
    "checkin_longitude": null,
    "plan": {
        "route_ids": ["e05b954e-754d-4774-b91b-000859eef55b"],
        "fleet_id": null,
        "name": "2-09-2020 18:34:49",
        "end_date": "2020-09-02",
        "reset_day": 1,
        "id": "9ab4c716-020d-44cd-a90c-4dc88cabf884",
        "account_id": 28387,
        "start_date": "2020-09-02"
}
}
]

Attributes	Type		Description
id	int		Id of the visit in SimpliRoute
load	double		Load 1
load2	double		Load 2
load3	double		Load 3
window_start	time		Start time window 1. Format HH:MM:SS
window_end	time		End time window 1. Format HH:MM:SS
window_start_2	time		Start time window 2. Format HH:MM:SS
window_end_2	time		End time window 2. Format HH:MM:SS.
reference	varchar(254)		Visit reference
planned_date	date		Delivery date. Format YYYY-MM-DD
order	int		Planned delivery order
checkout_comment	string		Comments upon delivery
duration	time		Service time of the visit
checkout_comment	string		Comments upon delivery
duration	time		Service time
calculated_service_time	time		Calculated service time
title	varchar(254)		Title of the visit
contact_name	varchar(254)		Contact name
contact_email	string		Contact e mail
contact_phone	varchar(254)		Contact phone number
notes	string		Notes of the visit
latitude	double		Latitude of the visit
longitude	double		Longitude of the visit
status	varchar(100)		Status of the visit: pending, completed, failed, partial
address	varchar(254		Address of the visit
account	varchar(254)		Account name
account.id	integer		Id of the account
account.name	varchar(254)		Account namme
route	varchar(254)		Route name
route.id	varchar(254)		Id of the route
route.comment	varchar(254)		Route name
route.driver	varchar(254)		Route name
route.driver.id	varchar(254)		Route name
route.driver.name	varchar(254)		Route name
route.plan	varchar(254)		Route name
route.plan.id	varchar(254)		Route name
route.plan.name	varchar(254)		Route name
route.route_start	varchar(254)		Route name
route.route_start.address	varchar(254)		Route name
route.route_start.estimated_time_start	varchar(254)		Route name
route.route_start.lat	varchar(254)		Route name
route.route_start.lon	varchar(254)		Route name
route.route_start.start_time	varchar(254)		Route name
route.route_end	varchar(254)		Route name
route.route_end.address	varchar(254)		Route name
route.route_end.estimated_time_start	varchar(254)		Estimated completion time
route.route_end.lat	double		Latitude of the end of the route.
route.route_end.lon	double		Longitude of the end of the route
route.route_end.end_time	time		Real moment of the end of the route
route.timestamp	date		Current time of information request.
route.vehicle	json		Contains route vehicle information.
route.vehicle.id	integer		Id of the vehicle of the route.
route.vehicle.name	varchar(254)		Route vehicle name.
route.visit_ids	array		Array with a list of visits corresponding to the assigned checkout route
route.planned_date	date	Date of the route planning.
status_changed	timestamp		Date and time of the last status change
priority_level	integer		Priority of the Visit. Ej 1 high priority, 2 second priority
created	timestamp		Creation time of the visit.
modified	timestamp		Time of the last modification of the visit.
estimated_time_arrival	time		Estimated time of arrival for the visit
estimated_time_departure	time		Estimated time of departure from the visit.
tracking_id	varchar(254)		Id of tracking
signature	varchar(100)		Address where the signature is stored.
checkin_time	timestamp		Arrival time for the visit (by GPS driver).
checkin_latitude	double		Latitude of arrival at the visit
checkin_longitude	doube		Longitude of arrival at the visit
checkout_observation	uuid		Id of the observation selected at checkout
checkout_latitude	double		Checkout latitude
checkout_longitude	double		Checkout longitude
checkout_time	timestamp		Checkout date and time
on_its_way	timestamp		Date and time when “On its way” was marked.
geocode_alert	varchar (22)		Alert when georeferencing the address
pictures	array		Array with urls of the photos added to the visit.
postal_code	varchar (15)		Postal code of the visit.
programmed_date	date		Scheduled date of visit.
visit_type	json		Type of the visit that is being made.
extra_fields_values	array		Extra values ​​of the visit. Format: [{“key”:”value”}]
current_eta	date		Estimated time of arrival to the visit.
observation	json		Contains observation information added to the visit
observation.id	integer		Id of the Observation
observation.labe	varchar (254)		Observation visit label
fleet	json		Information of the fleet to which the visit belongs.
plan	json		Contains plan information associated with the visit
plan.id	uuid		id of the plan associated with the visit.
plan.route_ids	array		Array with id of the plan routes.
plan.fleet_id	integer		id of the fleet which the plan belongs
plan.name	varchar (254)		Name of the plan
plan.end_date	date		Plan termination date.
plan.reset_day	integer		Plan reset time.
plan.account_id	id		Id of the account assigned to the plan
plan.start_date	date		Plan start date

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",
    "refill": 30,     
    "skills": [
        "47076"
        "47054"
    ],
    "zones": [
        14730
    ],
    "max_tour_duration": 40,
    "cost": 100,
    "min_load": 0,
    "min_load_2": 0,
    "min_load_3": 0,
    "max_visit": 35,
    "max_number_of_routes": 2
}]

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.
zones	Optional	Integer array	Identifiers of the zones to which the vehicle belongs. A vehicle can belong to more than one zone.
max_tour_duration	Optional	Integer	Maximum minutes that the vehicle is allowed to make all its routes.
min_load	Optional	Integer	Percentage of minimum load associated with capacity attribute that the vehicle must have to go out on the road.
min_load_2	Optional	Integer	Percentage of minimum load associated with capacity_2 attribute that the vehicle must have to go out on the road.
min_load_3	Optional	Integer	Percentage of minimum load associated with capacity_3 attribute that the vehicle must have to go out on the road.
max_visit	Optional	Integer	Maximum number of visits that the routes carried out by the vehicle can have.
max_number_of_routes	Optional	Integer	Maximum number of routes that each vehicle can have. If the value is 0 or null, the maximum is infinity.
open_start	Optional	Boolean	When true, this feature allows vehicles to begin their routes from locations other than the depot. It's false by default.

Deliveries

Delivery's object example:

[{
    "nodes": [
        {
            "ident": "Delivery 1",
            "group_id": "Delivery 1",
            "lat": -33.3887,
            "lon": -70.62304
        },
        {
            "ident": "Delivery 2",
            "group_id": "Delivery 1",
            "address": "Ricardo Flores Magon # 28. Nave 12. Parque industrial San Jeronimo Caleras. San Jeronimo Caleras, Pue.",
            "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": [
                30744,
                47593
            ],
            "skills_optional": [
                30567
            ],
            "priority_level": 2,
            "zones": [
                14730
            ]
        }
    ]
}]

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	Float	Latitude of the delivery's location.
lon	Mandatory	Float	Longitude of the delivery's location.
address	Optional	String	Address of the delivery. If there are lat and lon attributes, it will privilege those fields over this
group_id	Optional	String	Identifier of the delivery to which this delivery will be linked when using join_v2 (see optimization options).
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	Integer array	Skills this delivery needs to be fulfilled. Only the vehicles who have all of these skills will attend the delivery.
skills_optional	Optional	Integer 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.
zones	Optional	Integer array	Identifier of the zone to which this delivery belongs. Only vehicles that have this area will attend the delivery.

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
country	Mandatory	String	ISO code referring to the country where the delivery locations are located.
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	Float	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.
join_v2	Optional	Boolean	Default: False. If true, the algorithm performs a union of visits with the same address, respecting the capacity of the vehicles, and seeking to minimize the number of vehicles that have similar visits.
beauty	Optional	Boolean	Default: False. If true, the algorithm groups visits into clusters and creates routes within these clusters.
fmb	Optional	Integer	Default: 5. Clustering factor. It could be 1.0 = Zero Clustering, 2.0 = Low Clustering, 3.0 = Medium Clustering, 4.0 = High Clustering or 5.0 = Intense Clustering
use_euclidean_distance	Optional	Boolean	Default: False. If true, it is considered as the distance between two locations, the direct line that joins both nodes.
autoZone	Optional	Boolean	Default: False. If true, the algorithm assigns the vehicles that serve each specified zone in the visits.
intensive_intra	Optional	Boolean	Default: False. If true, the algorithm performs a more intensive search on the solution space. Response time may increase.
open_routes_logic	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, BUT it does.
vehicle_capacities_increment	Optional	Integer	Default: 0. Percentage increase in load capacity of all vehicles.
vehicle_journey_extention	Optional	Integer	Default: 0. Percentage of increase in the time window of all vehicles.
enable_soft_window	Optional	Boolean	Default: False. If true, it allows not respecting the deliveries time windows, but seeking to minimize the total delay time.
isReorder	Optional	Boolean	Default: False. When enabled, this feature will try to insert all nodes, considering only the first time windows. If this is not achievable, it will try again ignoring the time window constraints.

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:00",
                            "ident": "depot_1_start",
                            "lon": -70.6104996,
                            "departure": "00:00:00",
                            "lat": -33.4233926,
                            "order": 0,
                            "priority": null,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:17:00",
                            "ident": "3",
                            "lon": -70.5534688,
                            "departure": "00:17:00",
                            "lat": -33.333413,
                            "order": 1,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:39:00",
                            "ident": "2",
                            "lon": -70.653234,
                            "departure": "00:39:00",
                            "lat": -33.4334123,
                            "order": 2,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "load": 0,
                            "arrival": "00:40:00",
                            "ident": "1",
                            "lon": -70.6509688,
                            "departure": "00:40:00",
                            "lat": -33.436135,
                            "order": 3,
                            "priority": 0,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        },
                        {
                            "arrival": "01:42:00",
                            "ident": "depot_1_start",
                            "lon": -70.6104996,
                            "departure": "01:42:00",
                            "lat": -33.4233926,
                            "order": 4,
                            "priority": null,
                            "load": 0,
                            "load_2": 0,
                            "load_3": 0
                        }
                    ]
                }
            ]
        }
    ],
    "num_vehicles_used": 1,
    "filteredClientsNodes": [],
    "unattendedClientsNodes": []
}

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.

Optimization Response

The optimization response, which is the ouput optimization, can be divided into these sections:

• Vehicles: Array of vehicles from the Json input.
• Tours: Array of tours. A tour is the list of all the routes that the vehicle takes from the beginning of its journey until its end.
• Nodes: Array of deliveries that were included in some route.
• num_vehicles_used: Number of vehicles used to create the routes.
• filteredClientsNodes: Array of deliveries' ident that were removed from the Optimization input before optimizing the routes, due to the impossibility of serving them due to the constraints of the problem.
• unattendedClientsNodes: Array of deliveries' ident, not filtered, that could not be included in some route during the optimization of the problem.

Some of the attributes that the nodes have in the optmization response are the same as those sent in the request, except for these:

Attributes	Type	Description
arrival	String	String "HH:mm:ss" (military time). Vehicle arrival time at delivery.
departure	String	String "HH:mm:ss" (military time). Vehicle departure time from delivery.
order	Integer	Order in which delivery is visited.

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.

Pick-up and Delivery

Job object example: one pick node.

{
  "jobs": [
    {
      "pickNodes": [
        {
          "ident": "OnlyPickUp_1",
          "lat": -22.931935311303512,
          "lon": -43.39394580787891,
          "duration": 11,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }],
    "deliveryNodes": [
      ]}
  ]
}

Job object example: one delivery node.

{
  "jobs": [
    {
      "pickNodes": [
      ],
      "deliveryNodes": [
        {
          "ident": "OnlyDelivery_1",
          "lat": -22.928792360672404,
          "lon": -43.389912163599,
          "duration": 12,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }]}
  ]
}

Job object example: one pick node and one delivery node.

{
  "jobs": [
    {
      "pickNodes": [
        {
          "ident": "PickUp_1",
          "lat": -22.92770862905761,
          "lon": -43.37154320004268,
          "duration": 29,
          "load": 2,
          "load_2": 1,
          "load_3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }],
      "deliveryNodes": [
        {
          "ident": "Delivery_1",
          "group":[],
          "lat": -22.930334385243487,
          "lon": -43.390728465304214,
          "duration": 3,
          "load": 2,
          "load2": 1,
          "load3": 1,
          "window_start": "09:00",
          "window_end": "23:59",
          "skills_required": [],
          "skills_optional": [],
          "priority_level": 0
    }]}
  ]
}

One of the variants supported by the routing algorithm is the Pick-up and Delivery Problem. In this problem, nodes are divided into two categories that serve different goals: picks and deliveries. While a pick is meant to pick up load from a fixed location, a delivery has to take it to its destination.

The fundamental unit of this problem is known as a job, which consists of a group of nodes. Each job falls into one of the following three cases:

• One pick node: in this case, after visiting the node, the driver will pick and transport its load in the vehicle until the next depot.
• One delivery node: in this case, when the driver arrives at the node, it delivers the load that comes originally from a depot.
• One pick node and one delivery node: in this scenario, the driver must first pass through the pick-up node to pick up the load, which consequently must be taken to a specific delivery node.

Regarding the capacity constraint, it should be noted that the total load of a vehicle changes dynamically depending on whether it picks up or delivers load during the route.

The optimization input is a JSON object that has a similar structure to the regular optimization case. It is composed of optimization options, a list of vehicles and a list of jobs (instead of nodes). Each job in turn is composed of a list of pick nodes and a list of delivery nodes, to cover the three job cases explained above. In order to use this mode, the request must be sent to the following endpoint: https://optimizer.simpliroute.com/pd/optimize/sync/.

A pickNode or deliveryNode is very similar to the node (delivery) object that was previously defined and is compatible with the following attributes:

Attributes	Mandatory	Type	Description
ident	Mandatory	String	Unique identifier for the object.
lat	Mandatory	Float	Latitude of the pick or delivery's location.
lon	Mandatory	Float	Longitude of the pick or delivery's location.
address	Optional	String	Address of the pick or delivery. If there are lat and lon attributes, it will prioritize those fields over this.
load	Optional	Float	Load of this pick or delivery. Must be on same units as vehicle's load.
load_2	Optional	Float	Secondary load of this pick or delivery. Must be on same units as vehicle's load 2.
load_3	Optional	Float	Third load of this pick or delivery. Must be on same units as vehicle's load 3.
window_start	Optional	String	String "HH:mm" (military time). Minimum time this pick or delivery can be visited.
window_end	Optional	String	String "HH:mm" (military time). Maximum time this pick delivery can be visited.
window_start_2	Optional	String	String "HH:mm" (military time). Secondary minimum time this pick or 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 pick or delivery can be attended.
duration	Optional	Integer	Minutes that the vehicle will stay on the pick or delivery.
skills_required	Optional	Integer array	Skills this pick or delivery needs to be fulfilled. Only the vehicles who have all of these skills will visit it.
skills_optional	Optional	Integer array	Skills this pick or delivery needs to be fulfilled. Only the vehicles who have at least one of these skills will visit it.
priority_level	Optional	Integer	Used to indicate this pick or 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.

Rest Time (Routes with a break time)

Example of Vehicles Object with rest time

{
       "vehicles": [
        {
            "ident": "159331",
            "location_start": {
                "ident": "vehicle-start-159331",
                "lat": -33.405976,
                "lon": -70.652035
            },
            "location_end": {
                "ident": "vehicle-end-159331",
                "lat": -33.405976,
                "lon": -70.652035
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "11:00",
            "shift_end": "23:00",
            "skills": [
                "32073",
                "32074"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        },
        {
            "ident": "159351",
            "location_start": {
                "ident": "vehicle-start-159351",
                "lat": -33.594771,
                "lon": -70.520194
            },
            "location_end": {
                "ident": "vehicle-end-159351",
                "lat": -33.594771,
                "lon": -70.520194
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "08:00",
            "shift_end": "14:00",
            "skills": [
                "32076"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        },
        {
            "ident": "159349",
            "location_start": {
                "ident": "vehicle-start-159349",
                "lat": -33.486415,
                "lon": -70.609595
            },
            "location_end": {
                "ident": "vehicle-end-159349",
                "lat": -33.486415,
                "lon": -70.609595
            },
            "capacity": 10.0,
            "capacity_2": 1.0,
            "capacity_3": 1.0,
            "shift_start": "08:00",
            "shift_end": "14:00",
            "skills": [
                "32073"
            ],
            "refill": 0,
            "rest_time_start": "12:00",
            "rest_time_end": "14:00",
            "rest_time_duration": 60
        }
    ],
    "enable_rest_time": true
}

Our algorithm can consider a defined rest time for each vehicle (driver) in order to take a break in the journey that must be traveled during the day. This feature considers only a pause in the route of a vehicle, at a time defined in the request.

In order to use Rest Time, you must use the same route optimization endpoint that is used for regular optimizations, but adding some optional parameters in the vehicles object for each vehicle. In addition, you must turn on an additional parameter that allows you to use this feature. Only the vehicles that have the additional parameters are considered with a rest time.

These are the new parameters you can add:

Attributes	Mandatory	Type	Description
rest_time_start	Mandatory	String	String "HH:mm" (military time). Minimum time in which this vehicle must take the rest period. This time must be less than the shift end attribute.
rest_time_end	Mandatory	String	String "HH:mm" (military time). Maximum time in which this vehicle must take the rest period. This time must be greater than the shift start attribute.
rest_time_duration	Mandatory	Integer	Minutes that this vehicle will remain in a rest time. This duration must be less than or equal to the time window established to take the break.
enable_rest_time	Optional	Boolean	Default: False. If true, the vehicles considering a rest time on the route, which is defined with the previous parameters.

Incremental Routing (Vehicles with previously created routes)

Example of Vehicle object with pre-created routes for each vehicle

{
  "vehicles": [
    {
      "ident": "7247",
      "location_start": {
        "ident": "7247",
        "lat": -21.6698437,
        "lon": -49.7495409
      },
      "shift_start": "09:12",
      "shift_end": "18:00",
      "partial_tour": {
        "ident": "7247",
        "partial_routes": [
          {
            "nodes": [
              "18112000205726",
              "10081834157634",
              "10089320449243"
            ],
            "fixed_nodes_number": 2
          },
          {
            "nodes": [
              "10089034859206",
              "18162900171426",
              "18109901985501",
              "18162900171339"
            ],
            "fixed_nodes_number": 3
          }
        ]
      }
    }
  ],
    "incremental_routing": true
}

In some scenarios, there are routes already created and it is desired to optimize considering that these routes are not disassembled but integrating new nodes in the same vehicles or in others. This optimization, called incremental routing, allows to optimize considering that there are routes that must remain fixed.

The incremental routing optimization have two sections:

• Partial Tour: Object indicating that the vehicle has previously created partial routes. It contains an ident that is the same vehicle ident. If you don't want the vehicle to have partial routes then this object should be null.
• Partial Routes: Array of partial route object. Each partial route object is a pre-created route and contains a list of node idents.

In order to use incremental routing optimization, you must use the same route optimization endpoint that is used for regular optimizations, but adding this sections and some optional parameters in the vehicles object for each vehicle. Only the vehicles that have the additional objects and parameters are considered to have pre-created routes. It is important to consider that both nodes belonging to partial routes and new nodes must be within the deliveries list of the Nodes Object.

These are the new parameters you can add in the partial route object:

Attributes	Mandatory	Type	Description
nodes	Mandatory	String array	Ident of the nodes that are part of the route that you want to keep in the vehicle.
fixed_nodes_number	Mandatory	Integer	First n nodes that remain fixed in the vehicle and in the position in this previously created route. If the value is equal to 0, all the nodes can change their position but not the vehicle. If the value is equal to the size of the list of nodes, this partial route remains as it is, no node moves.

Additionally, you must turn on this additional parameter that allows you to use this feature:

Attributes	Mandatory	Type	Description
incremental_routing	Optional	Boolean	Default: False. If true, the vehicles considering the previouly created routes which are defined with the previous objetcs and parameters.

Long Routes

Example of Vehicles and Nodes Objects with long routes optimization, where a night route starts at 10:00 p.m. and ends at 7:00 a.m. the following day (equivalent to 31:00 hrs).

{
  "vehicles": [
    {
      "ident": "Vehicle 1",
      "location_start": {
        "ident": "warehouse A",
        "lat": -12.101389,
        "lon": -77.004534
      },
      "capacity": 3500,
      "shift_start": "22:00",
      "shift_end": "31:00"
    }
  ],
  "nodes": [
    {
      "ident": "Jirón Vesalio 252, San Borja",
      "lat": -12.105329,
      "lon": -77.005524,
      "arrayOfTimeWindows": [
        [
          "25:00",
          "28:00"
        ]
      ],
      "load": 77,
      "duration": 10
    },
    {
      "ident": "Jirsón Tasso 423, San Borja",
      "lat": -12.098615,
      "lon": -77.007240,
      "arrayOfTimeWindows": [
        [
          "26:00",
          "30:00"
        ]
      ],
      "load": 77,
      "duration": 10
    }
  ],
  "longRoutes": true
}

Our algorithm extends the creation of routes to perform overnight routing operations, i.e., beyond the 24 hours of a day, called Long Routes Optimization.

To use Long Routes Optimization, you must use the same route optimization endpoint that is used for regular optimizations, but add some optional parameters on all node objects. In addition, you must activate an additional parameter that allows you to use this feature.

It is important to consider that this feature is focused on performing night routing optimizations, but it is possible to make routes of more than one day. However, this feature only supports horizons of no more than 7 days, no more than 10 vehicles and/or 40 nodes per vehicle.

These are the new parameters you can add:

Attributes	Mandatory	Type	Description
arrayOfTimeWindows	Optional	Object	Array of time windows (array of two String in format "HH:mm") to attend the visit. Times can be set for more than 24 hours. This attribute only works if longRoutes is True.
longRoutes	Optional	Boolean	Default: False. If true, it allows the vehicle to have a shift_end greater than 24 hours. In the visits the time windows must be sent.

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"
                }
            ]
        }
    ]
}

Optimization: Metadata

The Optimization Metadata pretends give to the client information not available in the optimization endpoint, such as the vehicle's route planned distances provided by the Optimization Endpoint.

Distance

The distances endpoint offers the estimated kilometers for a previous optimized routes.

An Authorization Header containing a valid Token is required.

Optimization Metadata Distances Endpoint

https://optimizator.simpliroute.com/v1/optimization/metadata/distance

Request

It respects the structure of the Optimization Response, so it should be easier to build after obtaining an optimization.

Root object:

Attributes	Mandatory	Data Type	Description
country	Yes	String	ISO code referring to the country where the delivery locations are located.
vehicles	Yes	Object	List of vehicles incurred in the Optimization

Vehicle object:

Attributes	Mandatory	Data Type	Description
ident	No	String	Vehicle's identification string
tours	Yes	Object	List of tours assigned to the current vehicle

Tour object:

Attributes	Mandatory	Data Type	Description
nodes	Yes	Object	List of nodes that forms the current tour graph.

Node object:

Attributes	Mandatory	Data Type	Description
lat	Yes	Float	Coordinate representing the latitude of the visit or depot
lon	Yes	Float	Coordinate representing the longitude of the visit or depot

Example of Request

{
    "country": "CL",
    "vehicles": [
        {
            "ident": "123",
            "tours": [
                {
                    "nodes": [
                        {
                            "lat": -41.319286,
                            "lon": -72.995719
                        },
                        {
                            "lat": -41.319081,
                            "lon": -72.989037
                        }
                    ]
                },
                {
                    "nodes": [
                        {
                            "lat": -41.317910,
                            "lon": -73.006348
                        },
                        {
                            "lat": -41.317449, 
                            "lon": -72.981885
                        }
                    ]
                }
            ]
        },
        {
            "ident": "456",
            "tours": [
                {
                    "nodes": [
                        {
                            "lat": -42.319286,
                            "lon": -73.995719
                        },
                        {
                            "lat": -42.319081,
                            "lon": -73.989037
                        }
                    ]
                },
                {
                    "nodes": [
                        {
                            "lat": -42.317910,
                            "lon": -73.006348
                        },
                        {
                            "lat": -42.317449, 
                            "lon": -73.981885
                        }
                    ]
                }
            ]
        }
    ]
}

Response

200

It will return 200 when the request is successful. It will follow the same object structure than the request.

200 response example

{
    "vehicles": [
        {
            "ident": "123",
            "tours": [
                {
                    "distance": 899.5,
                    "metric": "meters"
                },
                {
                    "distance": 2200.6,
                    "metric": "meters"
                }
            ]
        },
        {
            "ident": "456",
            "tours": [
                {
                    "distance": 899.5,
                    "metric": "meters"
                },
                {
                    "distance": 2200.6,
                    "metric": "meters"
                }
            ]
        }
    ]
}

400 response example

{
    "statusCode": 400,
    "message": "Country value is required"
}

5XX reponse example

{
    "errors": [
        {
            "code": "E5000",
            "message": "Internal server error",
            "metadata": {
                "code": "E5000"
            }
        }
    ]
}

Validate Incompatibilities

The validation process involves iterating through each visit and checking against each vehicle for any type of incompatibility based on required skills, optional skills, loads, time windows, or zones constraints.

This process is only supported for VRP-type problems and is carried out in the optimizer at the beginning of the process, just before the problem is processed. Visits that are found to be incompatible will be filtered out and will not be considered in the optimization process.

Since a visit can have different incompatibilities for each vehicle, it's challenging to specify a single cause. In such cases, a summary description will be provided, listing the categories that are incompatible with the visit.

Example

Here's an example of a problem response that contains 1 visit and 3 vehicles, where neither vehicle meets the visit requirements:

JSON response:

{
  "filteredClientsNodes": [
    {
      "ident": "Visit",
      "cause": {
        "description": "No vehicles matching: required skills, optional skills, time windows, zone, load",
        "codes": [
          "W02002",
          "W02102",
          "W03002",
          "W04002",
          "W01001"
        ],
        "details": [
          {
            "code": "W02002",
            "category": "required skills",
            "description": "None Vehicles has the required skills for this visit.",
            "count": 3
          },
          {
            "code": "W02102",
            "category": "optional skills",
            "description": "None Vehicles has the optional skill for this visit.",
            "count": 3
          },
          {
            "code": "W03002",
            "category": "time windows",
            "description": "The visit's time window falls out outside the working hours of all vehicles.",
            "count": 3
          },
          {
            "code": "W04002",
            "category": "zone",
            "description": "None vehicle has been assigned to the visit's zone",
            "count": 3
          },
          {
            "code": "W01001",
            "category": "load",
            "description": "Some vehicles has not the required capacity for this visit.",
            "count": 2
          }
        ]
      }
    }
  ]
}

While the description informs us that there are incompatibilities in the 5 categories (load, required skills, optional skills, time windows, zone), in the "details" attribute, we can observe a "counter" attribute that indicates the number of vehicles that are not compatible in each category. The causes are ordered in descending order based on the number of incompatible vehicles.

List of Codes

Below is the code description and the list of supported incompatibility causes.

Structure

<Initial Letter><Problem Category><Specific Number>

Initial Letter:

• W: Indicates an Alert or warning related to a poorly created visit.

Primary Incompatibility Codes

• W00001: Undefined.
• W01002: No vehicles have the required capacity for this visit.
• W02002: No vehicles have the required skills for this visit.
• W02102: No vehicles have the optional skill for this visit.
• W03002: The visit's time window falls outside the working hours of all vehicles.
• W04002: No vehicle has been assigned to the visit's zone.

Secondary Incompatibility Codes

• W01001: Some vehicles do not have the required capacity for this visit.
• W02001: Some vehicles do not have the required skills for this visit.
• W02101: Some vehicles do not have the optional skill for this visit.
• W03001: The visit's time window falls outside the working hours of some vehicles.
• W04001: Some vehicle has not been assigned to the visit's zone.

Mobile

Because the mobile application is one important part in the business model, here we present a detailed documentation of the different tasks that can be performed when using the endpoints that the mobile uses.

The mobile endpoints do the following tasks:

• Checkout.
• Store images.
• Save the values of the extrafields.
• And much more

In the next two sections, we'll dive deeper into our API, what objects it contains, and plenty of practical examples to get you started developing your application using our API. If you have questions, you can email us at [email protected]

Drivers Mobile API is a service that allows you to use our features from your website, software or mobile application. The API gives you access to all supported features of our service. The web service uses REST-style operations on HTTP requests with URL parameters encoded in the request and its response is encoded in JSON. It is designed to be easy to use and you can implement it in any computer language model that allows you to generate web requests. To use the Drivers Mobile API, you must have an account, sign in, and get your API Token.

Login

The endpoint allows the user to obtain a token to perform the functions of the application.

HTTP Method: POST 

URL: https://api-mobile.simpliroute.com/v1/auth/login/

Host : https://api-mobile.simpliroute.com/

Path: /v1/auth/login/

> Request Headers

| Parameter name  |Description  |    |                                                                                                                           |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| accept   |application/json, text/plain, */* |
| Content-Type| application/json |
| mobile-version | ‘X.X.X clientname’ |


>> “mobile-version” value: This value should be the version of the application and the name of the client

> Request Parameters

 Parameter name  |Description  |    |                                                                                                                           |
| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| password |User 's password.
|username | Username

>Example 

``` json
{
 "password":"xxxxxxxx",
 "username":"testuser"
}

JSON Response:

{"auth_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

JSON “auth_token” value: This returns the token that will be used for subsequent requests.

User & Account

User and account information

This endpoint brings back information about account settings, extrafields, and user and account information.

HTTP Method: GET

URL: https://api-mobile.simpliroute.com/v1/accounts/me-mobile/

Host : https://api-mobile.simpliroute.com/

Path: /v1/accounts/me-mobile/ ```

Request Headers

Parameter name	Description
accept	application/json, text/plain, /
Content-Type	application/json
mobile-version	‘X.X.X clientname’
authorization	‘Token xxxxxxxxxxxxxxxxxxxxxxx ‘

** “mobile-version” value: This value should be the version of the application and the name of the client.

“authorization” value: This value should be the token of the user with the prefix Token.

Example response

{
  "observations": [
    {
      "created": "2021-04-30T13:12:19.667352Z",
      "modified": "2022-03-04T12:14:35.634800Z",
      "id": "xxxxx",
      "account_id": xxxxx,
      "type": "completed",
      "label": "Obbservation 1"
    }
  ],
  "tags": [],
  "chat": {
    "enabled": true,
    "properties": [],
    "addon": {
      "id": "XXXXX",
      "title": "Simpli_chat",
      "key": "simpli_chat",
      "description": "simpli_chat",
      "enable": true
    }
  },
  "extrafields": [
    {
      "id": "XXXXX",
      "label": "Short text",
      "key": "prueba_int",
      "order": 1,
      "enable": true,
      "type": "STX",
      "checkout_type": "S&F",
      "options": [],
      "is_alert": false,
      "is_read": false,
      "is_write": true,
      "is_mandatory": false,
      "visit_types": []
    }
  ],
  "user": {
    "id": xxxxx,
    "username": "username",
    "name": "name",
    "phone": "",
    "email": "",
    "is_owner": false,
    "is_admin": false,
    "is_driver": true,
    "is_codriver": false,
    "is_router_jr": false,
    "is_monitor": false,
    "is_coordinator": false,
    "is_router": false,
    "is_staff": false,
    "old_id": null,
    "created": "2022-03-04T12:33:08.144102Z",
    "modified": "2022-05-04T05:20:01.987599Z",
    "last_login": "2022-05-04T05:20:01.987429Z",
    "blocked": false,
    "account": {...},
    "has_suscription_id": null,
    "organization": null
  },
  "visit_types": []
}

JSON “observations” value: Is an array that contains the value of the observations according to the type of checkout(completed or failed).

JSON “tags” value: Is an array that contains the value of the tags.

JSON “chat” value: Contains information if the user has chat activated.

JSON “user” value: It is an object that contains information about the user.

JSON “account” value: It is an object that contains information about the account.

Routes & Visits

Routes

It is an array that brings the information of user routes.

HTTP Method: GET 

URL: https://api-mobile.simpliroute.com/v1/mobile/routes/

Host : https://api-mobile.simpliroute.com/

Path: /v1/mobile/routes/

> Request response 
```json
[
  {
    "id": xxxxxx,
    "order": 1,
    "status": "pending",
    "tracking_id": "SR44991134454782",
    "title": "Visit new",
    "on_its_way": null,
    "route": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "driver": 213079,
    "vehicle": 211956,
    "address": "Av. Capitán Antonio Millán 1013, Rancagua, O'Higgins, Chile",
    "latitude": -34.17342,
    "longitude": -70.750285,
    "window_start": "00:00:00",
    "window_end": "23:59:00",
    "window_start_2": "23:59:00",
    "window_end_2": "23:59:00",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "skills_required": [],
    "skills_optional": [],
    "planned_date": "2022-05-04",
    "route_estimated_time_start": "09:00:00",
    "estimated_time_arrival": "10:13:00",
    "estimated_time_departure": "10:23:00",
    "checkout_time": null,
    "checkout_latitude": null,
    "checkout_longitude": null,
    "checkout_comment": "",
    "checkout_observation": null,
    "checkin_time": null,
    "signature": null,
    "created": "2022-05-04T05:50:49.911210Z",
    "modified": "2022-05-04T05:50:49.911210Z",
    "service_time": "600.0",
    "eta_predicted": "2022-05-04T10:13:00",
    "eta_current": "2022-05-04T10:13:00",
    "tags": [],
    "current_eta": null,
    "visit_type": null,
    "pictures": [],
    "extra_field_values": {}
  },
]

JSON “id” value: It is the identifier of the route.

Visits

It is an array that brings the list of visits.

HTTP Method: GET 

URL: https://api-mobile.simpliroute.com/v1/mobile/{userId}/my-visits

Host : https://api-mobile.simpliroute.com/

Path: /v1/mobile/{userId}/my-visits ```

Request response

[
  {
    "id": xxxxxxxx,
    "order": 1,
    "status": "pending",
    "tracking_id": "SR44991134454782",
    "title": "Visit New",
    "on_its_way": null,
    "route": "xxxxx-xxxxxx-xxxxxx-xxxxxxx",
    "driver": xxxxxx,
    "vehicle": xxxxxx,
    "address": "Av. Capitán Antonio Millán 1013, Rancagua, O'Higgins, Chile",
    "latitude": -34.17342,
    "longitude": -70.750285,
    "window_start": "00:00:00",
    "window_end": "23:59:00",
    "window_start_2": "23:59:00",
    "window_end_2": "23:59:00",
    "contact_name": "",
    "contact_phone": "",
    "reference": "",
    "notes": "",
    "skills_required": [],
    "skills_optional": [],
    "planned_date": "2022-05-04",
    "route_estimated_time_start": "09:00:00",
    "estimated_time_arrival": "10:13:00",
    "estimated_time_departure": "10:23:00",
    "checkout_time": null,
    "checkout_latitude": null,
    "checkout_longitude": null,
    "checkout_comment": "",
    "checkout_observation": null,
    "checkin_time": null,
    "signature": null,
    "created": "2022-05-04T05:50:49.911210Z",
    "modified": "2022-05-04T05:50:49.911210Z",
    "service_time": "600.0",
    "eta_predicted": "2022-05-04T10:13:00",
    "eta_current": "2022-05-04T10:13:00",
    "tags": [],
    "current_eta": null,
    "visit_type": null,
    "pictures": [],
    "extra_field_values": {}
  },
]

JSON “id” value: It is the identifier of the visit.

JSON “route” value: It is the identifier where the visit belongs.

GPS Integration

Simpliroute is able to integrate with your GPS in order to obtain important data

Please contact our Profesional services team to obtain technical details on how to set up this integracion at [email protected]

Frequency for sending data

It is recommended to send a maximum of 1 data per vehicle every 20 seconds. for fleets more than 20 vehicles, 1 data per minute/vehicle, optimal frequency for a layout correct of the routes on the map.

Loss of signal and sending of stored local data

In the event that one or more vehicles circulate in areas outside the satellite range or before any factor that generates a loss of signal in the installed devices, recommends the use of “queues” (or “queues”) for data that could not be sent because of the above reason, and thus be able to send them later, when the signal is reset. When the latter occurs, the system could send data accumulated in the queue, and send them with a maximum time of 10 seconds between each one, until sending all the saved objects. Important: It should be considered that the range of 10 seconds applies only to data stored locally as a result of signal loss. The range for vehicles that are within satellite coverage maintain the recommended at the beginning of this document. Additionally, the data must be sent independently, an arrangement with all objects can cause errors in the communication of the call.

Example Input

{
"latitude":-33.4311548,
"longitude":-70.5701852 ,
"timestamp":"2019-02-20 10:35:00-00”,
"vehicleId”: "JKCT-81",
"providerName”: "LOCALIZAGPS_AGROSUPER”,
}

Integration of GPS and variable data with SimpliRoute

For the integration of GPS data and additional variables with SimpliRoute (such as temperature or humidity), the following information must be sent, by POST method, to the endpoint

Please contact our Profesional services team to obtain technical details on how to set up this integracion at [email protected]

Payload details

Attributes	Description
latitude	Decimal number up to 6 decimal digits.
longitude	Decimal number up to 6 decimal digits.
timestamp	Date and time in UTC with format YYYY-MM-DD HH:II:SS-00 Example: 2019-02-20 10:35:00-00
vehicleId	Vehicle ID in SimpliRoute system.
temperature	Temperature data, see “temperature” object. (backwards compatible but deprecated, it is recommended to send the temperature information in the alert object)
alert	Alert data, see “alert” object
providerName	Name of the vehicle GPS information provider.

Temperature object

Attributes	Description
value	Decimal number with the temperature in degrees Celsius.
alert_type	Alert type, “min” when the temperature is below the limit set or “max” when greater.
alert_message	Message to be sent to the supervisor in charge of the trucks and the transport of refrigerated cargo.

Alert Object

Attributes	Description
name	Alert type identifier.
type	alert type
value	Alert Value
message	Message to be sent to the supervisor in charge of the trucks.

Alerts

It is possible to send additional variables through an array of objects that maintain the following structure:

Attributes	Description
name	Alert type identifier.
type	alert type
value	Alert Value
message	Message to be sent to the supervisor in charge of the trucks.

Available alerts

Names
temperature
geofence
speed
humidity
door
estado
brake
temperature_2
temperature_3
jamming
tiredness
fuel_cap
fuel_variation
driver_door_open
speeding
loss_of_load
no_smoking o smoking
Demurrage

Input example

[
    {
"latitude": -33.4311548,
"longitude": -70.5701852,
"timestamp": "2017-10-19 09:12:02-00",
"vehicleId": "<<vehicle_id>>",
"temperature": {
"value": 2.4,
"alert_type": null,
"alert_message": null
},
"alert": {
"name": “door”,
"type": “open”,
"value": true,
“message”: “open door alert”
},
“alerts”: [
{
"name": “general”,
"type": “ºC”,
"value" 4,
“message”: “temperature is lower than 5 degress”
},
...
],
"providerName": "<<provider>>"
}

Response example

{
"status": "Tracked",
"id": "2408269119724499",
"daily_status": "Updated"
4
}

API response when exist one or more invalid alerts ``` json

{ "status": "Tracked", "id": "2408269119724499", "daily_status": "Updated", "invalid_alerts": [] "invalid_alert": []

} ```

Frequency for sending data

It is recommended to send a maximum of 1 data per vehicle every 20 seconds. for fleets more than 20 vehicles, 1 data per minute/vehicle, optimal frequency for a layout correct of the routes on the map.

Loss of signal and sending of stored local data

In the event that one or more vehicles circulate in areas outside the satellite range or before any factor that generates a loss of signal in the installed devices, recommends the use of “queues” (or “queues”) for data that could not be sent because of the above reason, and thus be able to send them later, when the signal is reset. When the latter occurs, the system could send data accumulated in the queue, and send them with a maximum time of 10 seconds between each one, until sending all the saved objects. Important: It should be considered that the range of 10 seconds applies only to data stored locally as a result of signal loss. The range for vehicles that are within satellite coverage maintain the recommended at the beginning of this document. Additionally, the data must be sent independently, an arrangement with all objects can cause errors in the communication of the call.

ON DEMAND

Authentication

All calls to our API must have an authentication token.

Include your token as a header with the name Authorization. As in the following example:

Example call

curl https://us-central1-on-demand-prod-327320.cloudfunctions.net --request GET \
  --url /auth/config \
  --header 'Authorization: token' \
  --header 'Content-Type: application/json'

Generate Token

Once you have obtained your token, remember to keep it in a safe place. Since it is the key to our system, and will be needed for all calls to our API.

Please note that our tokens are only valid for one hour, and then must be generated again.

Parameters

Attribute	Type	Description
username	string	User name
password	string	User password

Example JSON response

curl --request POST \
  --url https://us-central1-on-demand-prod-327320.cloudfunctions.net/auth/signin \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "[email protected]",
  "password": "password"
}'

Parameters

Attribute	Type	Description
accessToken	string	Access token of the user
expiratioTime	long	Expiration time (timestamp) of the token, in milliseconds
accountId	string	Identificador de la cuenta del usuario

Example response

{
  "accessToken": "This is the access token",
  "expirationTime": 1654275965694,
  "accountId": "accountId"
}

Orders

An order is a requirement of a client generating the request of a driver, this order can be the delivery of a product or a service. The order has the following statuses:

• Pending: The order is pending to be served by a driver.
• Assigned: The order has been assigned to a driver.
• on its way: The order has been served by a driver and is on its way.
• Completed: The order has been completed successfully.
• Failed: The order has reached its destination, but for some reason it could not be completed.
• Cancelled: The order has been canceled by the client or by the administrator.

Tip

Remember that these endpoints are token protected, so you will need to use the Authorization header for submission. In case you don't have a token visit the documentation of Authentication

Create order

Parameters

Attribute	Type	Descriotion
*title(mandatory)	string	Name for the new order
*address(mandatory)	string	Address of the order, street and number
apartment(Optional)	string	Department number in case of being a building
community	string	Commune or administrative division where the address belongs
location	string	Order Coordinates(Optional)
lat	number	latitude of the order
lon	number	longitude of the order
contact	srtring	contact information of the person who made or will receive the order
location	string	Contact information of the person who placed or will receive the order
*name(mandatory)	string	Contact name
*phone(mandatory)	number	Contact phone number
*email(mandatory)	string	Contact e mail address

Example Json

curl --request POST \
  --url https://us-central1-on-demand-prod-327320.cloudfunctions.net/order \
  --header 'Authorization: token' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Name for the new order",
  "address": "Address of the order, street and number",
  "apartment": "Department number in case of being a building",
  "community": "Commune or administrative division where the address belongs",
  "description": "Description of the order",
  "contact": {
    "name": "contact name",
    "phone": "contact phone number",
    "email": "[email protected]"
  }
}'

Response parameters

Attribute	Data Type	Description
status	string	Request Result Status
message	string	Message with information about the request
data	string	Identifier of the created order

Example response

{
  "status": "Success",
  "message": "Order created successfully",
  "data": "eca4ec6e-a27f-497e-a810-7088fb1f487a"
}

Update an order

Parameters

Attribute	Type	Description
title	string	Name for the new order
address	string	Address of the order, street and numbering
apartment	string	Department number in case of being a building
community	string	Commune or administrative division where the address
contact	{}	Contact information for the person who placed or will receive the order
name	string	contact name
phone	string	contact phone number
email	string	Contact E-Mail
status	string	Order Status. It can be: [pending, assigned, onRoute, completed, failed, canceled]
checkoutLocation	{}	Order checkout position information
lat	float	Latitud de la posición de checkout
lon	float	checkout position longitude
checkoutAt	long	Check out time (timestamp) of the order, in milliseconds
checkoutComment	string	checkout description
images	string[]	checkout images

Example request

curl --request PATCH \
  --curl https://us-central1-on-demand-prod-327320.cloudfunctions.net/order/ecd135cb-c547-4d90-923d-09bd1415ea99 \
  --header 'Authorization: token' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "title",
  "address": "address 11223",
  "apartment": "11122",
  "community": "community",
  "contact": {
    "name": "name",
    "phone": "+511223311",
    "email": "[email protected]"
  },
  "status": "failed",
  "checkoutLocation": {"lat": -33.42, "lon": -70.603333},
  "checkoutAt": 1654282082000,
  "checkoutComment": "comment",
  "images": ["image_url"]
}'

Response Parameters

Attribute	Type	Description
status	string	Request Result Status
message	string	Message with information about the request
data	string	Updated order identifier

Example response

{
  "status": "Success",
  "message": "Order updated successfully",
  "data": "ecd135cb-c547-4d90-923d-09bd1415ea99"
}

Cancelled an Order

By using the follwing endpoint you can cancelled an order

Example request

curl --request DELETE \
  --url https://us-central1-on-demand-prod-327320.cloudfunctions.net/order/2af2c1e7-fd16-4b39-8534-8c222e2d8d43 \
  --header 'Authorization: token' \
  --header 'Content-Type: application/json'

Response parameters

Attribute	Type	Description
status	string	Request Result Status
message	string	Message with information about the request
data	string	Updated order identifier

Example response

{
  "status": "Success",
  "message": "Order canceled successfully",
  "data": "2af2c1e7-fd16-4b39-8534-8c222e2d8d43"
}

Search Historical Orders

Parameter

Attribute	Type	Description
page	int	Page number. Default value is 1
pageSize	int	Number of items per page. Default value is 10
search	string	Text for order search, searched on: order title, driver name, contact name
statuses	string	Status of the orders to search, possible values: [completed, failed, canceled], to filter by several status concatenate with a comma ex: completed,failed
situation	string	Situación de las órdenes a buscar, valores posibles: [onTime, late], para filtrar por varias situaciones concatenar con una coma ex: onTime,late
startDate	long	Fecha de inició (timestamp) para buscar órdenes, en milisegundos
endDate	long	Fecha de término (timestamp) para buscar órdenes, en milisegundos

Example call

curl --request GET \
  --url 'https://us-central1-on-demand-prod-327320.cloudfunctions.net/order/search?page=1&pageSize=10&search=Juan&statuses=completed%2Cfailed&startDate=1651949662000' \
  --header 'Authorization: token' \
  --header 'Content-Type: application/json'

Response parameters

Field	Type	Description
page	int	Page number. Default value is 1
pageSize	int	Number of items per page. Default value is 10
orders	order[]	list of orders
total	int	total orders found
previous	string	URL of the previous page
next	string	Url of next page

JSON Response

{
  "page": 1,
  "pageSize": 10,
  "orders": [
    {
      "arrival": 1654284120000,
      "createdAt": 1654282419433,
      "trackingId": "SR42703348739645",
      "marginRisk": "20",
      "description": "Descripción",
      "contact": {
        "phone": "1654180395348",
        "email": "[email protected]",
        "name": "Orden fallida a tiempo"
      },
      "id": "ecd135cb-c547-4d90-923d-09bd1415ea99",
      "status": "failed",
      "location": {
        "lon": -70.600253,
        "lat": -33.430625
      },
      "driver": {
        "name": "Juan Piloto",
        "vehicleName": "VH1",
        "email": "[email protected]",
        "phone": "+56 9 6655 4475",
        "id": 202655
      },
      "accountId": "56846",
      "visitId": 154758404,
      "apartment": "",
      "serviceLevelAgreement": "180",
      "generalAddress": "Holanda 1300, Providencia",
      "title": "Holanda fallida",
      "address": "Holanda 1300",
      "community": "Providencia",
      "checkoutLocation": {
        "lat": -33.42,
        "lon": -70.603333
      },
      "checkoutAt": 1654282082000,
      "images": [],
      "checkoutComment": "comment",
      "situation": "onTime"
    } ...
  ],
  "total": 6,
  "next": "https://us-central1-on-demand-prod-327320.cloudfunctions.net/order/search?page=2&pageSize=10",
  "previous": null
}

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.