Add route template
This endpoint adds a route template to the company.
Route templates can be used to create specific routes that are used frequently without the need to define them each time they are necessary.
See the endpoint New Assign Template or Group to find out how to use the route templates.
Specifying the path
The path needs to be specifyed in each step defined. There are two ways to do this:
Defining the polyline A polyline may be obtained from the maps service provider.
If you decide to specify the polylines, you need to specify them for every step in the route - not just a for a few steps ; otherwise, Frotcom will use thestartsandsrrivepoints, ignoring any polyline that you may have specified.
If you choose not to define the polyline for every step, then you need to define thestartsandarrivepoints ; otherwise, the operation will fail with a "Bad Request" HTTP response.Specifying the
startsandarrivepoints
If you don't define the polyline, then you need to define these points. You may define these endpoint in two ways:
Use the ID of a place registered in the company
If you specify the ID of a place, then it's coordinates will be used as the coordinates of the point being defined.Use the GPS coordinates of the point. If you specify the GPS coordinates, these will prevail over the ID of the place.
If you specify the GPS coordinates, then these will be used as the coordinates of the point being defined.
If you specify both, the place ID and and the GPS coordinates, then then the GPS coordinates will be used and the place ID will be ignored.
Parameters
route
route is the json object that must be specified in the payload of the POST request and it contains all the necessary data to create the route template.
Depending on your needs, you may ommit some of the fields.
Please check the table with the fields details below.
{
"code": "string",
"colour": 0,
"name": "string",
"stepId": 0,
"routeId": 0,
"assignId": 0,
"assignNumber": 0,
"steps": [
{
"id": 0,
"createCorridor": true,
"corridorWidth": 0,
"polyline": "string",
"assignId": 0,
"assignNumber": 0,
"routeGroupId": 0,
"starts": {
"placeId": 0,
"address": "string",
"planned": "2023-05-18T10:01:59.448Z",
"coordinates": {
"latitude": 0,
"longitude": 0
},
"clientId": 0
},
"arrive": {
"placeId": 0,
"address": "string",
"planned": "2023-05-18T10:01:59.448Z",
"coordinates": {
"latitude": 0,
"longitude": 0
},
"clientId": 0
},
"times": {
"mileage": 0,
"duration": 0,
"breaks": 0,
"stopOver": 0
},
"notifications": {
"mode": "none",
"delta": 0,
"subject": "string",
"message": "string",
"useCrmContacts": true,
"useAccountContacts": true,
"warnings": {
"emails": "string",
"phones": "string"
},
"others": {
"emails": "string",
"phones": "string"
}
},
"alarms": {
"contacts": {
"emails": "string",
"phones": "string"
},
"terminal": "notSendAlarm",
"sound": 0,
"playSound": true,
"confirmation": true,
"form": "string",
"formInterval": 0,
"warningATDBefore": true,
"warningATDBeforeDuration": 0,
"warningATDAfter": true,
"warningATDAfterDuration": 0,
"warningETABefore": true,
"warningETABeforeDuration": 0,
"warningETAAfter": true,
"warningETAAfterDuration": 0,
"warningETATolerance": true,
"warningETAAfterImidiately": true,
"warningATDAfterImidiately": true
},
"messages": {
"message": "string",
"scheduleArriveTime": true,
"destinationPoint": true,
"taskId": 0,
"jobId": 0
},
"dragPoints": [
{
"latitude": 0,
"longitude": 0
}
],
"formSinceLastTime": 0,
"altDirIndex": 0
}
],
"options": {
"avoidHighways": true,
"reorderingWaypointsAllowed": true,
"avoidTolls": true,
"avoidFerries": true,
"costOptimized": true,
"vehicleClassId": 0,
"vehicleProfileId": 0,
"useDrivingTimeRestrictionsRules": true,
"useExistingVehicleDrivingTime": 0,
"vehicleDrivingTimeId": 0,
"useWorkingPeriod": true
},
"auxiliaryId": "string",
"field1": "string",
"field2": "string",
"field3": "string"
}
| Field | Description |
| code | The ID that identifies the route template.
|
| colour |
|
| name | A name that identifies the route template. This name must be unique.
|
| auxiliaryId |
|
| steps |
Set of steps that define the route.
|
| steps[i].createCorridor |
Specifies if a corridor should be created for the step. Corridores allow to check if the vehicle leaves the expected path.
|
| steps[i].corridorWidth |
The width of the corridor in Km.
|
| steps[i].starts |
Definition of the coordinates of the starting location of the step
|
| steps[i].starts.placeId |
The ID of a company's place that defines the starting place
|
| steps[i].starts.planned |
|
| steps[i].starts.coordinates |
|
| steps[i].starts.latitude |
The latitude of the starting location of the step
|
| steps[i].starts.longitude |
The longitude of the starting location of the step
|
| steps[i].arrive |
Definition of the coordinates of the starting location of the step
|
| steps[i].arrive.placeId |
The ID of a company's place that defines the place of arrival
|
| steps[i].arrive.planned |
|
| steps[i].arrive.coordinates |
|
| steps[i].arrive.latitude |
The latitude of the arrival location of the step
|
| steps[i].arrive.longitude |
The longitude of the arrival location of the step
|
| steps[i].times |
|
| steps[i].notifications |
|
| steps[i].alarms |
|
| steps[i].messages |
|
| steps[i].dragPoints |
|
| steps[i].formSinceLastTime |
|
| steps[i].altDirIndex |
|
| options |
This is a set of options which are used when Frotcom requests a path from the maps service.
|
| options.avoidHighways |
Instructs the maps service to find a path that avoids highways.
|
| options.reorderingWaypointsAllowed |
Allows the reordering of the specified waypoints in order to optimize the path.
|
| options.avoidTolls |
Instructs the maps service to find a path which avoids tolls.
|
| options.avoidFerries |
Instructs the maps service to find a path which avoids traveling by ferry boats.
|
| options.costOptimized |
Tries to optimize the costs.
|
| options.vehicleClassId |
The ID of the class of the vehicle. The list of vehicle classes can be obtained using the endpoint Get vehicle profiles (HERE maps). |
| options.vehicleProfileId |
The ID of the profile of the vehicle. The profile of the vehicle may be important the account is configured for using the Advanced routing with Here maps. The list of vehicle profiles can be obtained using the endpoint Gets vehicle classes. |
| options.useDrivingTimeRestrictionsRules |
Determines the path taking into consideration the driving times restrictions. This option influences the ETD (Estimated Time of Departure) and ETA (Estimated Time of Arrival) timestamps. |
| options.useExistingVehicleDrivingTime |
|
| options.vehicleDrivingTimeId |
This field indicates the ID of the vehicle which driving times should be considered when calculating the route times of arrival and departure. If null, the driving times aren't applied.
|
| options.useWorkingPeriod |
Determines the path taking into consideration the working periods. This option influences the ETD (Estimated Time of Departure) and ETA (Estimated Time of Arrival) timestamps. |
| field1 |
Field of free aditional text
|
| field2 |
Field of free aditional text
|
| field3 |
Field of free aditional text
|
Response Body
{
"id": 0
}
| Field | Description |
| id | A code that identifies the route template that was created.
|
Response HTTP Codes
201 - Created
- When the route template is created successfully
400 - Bad request
- If the parameter routes is not provided
- If the parameter routes is invalid or not well formated
- If the array of steps is not provided or is empty
- If a name is not specified
- If the specified name is longer than it's maximum allowed size (see the name in the parameters reference above)
- If code is specified, but is longer than it's maximum allowed size
- For any step, if a createCorridor is set to true, but corridorWidth value is smaller than 0.01 Km
- For any step, when starts is specified and a placeId is also specified, but the corresponding place can not be found in the company's account
- For any step, when starts is specified and a placeId is not, and the coordinates are also not specified
- For any step, when arrive is specified and a placeId is also specified, but the corresponding place can not be found in the company's account
- For any step, when arrive is specified and a placeId is not, and the coordinates are also not specified
- For any step, when notifications is specified and mode is set to distance, but delta is not specifyed or it's value is less than zero
- For any step, if any of the specified emails in notilications.warnings.emails or notilications.others.emails is not valid;
- For any step, if any of the specified emails in notilications.warnings.phones or notilications.others.phones is not valid;
- For any step, if any of the specified emails in alarms.contacts.emails is not vallid
- For any step, if any of the specified emails in alarms.contacts.phones is not vallid
- For any step, if the polyline is not defined and at least one of starts and arrival is also not defined
401 - Unauthorized
- Invalid credentials
403 - Forbidden
- The user don't have permission to manage routes
403 - Conflict
- If the field name specified is already in use
- If the field auxiliarId is already in use
404 - Not found
- For any step, if a direction route can not be obtained from the maps service
409 - Conflict
- If the field name specified is already in use
- If the field auxiliarId is already in use
Request Sample
{
"name": "Route name",
"code": "1234",
"steps": [
{
"starts": {
"latitude": 34.91401,
"longitude": 33.63718
},
"arrive": {
"latitude": 35.12586,
"longitude": 33.34906
}
}
],
}