traveltime-drive-time-comparisons

TravelTime Drive Time Comparisons tool

This tool compares the travel times obtained from TravelTime Routes API, Google Maps Directions API, TomTom Routing API, HERE Routing API, Mapbox Directions API, OpenRoutes API, OSRM Routes API, and Valhalla Routes API. Source code is available on GitHub.

Features

• Get travel times from TravelTime API, Google Maps API, TomTom API, HERE API, Mapbox API, OSRM API and Valhalla API in parallel, for provided origin/destination pairs and a set of departure times.
• Departure times are calculated based on user provided start time, end time and interval.
• Analyze the differences between the results and print out the average error percentage.

Prerequisites

The tool requires Python 3.8+ installed on your system. You can download it from here.

Installation

Create a new virtual environment with a chosen name (here, we'll name it 'env'):

python -m venv env

Activate the virtual environment:

source env/bin/activate

Install the project and its dependencies:

pip install traveltime-drive-time-comparisons

Setup

Provide credentials and desired max requests per minute for the APIs inside the config.json file. You can also disable unwanted APIs by changing the enabled value to false.

{
  "traveltime": {
    "app-id": "<your-app-id>",
    "api-key": "<your-api-key>",
    "max-rpm": "60"
  },
  "api-providers": [
    {
      "name": "google",
      "enabled": true,
      "api-key": "<your-api-key>",
      "max-rpm": "60"
    },
    ...other providers
  ]
}

Usage

Run the tool:

traveltime_drive_time_comparisons --input [Input CSV file path] --output [Output CSV file path] \
    --date [Date (YYYY-MM-DD)] --start-time [Start time (HH:MM)] --end-time [End time (HH:MM)] \
    --interval [Interval in minutes] --time-zone-id [Time zone ID] 

Required arguments:

• --input [Input CSV file path]: Path to the input file. Input file is required to have a header row and at least one row with data, with two columns: origin and destination. The values in the columns must be latitude and longitude pairs, separated by comma and enclosed in double quotes. For example: "51.5074,-0.1278". Columns must be separated by comma as well. Check out the project's repository for examples in the examples directory and more pre-prepared routes in the inputs directory.
• --output [Output CSV file path]: Path to the output file. It will contain the gathered travel times. See the details in the Output section
• --date [Date (YYYY-MM-DD)]: date on which the travel times are gathered. Use a future date, as Google API returns errors for past dates (and times). Take into account the time needed to collect the data for provided input.
• --start-time [Start time (HH:MM)]: start time in HH:MM format, used for calculation of departure times. See Calculating departure times
• --end-time [End time (HH:MM)]: end time in HH:MM format, used for calculation of departure times. See Calculating departure times
• --interval [Interval in minutes]: interval in minutes, used for calculation of departure times. See Calculating departure times
• --time-zone-id [Time zone ID]: non-abbreviated time zone identifier in which the time values are specified. For example: Europe/London. For more information, see here.

Optional arguments:

• --config [Config file path]: Path to the config file. Default - ./config.json

Example:

traveltime_drive_time_comparisons --input examples/uk.csv --output output.csv --date 2023-09-20 \
    --start-time 07:00 --end-time 20:00 --interval 180 --time-zone-id "Europe/London"

Calculating departure times

Script will collect travel times on the given day for departure times between provided start-time and end-time, with the given interval. The start-time and end-time are in principle inclusive, however if the time window is not exactly divisible by the given interval, the end-time will not be included. For example, if you set the start-time to 08:00, end-time to 20:00 and interval to 240, the script will sample both APIs for departure times 08:00, 12:00, 16:00 and 20:00 (end-time included). But for interval equal to 300, the script will sample APIs for departure times 08:00, 13:00 and 18:00 (end-time is not included).

Output

The output file will contain the origin and destination columns from input file, with some additional columns:

• departure_time: departure time in YYYY-MM-DD HH:MM:SS±HHMM format, calculated from the start-time, end-time and interval. It includes date, time and timezone offset.
• *_travel_time: travel time gathered from alternative provider API in seconds
• tt_travel_time: travel time gathered from TravelTime API in seconds
• error_percentage_*: relative error between provider and TravelTime travel times in percent, relative to provider result.

Sample output

origin,destination,departure_time,google_travel_time,tomtom_travel_time,here_travel_time,osrm_travel_time,openroutes_travel_time,mapbox_travel_time,tt_travel_time,error_percentage_google,error_percentage_tomtom,error_percentage_here,error_percentage_mapbox,error_percentage_osrm,error_percentage_openroutes
"52.200400622501455, 0.1082577055247136","52.21614536733819, 0.15782831362961777",2024-09-25 07:00:00+0100,621.0,805.0,614.0,532.0,697.0,1018.0,956.0,53,18,55,6,79,37

License

This project is licensed under MIT License. For more details, see the LICENSE file.