Travel Time Matrix (Distance Matrix)

Overview

This macro can be used to create a matrix of travel times between multiple origins and multiple destinations, as well as a matrix of distances or fares where applicable.

Learn more about our distance matrix service

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

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 zone

• The desired time zone to be used can be selected from the Select Time Zone dropdown

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 journey
• F output - rows that have not successfully generated a journey, along with the HTTP status, error code, description of the error, and link to where the error codes are documented

Successful Output Information

For successful results, the macro will append a number of fields onto the end of the input data:

• Metric – the metric represented by the corresponding Value field:
  • distance
  • travel_time
  • Fare single (GBP)
  • Fare week (GBP)
  • Fare month (GBP)
  • Fare year (GBP)
• Value – the value of the corresponding Metric field
• Query details - these fields record the specific parameters used for each query so that they can be easily identified.

In order to create a matrix view of the output data:

1. Run the Filter tool to isolate one Metric – e.g “Metric = travel_time”
2. Run the Cross Tab tool with the following configuration:
   • Group data by these values = Origin Name
   • Change column headers = Destination Name
   • Values for new columns = Value
   • Method for aggregating values = Sum

Documentation

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

https://docs.traveltime.com/api/reference/travel-time-distance-matrix