Upload Addresses into the Address Book and Plan Routes from a Territory

See files for this Use Case on GitHub here

Let's look at how you can upload addresses into the address book, make a territory zone around some of them, and plan routes from the territory.

Description

Customers in particularly urban areas can be hard to get to because of heavy traffic, one-way streets, and other inner-city issues. Planning routes for this situation manually by figuring out the best way to each address one by one is difficult and time-consuming. But Route4Me's territory routing feature makes this task fast and easy.

The Territory Routing and Management release will integrate with the upcoming Logistics Network Analysis module, which uses Route4Me's advanced predictive modeling and data science capabilities to analyze possible facility relocation costs and savings in real-time.

Solution

Add Locations to an Address Book

Suppose your logistics company just won over 9 new customers in Huston City, Texas. You can enter these 9 new addresses into the address book belonging to your Route4Me account. These addresses are in the file all_contacts_data.json. Extract the addresses one by one and insert them in the JSON input file and run batch script as described below:

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
input data POST data Valid JSON string of the Address book location. Click here to see the JSON Schema POST


From the cURL example below, you can see that:

1 ECHO OFF
2 SET url=https://www.route4me.com/api.v4/address_book.php
3 SET apikey=11111111111111111111111111111111
4 
5 ECHO ON
6 
7 :: Needs clarification - requires member_id, although ir is sent
8 
9 curl -o file1.txt -k -X POST -d "@add_contact_to_addressbook_data.json" "%url%?api_key=%apikey%&member_id=1"
10 
11 timeout /t 30

You can expect an Address book location object as response (see link).

Perform those steps for remaining 8 addresses, too (you can see all response JSON files in this folder).

On the Route4Me map, you can see all 9 locations as:

Make Territory Zone around Chosen Locations

We already have 9 new addresses in the Address book with the following address_id:

"address_id": 8762599,
"address_id": 8762600,
"address_id": 8762601,
"address_id": 8762629,
"address_id": 8762630,
"address_id": 8762631,
"address_id": 8762632,
"address_id": 8762633,
"address_id": 8762634

Let’s choose the first 6 addresses and make a Territory Zone around them.

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
input data POST data Valid JSON string of the Territory object. Click here to see the JSON Schema POST


From the cURL example below, you can see that:

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

See sample RESPONSE JSON data here

On the Route4Me map, you can see the created Territory Zone as:

Get Addresses from the Territory

You can get all the addresses from inside the Territory Zone.

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

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
territory_id string An unique ID for a Territory zone GET
addresses integer If equla to 1, response will be with address list, if not - not GET


1 @ECHO OFF
2 
3 SET url=https://www.route4me.com/api.v4/territory.php
4 SET apikey=11111111111111111111111111111111
5 SET terid=B0749C40E541523500F97D87D73C762C
6 SET addresses=1
7 
8 ECHO ON
9 curl -o file1.txt -g -k -X GET "%URL%?api_key=%apikey%&territory_id=%terid%&addresses=%addresses%"
10 
11 timeout /t 30
Attention
In the response you will get all the addresses, created not only by you, but by others too - you should filter the address list.

See sample RESPONSE JSON data here

Create an Optimization

Now you can create an optimization from the addresses inside Territory zone.

From the cURL example below, 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 
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 SET route_path_output=Points
9 
10 ECHO ON
11 
12 curl -o file1.txt -g -X POST -k -d "@single_driver_round_trip_data.json" "%URL%?api_key=%apikey%&route_path_output=%route_path_output%"
13 
14 timeout /t 30

You can expect an Optimization Problem (see link) with the generated route.

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=4A033647BD3A00F48A6036DF4D812070
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 one route with route_id=617D8755F4B204FE4F19342741D59205

Get Details of the Route

You can get more details of the route and draw it on a map.

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=617D8755F4B204FE4F19342741D59205
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 the route on a map as: