Samsara Telematics Integration with NextBillion.ai
In the following sections, we'll go over how to integrate Samsara Telematics with the NextBillion.ai Route Optimization API. Each step will be detailed to ensure a successful and efficient integration process, from obtaining API keys and setting up authentication to designing data pipelines and interpreting response data.
Prerequisites
Before integrating Samsara Telematics and NextBillion.ai's Route Optimization API, make sure you have the following prerequisites in place:
Samsara API Token with Read/Write Permissions
Obtain a valid API token with both read and write scopes from your Samsara account. This token will be used to gain secure access to and retrieve data from your Samsara telematics system.
API Key from NextBillion.ai
Check that you have a valid API key from NextBillion.ai. This key will be used to provide secure authentication when interacting with NextBillion.ai's services.
Samsara Asset Tracker
Ensure that the Samsara asset tracker is properly installed and configured on your drivers' vehicles. This device will transmit real-time telematics data that will be integrated with NextBillion.ai’s Route Optimization API.
By ensuring that these prerequisites are met, you will pave the way for a smooth and secure integration, allowing you to leverage the combined power of Samsara's telematics insights and NextBillion.ai's optimization capabilities for improved fleet management.
Connect and Import Data from Samsara
To effectively leverage the capabilities of both Samsara's telematics and NextBillion.ai's Route Optimization API, a seamless data integration process is required. You can unlock the power of advanced route optimization by pulling critical information from your Samsara account and orchestrating a smooth connection to the NextBillion.ai platform. This guide will walk you through the steps of pulling addresses, assets (vehicles), drivers, and addresses from Samsara and integrating them with Nextbillion.ai’s Route Optimization API.
Login to NextBillion.ai Account
Begin by logging into your NextBillion.ai account. This is your central hub for managing and accessing your API keys. API key is required to authenticate the requests made by the user.
Integrating Samsara Telematics with NextBillion.ai
To integrate Samsara Telematics with your NCC dashboard, Contact support. We will help you navigate through the process.
Pull List of Addresses
Initiate a data pull from Samsara to extract a list of addresses where your deliveries or pickups are planned. These addresses are crucial for accurate route optimization.
API Request
1# Fetch addresses from Samsara Telematics Dashboard
2curl --request GET \
3 --url https://api.samsara.com/addresses
4API Response
1"data": [
2 {
3 "id": "68913795",
4 "name": "Tuttle Crossing",
5 "createdAtTime": "2023-07-21T00:29:59.968745Z",
6 "formattedAddress": "Tuttle Crossing, Dublin, Ohio 43016",
7 "geofence": {
8 "circle": {
9 "latitude": 40.0784625,
10 "longitude": -83.1287112,
11 "radiusMeters": 360
12 }
13 },
14 "latitude": 40.0784625,
15 "longitude": -83.1287112
16 },
17 {
18 "id": "69020143",
19 "name": "Dublin Pool",
20 "createdAtTime": "2023-07-21T11:03:00.814447Z",
21 "formattedAddress": "dublin community pool, dublin oh 43017",
22 "geofence": {
23 "circle": {
24 "latitude": 40.1229158,
25 "longitude": -83.1442514,
26 "radiusMeters": 250
27 }
28 },
29 "latitude": 40.1229158,
30 "longitude": -83.1442514
31 },
32 {
33 "id": "70232689",
34 "name": "Brandon Park",
35 "createdAtTime": "2023-07-26T17:54:47.462049Z",
36 "formattedAddress": "Brandon Park Dublin OH 43017",
37 "geofence": {
38 "circle": {
39 "latitude": 40.1259995,
40 "longitude": -83.1306475,
41 "radiusMeters": 162
42 },
43 "settings": {
44 "showAddresses": false
45 }
46 },
47 "latitude": 40.1259995,
48 "longitude": -83.1306475
49 },
50 {
51 "id": "70232810",
52 "name": "Carrigan Ridge",
53 "createdAtTime": "2023-07-26T17:55:39.892546Z",
54 "formattedAddress": "4837 Carrigan Ridge Dr, Dublin, OH 43017, USA",
55 "geofence": {
56 "circle": {
57 "latitude": 40.13228346371899,
58 "longitude": -83.11910591484421,
59 "radiusMeters": 100
60 },
61 "settings": {
62 "showAddresses": false
63 }
64 },
65 "latitude": 40.13228346371899,
66 "longitude": -83.11910591484421
67 },
68 {
69 "id": "70232853",
70 "name": "Ashford",
71 "createdAtTime": "2023-07-26T17:56:01.820412Z",
72 "formattedAddress": "5495 Ashford Rd, Dublin, OH 43017, USA",
73 "geofence": {
74 "circle": {
75 "latitude": 40.130642879687194,
76 "longitude": -83.13425503136033,
77 "radiusMeters": 93
78 },
79 "settings": {
80 "showAddresses": true
81 }
82 },
83 "latitude": 40.130642879687194,
84 "longitude": -83.13425503136033
85 },
86 {
87 "id": "70474188",
88 "name": "Matt",
89 "createdAtTime": "2023-07-27T14:18:27.457235Z",
90 "formattedAddress": "Matt the Millers Dublin OH",
91 "geofence": {
92 "circle": {
93 "latitude": 40.1060565,
94 "longitude": -83.1609646,
95 "radiusMeters": 260
96 }
97 },
98 "latitude": 40.1060565,
99 "longitude": -83.1609646
100 },
101 {
102 "id": "70816049",
103 "name": "Tuccis",
104 "createdAtTime": "2023-07-28T20:41:20.862933Z",
105 "formattedAddress": "Tucci's Dublin OH 43017",
106 "geofence": {
107 "circle": {
108 "latitude": 40.1002547,
109 "longitude": -83.11442760000001,
110 "radiusMeters": 961
111 },
112 "settings": {
113 "showAddresses": false
114 }
115 },
116 "latitude": 40.1002547,
117 "longitude": -83.11442760000001
118 },
119 {
120 "id": "72221870",
121 "name": "Library",
122 "createdAtTime": "2023-08-03T12:29:40.276738Z",
123 "formattedAddress": "dublin public library, dublin, oh 43017",
124 "geofence": {
125 "circle": {
126 "latitude": 40.115674,
127 "longitude": -83.13273319999999,
128 "radiusMeters": 350
129 }
130 },
131 "latitude": 40.115674,
132 "longitude": -83.13273319999999
133 },
134 {
135 "id": "73117679",
136 "name": "Welch 2",
137 "createdAtTime": "2023-08-07T13:45:23.217399Z",
138 "formattedAddress": "6865 Dulles Dr, Powell, OH 43065, USA",
139 "geofence": {
140 "circle": {
141 "latitude": 40.20511242770415,
142 "longitude": -83.10496092298392,
143 "radiusMeters": 307
144 },
145 "settings": {
146 "showAddresses": false
147 }
148 },
149 "latitude": 40.20511242770415,
150 "longitude": -83.10496092298392
151 },
152 {
153 "id": "73174391",
154 "name": "SR33-1",
155 "createdAtTime": "2023-08-07T18:57:20.113356Z",
156 "formattedAddress": "880 Colemans Crossing Blvd, Marysville, OH 43040, USA",
157 "geofence": {
158 "circle": {
159 "latitude": 40.23075414420927,
160 "longitude": -83.33725928206681,
161 "radiusMeters": 250
162 },
163 "settings": {
164 "showAddresses": false
165 }
166 },
167 "latitude": 40.23075414420927,
168 "longitude": -83.33725928206681
169 },
170 {
171 "id": "73174447",
172 "name": "SR33-2",
173 "createdAtTime": "2023-08-07T18:57:54.658614Z",
174 "formattedAddress": "US-33, Marysville, OH 43040, USA",
175 "geofence": {
176 "circle": {
177 "latitude": 40.21432062120889,
178 "longitude": -83.3077934597623,
179 "radiusMeters": 250
180 },
181 "settings": {
182 "showAddresses": false
183 }
184 },
185 "latitude": 40.21432062120889,
186 "longitude": -83.3077934597623
187 },
188 {
189 "id": "73174499",
190 "name": "SR42-1",
191 "createdAtTime": "2023-08-07T18:58:17.316922Z",
192 "formattedAddress": "11144 US-42, Plain City, OH 43064, USA",
193 "geofence": {
194 "circle": {
195 "latitude": 40.177217479800646,
196 "longitude": -83.2152583881994,
197 "radiusMeters": 250
198 },
199 "settings": {
200 "showAddresses": false
201 }
202 },
203 "latitude": 40.177217479800646,
204 "longitude": -83.2152583881994
205 }
206],
207"pagination": {
208 "endCursor": "",
209 "hasNextPage": false
210}Upon the successful retrieval of the address list, the frontend shall look like as the dashboard depicted below.
Fetch Asset (Vehicle) Information
Retrieve a list of your assets, which represent your vehicles. This information will be used to optimize routes based on vehicle capacity and other parameters.
1curl --request GET \
2 --url https://api.samsara.com/fleet/vehiclesThe following image depicts the dashboard with vehicles data.
Obtain Driver Details
Extract the data regarding your drivers, including their availability, name and other details. This ensures that route assignments align with driver capabilities.
1curl --request GET \
2 --url https://api.samsara.com/fleet/driversThe drivers data will look like the following dashboard upon successfull retrieval.
The integrated dashboard will look something like this after successfully fetching all the necessary data.
Create Jobs with Route Optimization API
Using NextBillion.ai's Route Optimization API, create optimization jobs.
POST API Request
The following API request sends data to NextBillion.ai’s Route Optimization API to create optimization jobs based on certain parameters. The response confirms the creation of jobs.
1{
2 "request": {
3 "url": "https://api.nextbillion.io/optimization/v2?key=<your_api_key>",
4 "method": "POST",
5 "body": "{\"location_index\":0,\"service\":120,\"priority\":0,\"time_windows\":[[1692671400,1692689400]]},{\"id\":73611245,\"description\":// Rest of the locations...],\"vehicles\":[{\"id\":47390364,\"start_index\":9,\"time_window\":[1692671400,1692689400],\"breaks\":[],\"max_tasks\":25,\"costs\":{\"fixed\":0}}],\"options\":{\"routing\":{\"mode\":\"car\"}}}",
6 "headers": {
7 "Content-Type": "application/json",
8 "ot-baggage-requestId": "undefined",
9 "x-datadog-trace-id": "8353104637349579618",
10 "x-datadog-parent-id": "3667167573625418059",
11 "x-datadog-sampling-priority": "-1",
12 "traceparent": "00-000000000000000073ec306938e3cb62-32e4657a8dc6314b-00",
13 "tracestate": "dd=s:-1",
14 "X-Forwarded-For": "183.82.31.124"
15 }
16 },
17 "response": {
18 "data": {
19 "id": "2bda4ef824fa6c290e82b626ed85a8b3",
20 "message": "Optimization job created",
21 "status": "Ok",
22 ]
23 },
24 "headers": {
25 "server": [
26 "nginx/1.25.2"
27 ],
28 "date": [
29 "Tue, 22 Aug 2023 08:22:36 GMT"
30 ],
31 "content-type": [
32 "application/json; charset=utf-8"
33 ],
34 "content-length": [
35 "134"
36 ],
37 "access-control-allow-origin": [
38 "*"
39 ],
40 "access-control-allow-headers": [
41 "authorization"
42 ],
43 "access-control-allow-methods": [
44 "DELETE,GET,HEAD,PUT,PATCH,POST,OPTIONS"
45 ],
46 "strict-transport-security": [
47 "max-age=15724800; includeSubDomains"
48 ],
49 "via": [
50 "1.1 google"
51 ],
52 "alt-svc": [
53 "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000"
54 ]
55 },
56 "status": 200,
57 "statusText": "OK"
58 }
59}Post API Response
1{
2 "id": "2bda4ef824fa6c290e82b626ed85a8b3",
3 "message": "Optimization job created",
4 "status": "Ok"
5 ]
6}
7Example JSON Response
1{
2 "result": {
3 "code": 0,
4 "summary": {
5 "cost": 3042,
6 "routes": 1,
7 "unassigned": 0,
8 "setup": 0,
9 "service": 960,
10 "duration": 3042,
11 "waiting_time": 0,
12 "priority": 0,
13 "distance": 34783.899999999994
14 },
15
16"routes": [
17 {
18 "vehicle": 47390364,
19 "cost": 3042,
20 "steps": [
21 {
22 "type": "start",
23 "arrival": 1692671400,
24 "duration": 0,
25 "setup": 0,
26 "service": 0,
27 "waiting_time": 0,
28 "location": [
29 40.1177,
30 -83.1265
31 ],
32 "location_index": 9
33 },
34 {
35 "type": "job",
36 "arrival": 1692671776,
37 "duration": 376,
38 "setup": 0,
39 "service": 120,
40 "waiting_time": 0,
41 "location": [
42 40.1337656,
43 -83.1773764
44 ]
45// Rest of the jobs…
46 }
47 ],
48 "setup": 0,
49 "service": 960,
50 "duration": 3042,
51 "waiting_time": 0,
52 "priority": 0,
53 "distance": 34783.899999999994,
54 "geometry": "enzsFrsjzNChCAnAA`... "}
55 ]
56 },
57 "status": "Ok",
58 "message": ""
59}Integration with Route Optimization API
After successfully pulling the necessary data from Samsara, integrate the fetched data with Route Optimization using the following API endpoint.
GET https://api.nextbillion.io/optimization/v2/result?id={{nbaiOptimizationRun.data.id}}&key={{localStorage.values.apiKey}}Map the fetched Samsara data to the respective API parameters. Configure optimization settings such as shift start and end time, service time, and start and end location coordinates.
1 btnSendSamsara.setDisabled(true);
2 let locations = [];
3 let jobs = [];
4 let shipments = [];
5 vehicles = [];
6 veh_attr = [];
7 stop_attr = [];
8 // sequence through all stops and create job array while
9 // also creating the indexed list of locations
10 let location_index = 0;
11 let location = [];
12 tblStops.data.forEach(planstop => {
13
14 let job = {
15 id: parseInt(planstop.id),
16 description: planstop.name,
17 location_index: location_index++,
18 service: numberInput1.value,
19 priority: 0,
20 time_windows: [[shiftStart,shiftEnd]]
21 }
22 location.push(`${planstop.latitude},${planstop.longitude}`);
23
24 jobs.push(job);
25
26 });
27
28 // Add shift start/stop location to location index
29 location.push(`${txtVehicleStartPosition2.value}`);
30 location.push(`${txtVehicleEndPosition2.value}`);
31 location_index += 1;
32 let veh_fixed_cost = 0;
33 tblDrivers.data.forEach( (v,idx) => {
34 let breaks = [];
35
36 let vehicle = {
37 id: parseInt(v.id),
38 start_index: location_index,
39 time_window: [shiftStart, shiftEnd],
40 skills: v.skills,
41 breaks: breaks,
42 max_tasks: 25,
43 costs: {
44 fixed: veh_fixed_cost
45 }
46 };
47 vehicles.push(vehicle);
48 veh_fixed_cost += 0;
49 }
50 });Trigger Route Optimization API
After successfully fetching the data to Route optimization API, trigger the API to generate optimized routes.
The following API request sends data to the NextBillion.ai server to optimize routes for vehicles using the POST method.
1POST
2"https://api.nextbillion.io/optimization/v2?key=<your_api_key>"
3The following code block prepares the required data (vehicles, shipments, jobs, locations) and configuration (routing mode), then triggers the optimization process.
Note: It is required to specify the routing mode. If not specified, the API will optimize the routes for default routing mode car. The API supports truck and car as routing modes.
1let options = {
2 routing: {
3 mode: "car"
4 }
5};
6
7localStorage.setValue('vehiclesNBAI', vehicles);
8localStorage.setValue('shipmentsNBAI', shipments);
9localStorage.setValue('jobsNBAI', jobs);
10localStorage.setValue('locationsNBAI', locations);
11localStorage.setValue('nbaiOptions', options);
12localStorage.setValue('nbaiVRPResult', null);
13nbaiOptimizationRun.trigger();By following these steps, you establish a robust data pipeline between Samsara's telematics and NextBillion.ai's Route Optimization API. This integration empowers you to transform your vehicle fleet management with precise and efficient route planning, dynamically adapting to real-world conditions and driving operational excellence.
