Receive Address Check-In Notifications

See files for this Use Case on GitHub here

Description

Push notifications are available for a series of actions on your Route4Me account. These notifications will help you keep track of what your team members are up to.

A driver is usually required to record when they arrive and depart destinations. They can do this manually, or they can save time (which helps drivers get to customers on-time, which in turn keeps customers happy) by using Route4Me's geo-fencing feature, which records such events automatically. In this Use Case you will learn how to make appropriate notifications programmatically.

Solution

Setting of a Real Time Callback

Real-time callbacks permit third-party systems to receive notifications about every system and driver event, such as a driver checking into a location or entering a Dynamic Geofence (TM).

The callback is set at the account owner user level, so all activities detected by sub-users and sub-drivers are also sent to the callback URL.

Note
You should enter in the field "Callbak URL" your own endpoint URL, which will receive and process notifications from Route4Me.

Optimization Parameters and addresses

Let us choose the Single Driver Round Trip option for this use case. Here are the parameters for this 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

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

AttributeTypeDescriptionHTTP
method
api_keystringAPI KEY of the userGET
optimization_problem_idstringOptimization problem IDGET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/optimization_problem.php
4 SET apikey=11111111111111111111111111111111
5 SET optprobid=69E1F364F7D2B78FBE9FFB37A0755CEB
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 one 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

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=EDE99139F62A036E9651D4A2AD168E81
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 were generated the by Route4Me API.

You can draw the generated round trip route as:

Compare it to the route drawn by an OSM provider. Note: the sequence of the addresses is generated by the Route4Me API, but lines between them are drawn by the OSM provider.

Also, you can compare it to the drawing of the official Route4Me website:

Send a notification Mark Address As Detected as Visited

You can send to an address the Detected as Visited notification, which will mark the address as visited.

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

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
route_id string Route ID GET
route_destination_id integer Route destination (address) ID GET
is_visited integer If equal to 1, address will be marked as visited POST


Let's mark the following address as visited: route_destination_id = 178141206 ("512 Florida Pl, Barberton, OH 44203").

1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/address.php
4 SET apikey=11111111111111111111111111111111
5 SET routeid=EDE99139F62A036E9651D4A2AD168E81
6 SET routedestinationid=178141206
7 
8 ECHO ON
9 
10 :: is_visited=1 means address was visited, is_visited=0 --- not visited
11 
12 curl -o file1.txt -k -g -X PUT -H "Content-Type: application/json" -d "@mark_address_as_detected_as_visited_data.json" "%url%?api_key=%apikey%&route_id=%routeid%&route_destination_id=%routedestinationid%"
13 
14 timeout /t 30

See sample RESPONSE JSON data here

Pay attention to these parameters:

"is_visited": true,
"timestamp_last_visited": 1470394510
Note
Time in the Route4Me API is in UNIX time format (also known as POSIX time or Epoch time).

You can see the route on a map as:

Send a notification Mark Address As Detected as Departed

Now you can send to another address with the Detected as Departed notification, which will mark the address as departed.

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

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
route_id string Route ID GET
route_destination_id integer Route destination (address) ID GET
is_departed integer If equal to 1, address will be marked as departed POST


Let's choose the following address to mark as departed: route_destination_id = 178141208 ("3495 Purdue St, Cuyahoga Falls, OH 44221").

1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/address.php
4 SET apikey=11111111111111111111111111111111
5 SET routeid=EDE99139F62A036E9651D4A2AD168E81
6 SET routedestinationid=178141208
7 
8 ECHO ON
9 
10 :: is_departed=1 means address was departed, is_departed=0 --- not departed
11 
12 curl -o file1.txt -k -g -X PUT -H "Content-Type: application/json" -d "@mark_address_as_detected_as_departed_data.json" "%url%?api_key=%apikey%&route_id=%routeid%&route_destination_id=%routedestinationid%"
13 
14 timeout /t 30

See sample RESPONSE JSON data here

Pay attention to these parameters:

"is_departed": true,
"timestamp_last_departed": 1470397746
Note
Time in the Route4Me API is in UNIX time format (also known as POSIX time or Epoch time).

Now you can see the route on a map as: