Associate GPS Sensor Data (IoT) to a Route

See files for this Use Case on the GitHub here

You can associate GPS tracking data to a route and use for tracking of the packages IoT applications.

Description

Nowadays Internet connection extends to non-computer physical objects. A connected vehicle can receive swift information about weather, new avoidance zones and geofences. A connected pallet for example, can tell to its owner about the current location and condition of the shipment. A connected street light can sense the presence of cars and send environmental conditions to drivers. An user of our Route4Me API can receive information about logistic activities by callback url etc.

Let us consider AV fleet with five vehicles. The vehicles can communicate during trip and they can interchange an information instantly. For example, if several vehicles have to go through same road and first one discovered that there are some obstacles on the road, it can send information about obstacles to others and they will reoptimize their routes according to the new circumstance. Or Because of an obstacle one could be out of schedule and other one can deliver similar package (for example, bottles of milk) to destination instead it - in this case they can interchange package ID between them and after avoiding the obstacle first vehicle can deliver package to the appropriate destination.

Solution

Optimization Parameters and addresses

Let's create a route with just 2 destinations, round trip type. Here are the parameters for an optimization problem:

ParameterTypeDescriptionHTTP method
api_keystringAPI KEY of the userGET
redirectintegerif equal to 1, will be redirected, if 0 - notGET
addressesarrayValid JSON array of Address objects. Click here to see the JSON SchemaPOST
parametersRoute ParametersValid JSON string of RouteParameters object. Click here to see the JSON SchemaPOST

You can see the addresses on the map as:

Create an Optimization

You can create new optimization for this use case example. From the cUrl example bellow you can see that:

ParameterTypeDescription
api_keystringAPI KEY of the user
input dataPOST dataValid JSON object string. Click here to see the JSON Schema
1 @ECHO OFF
2 :: Single Driver Round Trip
3 
4 ::See video tutorial here: http://support.route4me.com/route-planning-help.php?id=manual0:tutorial2:chapter1:subchapter1
5 
6 SET URL=https://www.route4me.com/api.v4/optimization_problem.php
7 SET apikey=11111111111111111111111111111111
8 
9 ECHO ON
10 
11 curl -o file1.txt -g -X POST -k -d "@single_driver_round_trip_data.json" "%URL%?api_key=%apikey%"
12 
13 timeout /t 30

You can expect an Optimization problem (see link), which generated a route already.

View the Optimization details

You can get more details from the newly created optimization problem:

The endpoint: https://www.route4me.com/api.v4/optimization_problem.php

HTTP Parameters

AttributeTypeDescriptionHTTP
method
api_keystringAPI KEY of the userGET
optimization_problem_idstringOptimization problem IDGET


1 @ECHO OFF
2 SET url=https://www.route4me.com/api.v4/optimization_problem.php
3 SET apikey=11111111111111111111111111111111
4 SET optprobid=62AA10A7B1AF948E5D81339630F0192A
5 
6 ECHO ON
7 curl -o file1.txt -g -X GET -k "%URL%?api_key=%apikey%&optimization_problem_id=%optprobid%"
8 
9 timeout /t 30

See sample RESPONSE JSON data here

Details of the Optimized Route

You can get more details of this route:

The endpoint: https://www.route4me.com/api.v4/route.php

HTTP Parameters

AttributeTypeDescriptionHTTP
method
api_keystringAPI KEY of the userGET
route_idstringRoute IDGET
route_path_outputstringIf equal to 'Poitns', you'll get an array of the path points to next addressGET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/route.php
4 SET apikey=11111111111111111111111111111111
5 SET routeid=D496F76F0ECEE0D3D16EE44F7896F11E
6 SET rpo=Points
7 
8 ECHO ON
9 
10 curl -o file1.txt -g -k -X GET "%url%?route_id=%routeid%&api_key=%apikey%&route_path_output=%rpo%"
11 
12 timeout /t 30

See sample RESPONSE JSON data here

Note
In the RESPONSE you can see the array of the fields path_to_next. Those will be used to draw routes on a map, exactly as they generated by Route4Me API.

You can draw generated round trip route as:

Add Orders with Custom Data to the Route

You can add the orders to the route. The orders should contain custom data with item name, because we are going to search item's route and GPS position later.

The endpoint: https://route4me.com/api.v4/optimization_problem.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
optimization_problem_id string Optimization problem ID GET
redirect intenger If equal to 1, will be redirected GET
Addresses array Valid JSON string of the Address objects array POST


See sample INPUT JSON data here

Pay attention to the parameters into the custom data:

"package": "Tablet"
...
"package": "Books"
...
1 @ECHO OFF
2 
3 SET url=https://route4me.com/api.v4/optimization_problem.php
4 SET apikey=11111111111111111111111111111111
5 SET rdirect=0
6 SET optid=62AA10A7B1AF948E5D81339630F0192A
7 
8 ECHO ON
9 
10 :: The example refers to the process of adding an order to an optimization by sending HTPP PUT data
11 
12 curl -o file1.txt -k -g -X PUT -H "Content-Type: application/json" -d "@add_order_to_optimization_data.json" "%url%?api_key=%apikey%&redirect=%rdirect%&optimization_problem_id=%optid%"
13 
14 timeout /t 30

See sample RESPONSE JSON data here

You can do following steps again as they described above:

  • View the Optimization details;
  • Details of the Optimized Route.

and see that the optimization problem now has the same route with 2 stops, but additional unrouted destinations.

Reoptimize Optimization

In order to reshape the route including new addresses, you can reoptimize the existing optimization.

The endpoint: https://www.route4me.com/api.v4/optimization_problem.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
optimization_problem_id string Optimization problem ID GET
reoptimize integer If equal to 1, the optimization problem will be reoptimized GET
Route Parameters object Valid JSON object string. Click here to see the JSON Schema GET
Addresses array Valid JSON string of the Address objects. Click here to see the JSON Schema GET


Note
After reoptimization the parameter route_id of the routes could be changed.
1 @ECHO OFF
2 SET url=https://www.route4me.com/api.v4/optimization_problem.php
3 SET apikey=11111111111111111111111111111111
4 SET optprobid=62AA10A7B1AF948E5D81339630F0192A
5 
6 ECHO ON
7 curl -o file1.txt -g -X PUT -k "%url%?api_key=%apikey%&optimization_problem_id=%optprobid%&reoptimize=1"
8 
9 timeout /t 30

You can expect this API response:

{"status":true}

You can do following steps again as they described above:

  • View the Optimization details (see sample RESPONSE JSON data here);
  • Details of the Optimized Route (see sample RESPONSE JSON data here).

and see that now you have the reoptimized route with 8 destinations.

You can draw the reoptimized route on a map as:

Find a Route Containing the Asset

You can find a route containing specified asset by custom data. As you can find in the input JSON file (see the file here) for the topic Add Orders with Custom Data to the Route, the order has custom data:

"custom_fields": {
"package": "Notebook"
}

The endpoint: https://www.route4me.com/api.v4/route.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
query string Query string GET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/route.php
4 SET apikey=11111111111111111111111111111111
5 SET query=Notebook
6 
7 ECHO ON
8 curl -o file1.txt -g -k -X GET "%url%?api_key=%apikey%&query=%query%"
9 
10 timeout /t 30

See sample response JSON data here.

Pay attention to the parameter route_id:

"route_id": "814FB49CEA8188D134E9D4D4B8B0DAF7"

Set GPS position of a vehicle

Many vehicles are equipped with GPS devices. With our API, you can manually set a GPS position to the vehicle and retrieve this information.

The endpoint: https://www.route4me.com/track/set.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
format string RESPONSE format GET
member_id integer User ID GET
route_id string Route ID GET
course integer The direction in degrees in which the vehicle is heading GET
speed decimal The speed with which the vehicle is moving GET
lat double Geographic Latitude GET
lng double Geographic Longitude GET
device_type string Device type ENUM(iphone, ipad, android_phone, android_tablet) GET
device_guid string Device ID GET
vehicle_id string Vehicle ID GET


1 @ECHO OFF
2 SET url=https://www.route4me.com/track/set.php
3 SET apikey=11111111111111111111111111111111
4 SET frm=XML
5 SET membid=1
6 SET route_id=CEF9073F2C7BD79D967895A88E07F863
7 SET course=70
8 SET speed=60
9 SET lat=41.00478
10 SET lng=-81.59004
11 SET devtype=android_phone
12 SET devguid="HK5454H0K454564WWER445"
13 SET vehid=00000000000000000000000000000000
14 
15 ECHO ON
16 
17 :: There are also several optional parameters: tx_id, altitude, device_timestamp, app_version
18 
19 curl -o file1.txt -g -X GET -k "%URL%?api_key=%apikey%&format=%frm%&member_id=%membid%&route_id=%route_id%&course=%course%&speed=%speed%&lat=%lat%&lng=%lng%&device_type=%devtype%&device_guid=%devguid%&vehicle_id=%vehid%"
20 
21 timeout /t 30

You can expect this API response:

{
"status":true,
"tx_id":"3f3420fe077f42c1cfd2baed217acca43fe8ac6a"
}

Retrieve an Asset Tracking Information

Now you can find a route containing the destination with the item, even if this destination was moved from initial route to other one.

The endpoint: https://route4me.com/api.v4/status.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
tracking string Asset unique internal ID GET


1 @ECHO OFF
2 
3 SET url=https://route4me.com/api.v4/status.php
4 SET apikey=11111111111111111111111111111111
5 SET tracking="Q7G9P1L9"
6 
7 ECHO ON
8 
9 :: Example refers to the process of getting asset tracking data by sending HTTP GET parameters.
10 
11 curl -o file1.txt -g -X GET -k "%url%?api_key=%apikey%&tracking=%tracking%"
12 
13 timeout /t 30

You can expect this API response:

{
"tracking_number": "PL3EP8PR",
"status_history": [],
"locations": [{
"lat": 41.148579,
"lng": -81.42923,
"icon": "destination"
}],
"custom_data": {
"package": "Notebook"
},
"arrival": [{
"from_unix_timestamp": 1465964736,
"to_unix_timestamp": 1465968336
}],
"delivered": false
}

You can draw the asset location on a map as:

Dynamic Re-optimization a Route After Receiving new Information

Suppose, your driver is on the route to the client and suddenly you receive the information about the new conditions along the route - e.g. high hills covered with snow or road construction ahead. Having this information, you want to re-optimize route.

You can read the article Create a polygon Territory Around a Geographic Area on how to construct the territorial and avoidance zones with Route4Me API. This time let us do that with Route4Me web UI.

Also you can read the article Receive Address Check-In Notifications to learn how to use Rout4eMe's callback feature.

We can draw an avoidance zone using Route4Me web UI and then draw it along with the route on the map using the open source tools:

When we created the avoidance zone with the Web UI, we named it as **"AvZone above Hudson"**. Please note that inside the parameter avoidance_zones you have to indicate the avoidance zone ID, not avoidance zone name. So, first you have to find out the avoidance zone ID.

The endpoint: https://www.route4me.com/api.v4/avoidance.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/avoidance.php
4 SET apikey=11111111111111111111111111111111
5 
6 ECHO ON
7 curl -o file1.txt -g -k -X GET "%URL%?api_key=%apikey%"
8 
9 timeout /t 30

See sample response JSON data here.

You can find in the JSON data that territory_id=29AACF4A1B5F38F50EF7A7EAF6DCAFAB for our avoidance zone.

Now you can re-optimize the optimization.

The endpoint: https://www.route4me.com/api.v4/optimization_problem.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
optimization_problem_id string Optimization problem ID GET
reoptimize integer If equal to 1, the optimization problem will be reoptimized GET
Route Parameters object Valid JSON object string. Click here to see the JSON Schema GET
Addresses array Valid JSON string of the Address objects. Click here to see the JSON Schema GET


See sample input JSON data here.

1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/optimization_problem.php
4 SET apikey=11111111111111111111111111111111
5 SET optprobid=62AA10A7B1AF948E5D81339630F0192A
6 
7 ECHO ON
8 curl -o file1.txt -g -X PUT -k -d "@update_route_data.json" "%url%?api_key=%apikey%&optimization_problem_id=%optprobid%&reoptimize=1"
9 
10 timeout /t 30

See sample response JSON data here.

You can do following steps again as they described above:

  • View the Optimization details;
  • Details of the Optimized Route.

and see that the optimized route avoided the avoidance zone. You can see it on a map as:

Contents