Create Persistent Search Groups

See files for this Use Case on GitHub here

You can create persistent search groups using various parameters of the Address Group object.

Description

A large logistics company has hundreds of locations (addresses) that it delivers to. Making things more complicated is that different types of packages require different conditions of transportation. Consider glassware, for example. A package containing fragile glass plates requires special care from drivers and route planners.

Solution

The Route4Me API has a special repository of the locations you can use for testing.

If you have your own API key already, you can create any number of new addresses in your address book, but for testing is only a limited number of locations is allowed.

Suppose you own a logistics business in Las Vegas and you need to create search groups. In this case, the first step is to see which test locations from Las Vegas are in the testing repository.

Get Locations by Containing Specified Text in Any Field

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

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
query string If query is array, search engine will search by fields, if query is string will search by all text fields GET
offset integer Start position of searching GET
limit integer A limit number of the returned findings GET


1 ECHO OFF
2 
3 setlocal enableDelayedExpansion
4 
5 SET url=https://www.route4me.com/api.v4/address_book.php
6 SET apikey=11111111111111111111111111111111
7 
8 :: Example demostrates search for all Addressbook locations, any fields which of contains search_text value.
9 
10 SET search_text=Las Vegas
11 SET "search_text=!search_text: =%%20!"
12 SET offset=0
13 SET limit=40
14 
15 ECHO ON
16 
17 curl -o file1.txt -k -X GET "%url%?api_key=%apikey%&query=%search_text%&member_id=1&offset=%offset%&limit=%limit%"
18 
19 timeout /t 30

You can see the locations on the map as:

Add Addressbook Locations to Group

Now let's choose several contacts and add them to group "Glass package". This allows us to search for them as a group.

Let's to choose contacts with address_id:

"address_id": 4560331,
"address_id": 4560087,
"address_id": 4560098,
"address_id": 4564330,
"address_id": 4564346

The endpoint: http://www.route4me.com/api.v4/address_book.php

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
address_id integer Addressbook Location ID POST
address_group string Group name of the addressbook locations<String, String> POST


1 @ECHO OFF
2 
3 SET url=http://www.route4me.com/api.v4/address_book.php
4 SET apikey=11111111111111111111111111111111
5 
6 ECHO ON
7 
8 curl -o file1.txt -g -X PUT -H "Content-Type: application/json" -d "@address_data_for_update.json" "%url%?api_key=%apikey%"
9 
10 timeout /t 30

From the cURL example above, you can see that input data is stored in the file address_data_for_update.json with this content:

{
"address_id":4560331,
"address_group": "Glass package"
}

You can repeat the batch script for the remaining 4 locations by setting the appropriate value to the parameter address_id.

Search for Locations Group

Now you can search for all locations with the package type "Glass package".

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

HTTP Parameters

Attribute Type Description HTTP
method
api_key string API KEY of the user GET
query string If query is array, search engine will search by fields, if query is string will search by all text fields GET


1 ECHO OFF
2 
3 setlocal enableDelayedExpansion
4 
5 SET url=https://www.route4me.com/api.v4/address_book.php
6 SET apikey=11111111111111111111111111111111
7 
8 :: Example demonstrates search for all Address Book contacts and any field which contains search_text value.
9 
10 SET search_text=Glass package
11 SET "search_text=!search_text: =%%20!"
12 
13 ECHO ON
14 
15 curl -o file1.txt -k -X GET "%url%?api_key=%apikey%&query=%search_text%"
16 
17 timeout /t 30

See sample RESPONSE JSON data here

As you can see, you have all the address book locations with the parameter address_group containing the text "Glass package".

Note
You should choose unique name for each group, because the text is searched in other fields, too.

You can represent the locations on the map as:

Create Optimization Problem from Found Locations

Let's create optimized routes from these address book locations. First, we have to create the Optimization Problem. Let's choose the single driver round trip option.

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 prepare the JSON input file from the found group (see link).

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 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

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=C6951ECD8AADB1B0DB2F001C3436E8BA
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 the round trip route.

Get 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=38C44AEA54330BA6D1D73F24DE843B10
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 by the Route4Me API.

You can draw the generated route as: