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
12345678900987srwith 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,
"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 | Bolean |
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,
"planned_date": "2016-05-20",
"estimated_time_start": "03:00:00",
"estimated_time_end": "19:33:00",
"status": "assigned",
"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"
}
]
Example response
[
{
"id": "33ddc43b-5ca8-4455-b3af-16a2f1971c1e",
"status": "new",
"vehicle": 2032,
"driver": null,
"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,
"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",
"created": "2016-08-01T20:45:25.672207Z",
"modified": "2016-08-01T20:45:25.674460Z"
}
]
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.
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 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_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
[
{
"vehicle":{
"id":1,
"name":"Test"
},
"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],
"driver":{
"id":23870,
"name":"Conductor 1"
},
"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. | |
| driver {id, name} | id: int - name: string. | Driver information. |
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"
},
"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. |
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. |
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"
}
]
}
]
}
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 |
| 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. |