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 2 3# Fetch addresses from Samsara Telematics Dashboard curl --request GET \ --url https://api.samsara.com/addresses
API Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210"data": [ { "id": "68913795", "name": "Tuttle Crossing", "createdAtTime": "2023-07-21T00:29:59.968745Z", "formattedAddress": "Tuttle Crossing, Dublin, Ohio 43016", "geofence": { "circle": { "latitude": 40.0784625, "longitude": -83.1287112, "radiusMeters": 360 } }, "latitude": 40.0784625, "longitude": -83.1287112 }, { "id": "69020143", "name": "Dublin Pool", "createdAtTime": "2023-07-21T11:03:00.814447Z", "formattedAddress": "dublin community pool, dublin oh 43017", "geofence": { "circle": { "latitude": 40.1229158, "longitude": -83.1442514, "radiusMeters": 250 } }, "latitude": 40.1229158, "longitude": -83.1442514 }, { "id": "70232689", "name": "Brandon Park", "createdAtTime": "2023-07-26T17:54:47.462049Z", "formattedAddress": "Brandon Park Dublin OH 43017", "geofence": { "circle": { "latitude": 40.1259995, "longitude": -83.1306475, "radiusMeters": 162 }, "settings": { "showAddresses": false } }, "latitude": 40.1259995, "longitude": -83.1306475 }, { "id": "70232810", "name": "Carrigan Ridge", "createdAtTime": "2023-07-26T17:55:39.892546Z", "formattedAddress": "4837 Carrigan Ridge Dr, Dublin, OH 43017, USA", "geofence": { "circle": { "latitude": 40.13228346371899, "longitude": -83.11910591484421, "radiusMeters": 100 }, "settings": { "showAddresses": false } }, "latitude": 40.13228346371899, "longitude": -83.11910591484421 }, { "id": "70232853", "name": "Ashford", "createdAtTime": "2023-07-26T17:56:01.820412Z", "formattedAddress": "5495 Ashford Rd, Dublin, OH 43017, USA", "geofence": { "circle": { "latitude": 40.130642879687194, "longitude": -83.13425503136033, "radiusMeters": 93 }, "settings": { "showAddresses": true } }, "latitude": 40.130642879687194, "longitude": -83.13425503136033 }, { "id": "70474188", "name": "Matt", "createdAtTime": "2023-07-27T14:18:27.457235Z", "formattedAddress": "Matt the Millers Dublin OH", "geofence": { "circle": { "latitude": 40.1060565, "longitude": -83.1609646, "radiusMeters": 260 } }, "latitude": 40.1060565, "longitude": -83.1609646 }, { "id": "70816049", "name": "Tuccis", "createdAtTime": "2023-07-28T20:41:20.862933Z", "formattedAddress": "Tucci's Dublin OH 43017", "geofence": { "circle": { "latitude": 40.1002547, "longitude": -83.11442760000001, "radiusMeters": 961 }, "settings": { "showAddresses": false } }, "latitude": 40.1002547, "longitude": -83.11442760000001 }, { "id": "72221870", "name": "Library", "createdAtTime": "2023-08-03T12:29:40.276738Z", "formattedAddress": "dublin public library, dublin, oh 43017", "geofence": { "circle": { "latitude": 40.115674, "longitude": -83.13273319999999, "radiusMeters": 350 } }, "latitude": 40.115674, "longitude": -83.13273319999999 }, { "id": "73117679", "name": "Welch 2", "createdAtTime": "2023-08-07T13:45:23.217399Z", "formattedAddress": "6865 Dulles Dr, Powell, OH 43065, USA", "geofence": { "circle": { "latitude": 40.20511242770415, "longitude": -83.10496092298392, "radiusMeters": 307 }, "settings": { "showAddresses": false } }, "latitude": 40.20511242770415, "longitude": -83.10496092298392 }, { "id": "73174391", "name": "SR33-1", "createdAtTime": "2023-08-07T18:57:20.113356Z", "formattedAddress": "880 Colemans Crossing Blvd, Marysville, OH 43040, USA", "geofence": { "circle": { "latitude": 40.23075414420927, "longitude": -83.33725928206681, "radiusMeters": 250 }, "settings": { "showAddresses": false } }, "latitude": 40.23075414420927, "longitude": -83.33725928206681 }, { "id": "73174447", "name": "SR33-2", "createdAtTime": "2023-08-07T18:57:54.658614Z", "formattedAddress": "US-33, Marysville, OH 43040, USA", "geofence": { "circle": { "latitude": 40.21432062120889, "longitude": -83.3077934597623, "radiusMeters": 250 }, "settings": { "showAddresses": false } }, "latitude": 40.21432062120889, "longitude": -83.3077934597623 }, { "id": "73174499", "name": "SR42-1", "createdAtTime": "2023-08-07T18:58:17.316922Z", "formattedAddress": "11144 US-42, Plain City, OH 43064, USA", "geofence": { "circle": { "latitude": 40.177217479800646, "longitude": -83.2152583881994, "radiusMeters": 250 }, "settings": { "showAddresses": false } }, "latitude": 40.177217479800646, "longitude": -83.2152583881994 } ], "pagination": { "endCursor": "", "hasNextPage": false }
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.
1 2curl --request GET \ --url https://api.samsara.com/fleet/vehicles
The 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.
1 2curl --request GET \ --url https://api.samsara.com/fleet/drivers
The 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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59{ "request": { "url": "https://api.nextbillion.io/optimization/v2?key=<your_api_key>", "method": "POST", "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\"}}}", "headers": { "Content-Type": "application/json", "ot-baggage-requestId": "undefined", "x-datadog-trace-id": "8353104637349579618", "x-datadog-parent-id": "3667167573625418059", "x-datadog-sampling-priority": "-1", "traceparent": "00-000000000000000073ec306938e3cb62-32e4657a8dc6314b-00", "tracestate": "dd=s:-1", "X-Forwarded-For": "183.82.31.124" } }, "response": { "data": { "id": "2bda4ef824fa6c290e82b626ed85a8b3", "message": "Optimization job created", "status": "Ok", ] }, "headers": { "server": [ "nginx/1.25.2" ], "date": [ "Tue, 22 Aug 2023 08:22:36 GMT" ], "content-type": [ "application/json; charset=utf-8" ], "content-length": [ "134" ], "access-control-allow-origin": [ "*" ], "access-control-allow-headers": [ "authorization" ], "access-control-allow-methods": [ "DELETE,GET,HEAD,PUT,PATCH,POST,OPTIONS" ], "strict-transport-security": [ "max-age=15724800; includeSubDomains" ], "via": [ "1.1 google" ], "alt-svc": [ "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000" ] }, "status": 200, "statusText": "OK" } }
Post API Response
1 2 3 4 5 6{ "id": "2bda4ef824fa6c290e82b626ed85a8b3", "message": "Optimization job created", "status": "Ok" ] }
Example JSON Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59{ "result": { "code": 0, "summary": { "cost": 3042, "routes": 1, "unassigned": 0, "setup": 0, "service": 960, "duration": 3042, "waiting_time": 0, "priority": 0, "distance": 34783.899999999994 }, "routes": [ { "vehicle": 47390364, "cost": 3042, "steps": [ { "type": "start", "arrival": 1692671400, "duration": 0, "setup": 0, "service": 0, "waiting_time": 0, "location": [ 40.1177, -83.1265 ], "location_index": 9 }, { "type": "job", "arrival": 1692671776, "duration": 376, "setup": 0, "service": 120, "waiting_time": 0, "location": [ 40.1337656, -83.1773764 ] // Rest of the jobs… } ], "setup": 0, "service": 960, "duration": 3042, "waiting_time": 0, "priority": 0, "distance": 34783.899999999994, "geometry": "enzsFrsjzNChCAnAA`... "} ] }, "status": "Ok", "message": "" }
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 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50btnSendSamsara.setDisabled(true); let locations = []; let jobs = []; let shipments = []; vehicles = []; veh_attr = []; stop_attr = []; // sequence through all stops and create job array while // also creating the indexed list of locations let location_index = 0; let location = []; tblStops.data.forEach(planstop => { let job = { id: parseInt(planstop.id), description: planstop.name, location_index: location_index++, service: numberInput1.value, priority: 0, time_windows: [[shiftStart,shiftEnd]] } location.push(`${planstop.latitude},${planstop.longitude}`); jobs.push(job); }); // Add shift start/stop location to location index location.push(`${txtVehicleStartPosition2.value}`); location.push(`${txtVehicleEndPosition2.value}`); location_index += 1; let veh_fixed_cost = 0; tblDrivers.data.forEach( (v,idx) => { let breaks = []; let vehicle = { id: parseInt(v.id), start_index: location_index, time_window: [shiftStart, shiftEnd], skills: v.skills, breaks: breaks, max_tasks: 25, costs: { fixed: veh_fixed_cost } }; vehicles.push(vehicle); veh_fixed_cost += 0; } });
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.
1 2POST "https://api.nextbillion.io/optimization/v2?key=<your_api_key>"
The 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.
1 2 3 4 5 6 7 8 9 10 11 12 13let options = { routing: { mode: "car" } }; localStorage.setValue('vehiclesNBAI', vehicles); localStorage.setValue('shipmentsNBAI', shipments); localStorage.setValue('jobsNBAI', jobs); localStorage.setValue('locationsNBAI', locations); localStorage.setValue('nbaiOptions', options); localStorage.setValue('nbaiVRPResult', null); nbaiOptimizationRun.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.
