Routing Preferences Services

Description

Routing calculation based on green preferences (avoid most crowded routes, use public transportation, minimize fuel consumption). This service provides routes calculated for different types of vehicles (depending on user preference for maximum distances) so to let users to select “zero emission” instead of bus or private car. CO2 equivalent emissions will be based on available data and statistics provided by the European Environmental Agency (EEA, 2015).

Work done

Development completed and service deployed

Work remaining

Integrated test

Current issues

None

Details

The list of avaliable services include:

1. Save itinerary
2. Get itinerary
3. Delete itinerary
4. Save/Update preferences
5. Get preferences
6. Delete preferences

Test service page: http://hub.geosmartcity.eu/routing-preferences/testService.jsp

Save itinerary

This service allows to save an itinerary into the database. This itinerary will be the json text provided as a response by the OTP service enriched by some more information.

An example of the json response structure the OTP service will output is:

In the first section of the response are displayed all the request parameters that were passed to OTP.

The second section is the OTP calculated plan, which is the actual result of the OTP calculations, and mainly consists of a list of itineraries. Each of those represents a set of steps to reach a destination from a given point. For each step are listed information about departure and arrival times, and the kind of transportation used.

The debug output section lists some statistics about the OTP calculation itself.

When the user is willing to save an itinerary we imagine that he will only choose one among the enlisted OTP itinerary results. Moreover he may add additional notes linked to the preference. We also want to save the used identifier as well, to match the saved values to the correct users.

Therefore in addition to this json, the user has to provide those 3 additional values.

This image shows how the test service page looks as we select the save itinerary service.

1. In the Text field the user has to paste the output json response as provided from the OTP service.
2. The User id field identifies the user who is saving the itinerary. This value will be saved inside the json string in the first level.
3. The Itinerary id field has to be used as an index: the inserted number will select one among the n itineraries values that form the plan in the OTP json text. It has to be an integer value between 1 and the maximum number of itineraries that are found in the OTP json response.
4. The Notes field contains other useful information about the choice of this particular itinerary. This value will be saved inside the json string in the first level.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain the itineraryId value (the unique identification key to the saved record)

or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.

Get itinerary

This service allows to retrieve one or more itineraries from the database. The user will input queries related to the json itinerary previously saved.

The queries must follow the following syntax:

1. from the json root node type all the names of all the json nodes of the json tree until you reach the desired element.
2. each element must be quoted (')
3. each element must be separated from the following elements by a '/'
4. all operators allowed in the PSQL database are still legal.

For example we could search for all the itineraries belonging to a specific user through the following query:

'userId' = '1'

As mentioned in the previous paragraph the userId parameter is saved in the first json level, so the query is quite simple.

Another example could be retrieving all the itineraries that have a specific request parameter. Those parameters are inside the requestParameters element. Therefore an example to do that is:

'requestParameters'/'mode' LIKE '%TRANSIT%'

Which will find all the itineraries that contain TRANSIT as one of its modes.

Of course it is possible to specify logic operators for the research. We could indeed mix the two previous queries into a more specific one:

'requestParameters'/'mode' LIKE '%TRANSIT%' AND 'userId' = '1'

We could also use brackets to order the clauses:

'requestParameters'/'mode' LIKE '%TRANSIT%' AND ('userId' = '1' OR 'userId' = '11')

This image shows how the test service page looks as we select the get itinerary service.

1. In the Text field the user has to insert a query following the aforementioned syntax.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain all the itineraries found, grouped togheter as a list under a new root element named json

or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.

Delete itinerary

This service allows to delete an itinerary given its unique identifier as a database row.

This image shows how the test service page looks as we select the delete itinerary service.

1. In the Itinerary Id field the user has to insert the id of the database row to be deleted.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain the itineraryId value (the unique identification key to the saved record) or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.

Save/Update preferences

This service allows to save the user preferences into the database. The preferences have to be presented as a json text and they will be saved without further elaboration. The user can specify all the parameters he need within the json text and all of those will be saved. The only mandatory parameter is the userId parameter, which identifies the user who is saving his or her preferences.

Only one preference per user is allowed, so if a new preference with the same userId of another one previously inserted is about to be saved, it will replace the other one instead.

An example of preferences could be the following:

{ "userId":1, "maxWalkingDistance":10, "walkingSpeed":10, "maxBikingDistance":10, "bikingSpeed":10 }

This image shows how the test service page looks as we select the save/update preferences service.

1. In the Text field the user has to insert his or her preferences as a json string.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain the userId value or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.

Get preferences

This service allows to get the user preferences into the database. This research is only made through the userId parameter. The user has to insert a json string containing the userId value. The corresponding preference will be displayed as the result.

This image shows how the test service page looks as we select the get preferences service.

1. In the Text field the user has to insert the userId as a json string.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain the preferences or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.

Delete preferences

This service allows to delete the user preferences from the database. This deletion is only made through the userId parameter. The user has to insert a json string containing the userId value. The corresponding preference will be deleted as the result.

This image shows how the test service page looks as we select the delete preferences service.

1. In the Text field the user has to insert the userId as a json string.

After pressing the submit button the result will appear within the response field which is always a json string. This result will either cointain the userId of the deleted preference or an error output if the elaboration didn’t succeed. The error is composed of an error code, and a description that should guide the user to an easy recognition of the problem. More information can always be obtained checking log files.