Before starting we need to bring you some definitions of Routal model that are essential:
- Plan is a set of tasks (deliveries, pickups, repairs, ...), formerly called Services, that must be done within a time interval. These tasks must be assigned to someone (courier, driver, ...) formerly called Route.
- Route is a set of services that must be performed by the same entity (courier, driver, ...) within a certain order.
- Service is a task that must be performed. It's defined by its location and may contain some constraints such as duration, time windows, ...
1. AUTHENTICATE
The first thing needed is the user's private_key. This key is needed to authenticate every single request performed against the Highway API.
You can find the private key under the user settings. Private keys will always start with the prefix priv_ for users clarity.
2. CREATE THE PLAN
The plan is a container for routes and services. It is usually defined by the start date. It is necessary to have a plan to start optimizing and to be able to track the progress of operations.
curl "https://highwayservices.smartmonkey.io/api/v1/plan?\
private_key=<YOUR_PRIVATE_KEY>\
&project_id=<YOUR_PROJECT_ID>"\
--header "Content-Type: application/json" \
--data '{"label": "Example Highway Plan" }'
With the code below you will be able to create a new empty plan by replacing <YOUR_PRIVATE_KEY> and <YOUR_PROJECT_ID> by your owns.
{
"id":"<PLAN_ID>",
"organization_id":"<YOUR_ORGANIZATION_ID>",
"project_id":"<YOUR_PROJECT_ID>",
"_version":1,
"status":"planning",
"label":"Example Highway Plan",
"optimizer_config":{
"max_wait_time":3600,
"service_duration":300,
"balance_services":true,
"matrix_multiplier":1.25,
"time_limit_seconds":240,
"operation_country":null,
"first_solution_strategy":"AUTOMATIC"
},
"created_by":"<YOUR_USER_ID>",
"created_at":"2020-12-15T12:19:50.914Z",
"updated_at":"2020-12-15T12:19:50.914Z",
"services":[
],
"routes":[
]
}The call will provide you with the created plan as a result. You can check all the parameters in our API spec.
3. CREATE A PLAN WITH ROUTES AND SERVICES
A plan by itself is not really useful. In order to take advantages of all Routal functionalities, the plan should contain routes and services. It exists the possibility of creating them in different API calls or in just once. For simplicity, the following example explains how to create a plan with nested routes and services in the same API call.
We will define one route with the same start and end position, an example plate and a time window from 10:00h to 11:00h noted as 36000 and 39600 respectively because they are defined as the number of seconds since 00:00 (60*60*10 and 60*60*11). Review all route creation parameters in the API spec.
{
"label": "My First Route",
"start_location":{
"label":"Departure Street 45",
"lat":40.45,
"lng":-3.68
},
"end_location":{
"label":"Arrival Street 54",
"lat":40.45,
"lng":-3.68
},
"plate":"1221HHX",
"timewindow":[
36000,
39600
]
}
Now we will define two services with a random location and a time window. You can review all service creation parameters in the API spec.
{
"label":"First service",
"location":{
"label":"Example First Service Location",
"lat":40.47,
"lng":-3.67
},
"timewindows":[
[
36000,
37000
]
]
}{
"label":"Second service",
"location":{
"label":"Example Second Service Location",
"lat":40.45,
"lng":-3.69
},
"timewindows":[
[
37000,
39000
]
]
}
Now we will create a list called services and a list called routes in the plan creation object. You can copy the merged object from the following snippet:
{
"label":"Example Highway Plan",
"services":[
{
"label":"First service",
"location":{
"label":"Example First Service Location",
"lat":40.47,
"lng":-3.67
},
"timewindows":[
[
36000,
37000
]
]
},
{
"label":"Second service",
"location":{
"label":"Example Second Service Location",
"lat":40.45,
"lng":-3.69
},
"timewindows":[
[
37000,
39000
]
]
}
],
"routes":[
{
"label":"My First Route",
"start_location":{
"label":"Departure Street 45",
"lat":40.45,
"lng":-3.68
},
"end_location":{
"label":"Arrival Street 54",
"lat":40.45,
"lng":-3.68
},
"plate":"1221HHX",
"timewindow":[
36000,
39600
]
}
]
}
Once we have the body we can build the cURL request in order to create our custom plan:
curl --location --request POST 'https://highwayservices.smartmonkey.io/api/v1/plan?private_key=<YOUR_PRIVATE_KEY>&project_id=<YOUR_PROJECT_ID>' \
--header 'Content-Type: application/json' \
--data-raw '{
"label":"Example Highway Plan",
"services":[
{
"label":"First service",
"location":{ "label":"Example First Service Location", "lat":40.47, "lng":-3.67 },
"timewindows":[[ 36000, 37000 ]]
}, {
"label":"Second service",
"location":{ "label":"Example Second Service Location", "lat":40.45, "lng":-3.69 },
"timewindows":[[ 37000, 39000 ]]
}
],
"routes":[{
"label":"My First Route",
"start_location":{ "label":"Departure Street 45", "lat":40.45, "lng":-3.68 },
"end_location":{ "label":"Arrival Street 54", "lat":40.45, "lng":-3.68 },
"plate":"1221HHX",
"timewindow":[ 36000, 39600 ]
}