Routes

Overview

This macro can be used to generate A to B routes to display on a map, along with turn-by-turn directions and summary features such as total travel time.

Inputs

This macro runs off a single input data file.

The input data must include four fields:

• Latitude and longitude fields for the origins
• Latitude and longitude fields for the destinations

If you have your origins and destinations in separate files, then the Append Fields tool can be used to combine them into the required single input data file.

1. Credentials

Application ID and Application Key must be filled in with your API key details.

If you don’t already have an API key, you can get a trial key here.

2. Configuration

From

• Select Latitude Field - select the field from the input data that specifies the latitude of the origins
• Select Longitude Field - select the field from the input data that specifies the longitude of the origins

To

• Select Latitude Field - select the field from the input data that specifies the latitude of the destinations
• Select Longitude Field - select the field from the input data that specifies the longitude of the destinations

Search Method

• Arriving By - calculates routes arriving by the Search Date Time
• Departing At - calculates routes departing at the Search Date Time

Output Type

• Summarized - this option returns one data row for each A to B route
• Detailed - this option returns multiple rows of data for each A to B route (one for each leg of the journey)

3. Basic

Transport Method

• Set Specific Transport Method - chose the method of transport (if multiple options are selected, multiple routes will be returned for each pair of origins/destinations)
• Select Transport Method from Field - use a field in the input data to select the transport method

Get Fare Data?

• Whether to include fare data in the output. NB – fare data is only currently available in the UK. Requesting fare data in other countries will cause the macro to return an error.

Search Date Time

• Set Specific Date Time - set the date and time to be used as the Arriving By or Departing At time
• Set Date Time from Field - use a field in the input data to select the date and time for Arriving By or Departing At

Time zones

• The desired time zone to be used can be selected from the Select Time Zone dropdown
• This time zone will also be used in the departure_time and arrival_time fields in the results

4. Advanced

The advanced parameters can be used to configure the most granular features of the request.

These are pre-populated with realistic estimates, and so in the majority of cases will not require updating.

• Time needed to board public transport vehicle - the time (in mins) taken to board a train/bus/coach etc.
• Maximum walking time - the maximum time (in mins) allowed for walking from the origin to a station/stop, and from a station/stop to the destination.
• Maximum driving time to station - the maximum time (in mins) allowed for driving from the origin to the station (when using Driving and Train transport type).
• Maximum cycling time to station - the maximum time (in mins) allowed for cycling from the origin to the station (when using Cycling and Public Transport transport type).
• Time required to park a car or bike - the time (in mins) taken to park a car or bike.
• Time required to board a ferry - the time (in mins) taken to board a ferry.

Outputs

This macro returns 2 outputs:

• S output - rows that have successfully generated a route
• F output - rows that have not successfully generated a route, along with the HTTP status, error code, description of the error, and link to where the error codes are documented

When multiple transport methods are selected, multiple routes will be returned.

Successful Output Information

For successful results, the macro will append a number of fields onto the end of the input data. These will differ between the Summarized and Detailed output types selected in the configuration.

Summarized

• Distance - the total journey distance (in metres). NB - distances are not returned for public transport routes
• Travel_time - the total journey time (in seconds)
• Arrival_time / Departure/time - the actual arrival/departure times for the specific route
• Fares - single/weekly/monthly/annual fare costs in GBP (only for routes involving public transport)
• Route - the calculated route (NB - use a Browse tool to view on a map)
• Query details - these fields record the specific parameters used for each query so that they can be easily identified.

Tip - selecting a Record will highlight the corresponding Isochrone on the map, and vice versa

Documentation

Documentation for the API endpoint used by this macro can be found here:

https://docs.traveltime.com/api/reference/routes