RouteSync
Contents
RouteSync is a feature which aids route compliance and improves in-vehicle consistency from the back office to the mobile workforce devices. Routes can be planned on back office systems and by passing location information via API to CoPilot this route will be sent to CoPilot.
Msg_SendManagedRouteJSON
This API is used to send a RouteSync message in JSON format from the client application to CoPilot.
| Supported Since | Minimum Operating System |
|---|---|
| CoPilot 9.6.0 | Windows 10, Android 7 |
Syntax (Prototyped in alkmsg.h)
long Msg_SendManagedRouteJSON(const char* pJson);
Parameter
pJson: Complete contents of a JSON message describing a CoPilot managed route. See Note 1 for details on this format.
Return Value
-1 = Error parsing JSON Greater than zero = Successful in sending the request to CoPilot.
Related APIs
- Msg_ManagedRouteCallback - Used to set the callback and receive notification about successful processing of the message by CoPilot.
- Msg_SetFlexCallback
- MsgSdkManagedRouteCB
Note: The following is a description of the JSON format expected by the API including optional/required fields.
JSON Format
{
"Compliance": 0,
"OorDistance": 0.2,
"Legs": [
{
"Coords": [
-74730013, //Coords for roads you'd like the route to follow from Stop A -> Stop B
40297252
]
},
{
"Coords": [
-74660179, //Coords for roads you'd like the route to follow from Stop B -> Stop C
40348429,
-74660635,
40349433
]
}
],
"Trip": {
"Name": "Test name",
"Profile": {
"name": "",
"vehicleType": 4,
"routingType": 3,
"tollRoadType": 2,
"maxHeight": 12900,
"maxWidth": 9600,
"totalLength": 48000,
"totalWeight": 3300,
"totalWeightPerAxle": 2300,
"hazmatType": 0,
"displayRestrictions": 2,
"nationalNetwork": false,
"fiftyThreeFootTrailer": false,
"overrideRestrictions": true,
"bordersOpen": true,
"CongestionZonesOpen": 0,
"LowEmissionZonesOpen": 0,
"propane": false,
"ferryClosed": false,
"tollAvoid": false,
"tollClosed": false,
"truckDimensions": 0,
"wrongSideofStreetCost": 1000,
"autoSetStopDirection": 1
},
"Stops": [
{
"Location": {
"Address": {
"StreetAddress": "",
"City": "Lawrence Township",
"State": "NJ",
"Zip": "08648",
"County": "Mercer",
"Country": ""
},
"Coords": {
"Lat": "40.297263",
"Lon": "-74.730034"
}
},
"Waypoint": false,
"Name": "Stop A"
},
{
"Location": {
"Coords": {
"Lat": "40.348727",
"Lon": "-74.659049"
}
},
"Waypoint": false,
"Name": "Stop B"
},
{
"Location": {
"Address": {
"StreetAddress": "",
"City": "New York",
"State": "NY",
"Zip": "10001",
"County": "New York",
"Country": ""
}
},
"Waypoint": false,
"Name": "Stop C"
}
]
}
}
| JSON Parameter | Description | Required |
|---|---|---|
| Compliance | This value will dictate how CoPilot will handle re-routing. That is, how strictly CoPilot should try to return to the original (sent) route in the event that the driver is out-of-route. There are three possible values: 0 – Strict Compliance; 1 – Moderate Compliance; 2 – Minimal Compliance. | Yes |
| OorDistance | This value will determine how far away from the planned route the CoPilot-equipped vehicle must be to generate an out-of-route (OOR) alert. The default value is 0.2 miles. | Yes |
| Legs | At least one leg is needed for each managed route. This should be passed as two sets of Coordinates. | Yes |
| Coords | At least 2 coords per leg are required. These are latitude and longitude points between stops on the trip that create the route you want the driver to follow. We recommend at least one latitude and longitude location for every road you want the route to follow, and an additional latitude and longitude on each side of every turning junction. These should be passed as long integers and encoded as millionths of a degree. | Yes |
| Trip | The trip details | Yes |
| Profile | This passes the Vehicle Routing Profile that is used for the managed route. Note: While optional, this parameter is highly recommended. Otherwise, CoPilot will use the current routing profile on the device to generate the route. | No, but recommended |
| name | Profile Name, this should be passed if the Profile group is included. | No |
| vehicleType | 0:Auto, 2:RV, 3:Truck, 6:Motorcycle, 7:Bicycle, 8:Walking. This should be passed if the Profile group is included. | No |
| routingType | 0:Quickest, 1:Shortest, 2:Avoid Major Roads. This should be passed if the Profile group is included. | No |
| tollRoadType | 0:Avoid, 1:Use If Necessary, 2:No Restriction. This should be passed if the Profile group is included. | No |
| maxHeight | Value sent in hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle height you would like to specify, include this parameter. | No |
| maxWidth | Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle width you would like to specify, include this parameter. | No |
| totalLength | Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle length you would like to specify, include this parameter. | No |
| totalWeight | Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight you would like to specify, include this parameter. | No |
| totalWeightPerAxle | Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight per axle group you would like to specify, include this parameter. | No |
| hazmatType | 0:None, 1:General, 2:Explosive, 3:Inhalant, 4:Radioactive, 5:Caustic, 6:Flammable, 7:Harmful to water. If sending a Truck routing profile and you wish to specify any Hazmat category that may be applicable include this attribute | No |
| displayRestrictions | 0:Off, 1:On, 2:Based on profile. Within the truck routing profile that you are sending to CoPilot if you wish to include the setting to show restrictions on the map, include this parameter. | No |
| nationalNetwork | For North American customers, if sending a truck profile and you wish to apply the nationalNetwork routing profile setting this should be set with this parameter. | No |
| fiftyThreeFootTrailer | For North American customers sending a truck profile and wish to set the Fifty Three Foot Trailer setting within the routing profile, this parameter should be used. | No |
| overrideRestrictions | Set to true to to generate routes that waive truck restrictions pertaining to specific sizes and weights, but that continue to avoid truck-prohibited and truck discouraged roads. | No |
| bordersOpen | For North American customers if they wish to set the borders open parameter in the routing profile this should be set | No |
| propane | For North American customers who have a routing profile that needs to have the propane restriction set this parameter can be used | No |
| ferryClosed | To set the ferry routing attribute | No |
| wrongSideofStreetCost Available in CoPilot 10.14 and Later | For School Bus profiles, set to 1000. This value favors approaching a stop on the same side of the road that you are driving on. It helps prevent a situation in which a student has to cross the road to get on the bus. | No |
| autoSetStopDirection Available in CoPilot 10.14 and Later | For School Bus profiles, set to 1. This prevents a vehicle from making a U-turn at a stop. | No |
| CongestionZonesOpen Available in CoPilot 10.14 and Later | Sets a routing preference for Congestion Zones 0: Avoid, 1: Allow, 2: Warn when driving | No |
| LowEmissionZonesOpen Available in CoPilot 10.14 and Later | Sets a routing preference for Low Emission Zones. 0: Avoid, 1: Allow, 2: Warn when driving | No |
| Stops | Must always have one more stop than legs | Yes |
| Location | Details about the stop. | Yes |
| Address | The stop can be passed using the Address or the Coords. One of these options must be provided as part of the Stops Location section. | Yes, if no Coords supplied |
| StreetAddress | First line of the address of the Stop | No |
| City | City of the Stop | No |
| State | State of the stop | No |
| Zip | Zip or Postal Code for the stop | No |
| County | County of the stop | No |
| Country | Country code for the stop | No |
| Coords | The stop can be passed using the Coords or Address. If Address has not been provided this is mandatory. | Yes, if no Address supplied |
| Lat | Mandatory if using Coords for geocoding the stop | Yes, if using Coords |
| Lon | Mandatory if using Coords for geocoding the stop | Yes, if using Coords |
| Waypoint | Default is false. If you would like to set the stop as a Waypoint rather than a stop this should be set to True. | No |
| Name | Stop name – default is blank | No |
Msg_GetPointsOffRouteSyncRoute
Provides details of the lat/long coordinates that are included within the RouteSync input file but are not on the route generated by CoPilot. These details are provided through the subscription of MSG_ID_RouteSyncPointsOff.
| Supported Since | Minimum Operating System |
|---|---|
| CoPilot 9.2.0 | Windows 10, Android 7 |
Syntax (Prototyped in alkmsg.h)
long MsgGetPointsOffRouteSyncRoute(void _pBytes, unsigned long bytesLen, char strPayload, long lPayload);
Parameter
| Parameter | Description |
|---|---|
| pBytes | The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions(). |
| bytesLen | Buffer length |
| strPayload | String payload of the list of coordinated that are outside of the generated route |
| lPayload | Length of the strPayload |
Return Value
- Less than 0 = Failed
- Greater than 0 = Successful