Plan Routes and Notify Customers with Tracking Info

See files for this Use Case on GitHub here

Description

Route4Me provides advanced options for tracking driver activity. All tracking functionalities require drivers to use the Route4Me mobile app for iOS or Android and also have location services enabled on their devices. The Route4Me API tracking feature lets you set the current GPS position for a specific device and route and receive vehicle tracking history.

Solution

Optimization Parameters and addresses

Let's choose a Single Driver Round Trip option for this Use Case. The parameters for the Optimization Problem are:

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

In Route Parameters you can define the vehicle_id field. Set it to FFFF72BF6E06DC3C746673279BDAAE05 (This is the ID of one of the vehicles used in Route4Me's test account database).

You can see the addresses on the map as:

Create an Optimization

The cURL example below shows you how to create new optimized routes for this Use Case:

ParameterTypeDescription
api_keystringAPI KEY of the user
input dataPOST dataValid JSON object string. Click here to see the JSON Schema
1 @ECHO OFF
2 
3 :: Single Driver Round Trip
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 has 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

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
optimization_problem_id string Optimization problem ID GET


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

See sample RESPONSE JSON data here

In the RESPONSE you can see an array of the addresses, which belong to a round trip route.

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

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
route_id string Route ID GET
route_path_output string If equal to 'Points', you'll get an array of the path points to next address GET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/route.php
4 SET apikey=11111111111111111111111111111111
5 SET routeid=6FA75DE4CD327AA57BE2EE7DB11DA083
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 and use them to draw routes on a map, exactly as they are generated by the Route4Me API.

You can draw generated route as:

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 
3 SET url=https://www.route4me.com/track/set.php
4 SET apikey=11111111111111111111111111111111
5 SET frm=XML
6 SET membid=1
7 SET route_id=6FA75DE4CD327AA57BE2EE7DB11DA083
8 SET course=70
9 SET speed=60
10 SET lat=41.003671512
11 SET lng=-81.5984610468
12 SET devtype=android_phone
13 SET devguid="HK5454H0K454564WWER445"
14 SET vehid=FFFF72BF6E06DC3C746673279BDAAE05
15 
16 ECHO ON
17 
18 :: There are also several optional parameters: tx_id, altitude, device_timestamp, app_version
19 
20 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%"
21 
22 timeout /t 30

You can expect this API response:

{"status":true}

Retrieve Tracking Information

Now you can retrieve tracking information from the route.

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
route_id string Route ID GET
device_tracking_history integer If equal to 1, output route tracking data in response GET


See sample RESPONSE JSON data here

Pay attention to this block of the parameters in the RESPONSE:

"tracking_history": [
{
"s": "60",
"lt": "41.003671512",
"m": 1,
"lg": "-81.5984610468",
"d": 70,
"ts": "1470408402",
"ts_friendly": "2016-08-05 10:46:42",
"src": "R4M"
}
]

On a map, you can draw this information as: