Add TomTom comparison (#6)

* Adding TomTom comparison, refactoring code to work with multiple providers

Author: arnasbr

README.md

@@ -1,12 +1,13 @@
 # TravelTime/Google comparison tool
 
-This tool compares the travel times obtained from [TravelTime Routes API](https://docs.traveltime.com/api/reference/routes) 
-and [Google Maps Directions API](https://developers.google.com/maps/documentation/directions/get-directions).
+This tool compares the travel times obtained from [TravelTime Routes API](https://docs.traveltime.com/api/reference/routes),
+[Google Maps Directions API](https://developers.google.com/maps/documentation/directions/get-directions),
+and [TomTom Routing API](https://developer.tomtom.com/routing-api/documentation/tomtom-maps/routing-service).
 Source code is available on [GitHub](https://github.com/traveltime-dev/traveltime-google-comparison).
 
 ## Features
 
-- Get travel times from TravelTime API and Google Maps API in parallel, for provided origin/destination pairs and a set 
+- Get travel times from TravelTime API, Google Maps API and TomTom 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.
@@ -40,6 +41,12 @@ For Google Maps API:
 export GOOGLE_API_KEY=[Your Google Maps API Key]
 ```
 
+For TomTom API:
+
+```bash
+export TOMTOM_API_KEY=[Your TomTom API Key]
+```
+
 For TravelTime API:
 ```bash
 export TRAVELTIME_APP_ID=[Your TravelTime App ID]
@@ -76,7 +83,9 @@ Required arguments:
 
 
 Optional arguments:
-- `--google-max-rpm [int]`: Set max number of parallel requests sent to Google API per minute. Default is 60. 
+- `--google-max-rpm [int]`: Set max number of parallel requests sent to Google API per minute. Default is 60.
+  It is enforced on per-second basis, to avoid bursts.
+- `--tomtom-max-rpm [int]`: Set max number of parallel requests sent to TomTom API per minute. Default is 60.
   It is enforced on per-second basis, to avoid bursts.
 - `--traveltime-max-rpm [int]`: Set max number of parallel requests sent to TravelTime API per minute. Default is 60.
   It is enforced on per-second basis, to avoid bursts.
@@ -106,13 +115,13 @@ The output file will contain the `origin` and `destination` columns from input f
 
 ### Sample output
 ```csv
-origin,destination,departure_time,google_travel_time,tt_travel_time,error_percentage
-"52.1849867903527, 0.1809343829904072","52.202817030086266, 0.10935651695330152",2024-05-28 06:00:00+0100,718.0,1050.0,46
-"52.1849867903527, 0.1809343829904072","52.202817030086266, 0.10935651695330152",2024-05-28 09:00:00+0100,1427.0,1262.0,11
-"52.1849867903527, 0.1809343829904072","52.202817030086266, 0.10935651695330152",2024-05-28 12:00:00+0100,1064.0,1165.0,9
-"52.1849867903527, 0.1809343829904072","52.202817030086266, 0.10935651695330152",2024-05-28 15:00:00+0100,1240.0,1287.0,3
-"52.1849867903527, 0.1809343829904072","52.202817030086266, 0.10935651695330152",2024-05-28 18:00:00+0100,1312.0,1223.0,6
-"52.18553917820687, 0.12702050752253252","52.22715259892737, 0.14811674226050345",2024-05-28 06:00:00+0100,749.0,903.0,20
+origin,destination,departure_time,google_travel_time,tomtom_travel_time,tt_travel_time,error_percentage_google,error_percentage_tomtom
+"50.077012199999984, -5.2234787","50.184134100000726, -5.593753699999999",2024-09-20 07:00:00+0100,2276.0,2388.0,2071.0,9,13
+"50.077012199999984, -5.2234787","50.184134100000726, -5.593753699999999",2024-09-20 10:00:00+0100,2702.0,2578.0,2015.0,25,21
+"50.077012199999984, -5.2234787","50.184134100000726, -5.593753699999999",2024-09-20 13:00:00+0100,2622.0,2585.0,2015.0,23,22
+"50.077012199999984, -5.2234787","50.184134100000726, -5.593753699999999",2024-09-20 16:00:00+0100,2607.0,2596.0,2130.0,18,17
+"50.077012199999984, -5.2234787","50.184134100000726, -5.593753699999999",2024-09-20 19:00:00+0100,2398.0,2431.0,1960.0,18,19
+"50.09814150000003, -5.2586104000000065","50.2165765000003, -5.4758540000000036",2024-09-20 07:00:00+0100,2175.0,2357.0,1861.0,14,21
 ```
 
 ## License

src/traveltime_google_comparison/analysis.py

@@ -1,12 +1,22 @@
 import logging
 from dataclasses import dataclass
+from typing import List
 
 from pandas import DataFrame
 
-from traveltime_google_comparison.collect import Fields, GOOGLE_API, TRAVELTIME_API
+from traveltime_google_comparison.collect import (
+    Fields,
+    TRAVELTIME_API,
+    get_capitalized_provider_name,
+)
 
-ABSOLUTE_ERROR = "absolute_error"
-RELATIVE_ERROR = "error_percentage"
+
+def absolute_error(api_provider: str) -> str:
+    return f"absolute_error_{api_provider}"
+
+
+def relative_error(api_provider: str) -> str:
+    return f"error_percentage_{api_provider}"
 
 
 @dataclass
@@ -15,54 +25,84 @@ class QuantileErrorResult:
     relative_error: int
 
 
-def run_analysis(results: DataFrame, output_file: str, quantile: float):
-    results_with_differences = calculate_differences(results)
-    logging.info(
-        f"Mean relative error: {results_with_differences[RELATIVE_ERROR].mean():.2f}%"
-    )
-    quantile_errors = calculate_quantiles(results_with_differences, quantile)
-    logging.info(
-        f"{int(quantile * 100)}% of TravelTime results differ from Google API "
-        f"by less than {int(quantile_errors.relative_error)}%"
-    )
+def log_results(
+    results_with_differences: DataFrame, quantile: float, api_providers: List[str]
+):
+    for provider in api_providers:
+        capitalized_provider = get_capitalized_provider_name(provider)
+        logging.info(
+            f"Mean relative error compared to {capitalized_provider} "
+            f"API: {results_with_differences[relative_error(provider)].mean():.2f}%"
+        )
+        quantile_errors = calculate_quantiles(
+            results_with_differences, quantile, provider
+        )
+        logging.info(
+            f"{int(quantile * 100)}% of TravelTime results differ from {capitalized_provider} API "
+            f"by less than {int(quantile_errors.relative_error)}%"
+        )
+
+
+def format_results_for_csv(
+    results_with_differences: DataFrame, api_providers: List[str]
+) -> DataFrame:
+    formatted_results = results_with_differences.copy()
+
+    for provider in api_providers:
+        formatted_results = formatted_results.drop(columns=[absolute_error(provider)])
+        relative_error_col = relative_error(provider)
+        formatted_results[relative_error_col] = formatted_results[
+            relative_error_col
+        ].astype(int)
+
+    return formatted_results
+
+
+def run_analysis(
+    results: DataFrame, output_file: str, quantile: float, api_providers: List[str]
+):
+    results_with_differences = calculate_differences(results, api_providers)
+    log_results(results_with_differences, quantile, api_providers)
 
     logging.info(f"Detailed results can be found in {output_file} file")
 
-    results_with_differences = results_with_differences.drop(columns=[ABSOLUTE_ERROR])
-    results_with_differences[RELATIVE_ERROR] = results_with_differences[
-        RELATIVE_ERROR
-    ].astype(int)
+    formatted_results = format_results_for_csv(results_with_differences, api_providers)
 
-    results_with_differences.to_csv(output_file, index=False)
+    formatted_results.to_csv(output_file, index=False)
 
 
-def calculate_differences(results: DataFrame) -> DataFrame:
-    results_with_differences = results.assign(
-        **{
-            ABSOLUTE_ERROR: abs(
-                results[Fields.TRAVEL_TIME[GOOGLE_API]]
-                - results[Fields.TRAVEL_TIME[TRAVELTIME_API]]
-            )
-        }
-    )
+def calculate_differences(results: DataFrame, api_providers: List[str]) -> DataFrame:
+    results_with_differences = results.copy()
+
+    for provider in api_providers:
+        absolute_error_col = absolute_error(provider)
+        relative_error_col = relative_error(provider)
+
+        results_with_differences[absolute_error_col] = abs(
+            results[Fields.TRAVEL_TIME[provider]]
+            - results[Fields.TRAVEL_TIME[TRAVELTIME_API]]
+        )
+
+        results_with_differences[relative_error_col] = (
+            results_with_differences[absolute_error_col]
+            / results_with_differences[Fields.TRAVEL_TIME[provider]]
+            * 100
+        )
 
-    results_with_differences[RELATIVE_ERROR] = (
-        results_with_differences[ABSOLUTE_ERROR]
-        / results_with_differences[Fields.TRAVEL_TIME[GOOGLE_API]]
-        * 100
-    )
     return results_with_differences
 
 
 def calculate_quantiles(
-    results_with_differences: DataFrame, quantile: float
+    results_with_differences: DataFrame,
+    quantile: float,
+    api_provider: str,
 ) -> QuantileErrorResult:
-    quantile_absolute_error = results_with_differences[ABSOLUTE_ERROR].quantile(
-        quantile, "higher"
-    )
-    quantile_relative_error = results_with_differences[RELATIVE_ERROR].quantile(
-        quantile, "higher"
-    )
+    quantile_absolute_error = results_with_differences[
+        absolute_error(api_provider)
+    ].quantile(quantile, "higher")
+    quantile_relative_error = results_with_differences[
+        relative_error(api_provider)
+    ].quantile(quantile, "higher")
     return QuantileErrorResult(
         int(quantile_absolute_error), int(quantile_relative_error)
     )

src/traveltime_google_comparison/collect.py

@@ -14,15 +14,31 @@
 from traveltime_google_comparison.requests.base_handler import BaseRequestHandler
 
 GOOGLE_API = "google"
+TOMTOM_API = "tomtom"
 TRAVELTIME_API = "traveltime"
 
 
+def get_capitalized_provider_name(provider: str) -> str:
+    if provider == "google":
+        return "Google"
+    elif provider == "tomtom":
+        return "TomTom"
+    elif provider == "traveltime":
+        return "TravelTime"
+    else:
+        raise ValueError(f"Unsupported API provider: {provider}")
+
+
 @dataclass
 class Fields:
     ORIGIN = "origin"
     DESTINATION = "destination"
     DEPARTURE_TIME = "departure_time"
-    TRAVEL_TIME = {GOOGLE_API: "google_travel_time", TRAVELTIME_API: "tt_travel_time"}
+    TRAVEL_TIME = {
+        GOOGLE_API: "google_travel_time",
+        TOMTOM_API: "tomtom_travel_time",
+        TRAVELTIME_API: "tt_travel_time",
+    }
 
 
 logger = logging.getLogger(__name__)
@@ -100,7 +116,7 @@ def generate_tasks(
 
 
 async def collect_travel_times(
-    args, data, request_handlers: Dict[str, BaseRequestHandler]
+    args, data, request_handlers: Dict[str, BaseRequestHandler], providers: List[str]
 ) -> DataFrame:
     timezone = pytz.timezone(args.time_zone_id)
     localized_start_datetime = localize_datetime(args.date, args.start_time, timezone)
@@ -111,7 +127,12 @@ async def collect_travel_times(
 
     tasks = generate_tasks(data, time_instants, request_handlers, mode=Mode.DRIVING)
 
-    logger.info(f"Sending {len(tasks)} requests to Google and TravelTime APIs")
+    capitalized_providers_str = ", ".join(
+        [get_capitalized_provider_name(provider) for provider in providers]
+    )
+    logger.info(
+        f"Sending {len(tasks)} requests to {capitalized_providers_str} and TravelTime APIs"
+    )
 
     results = await asyncio.gather(*tasks)
 
@@ -121,6 +142,7 @@ async def collect_travel_times(
     ).agg(
         {
             Fields.TRAVEL_TIME[GOOGLE_API]: "first",
+            Fields.TRAVEL_TIME[TOMTOM_API]: "first",
             Fields.TRAVEL_TIME[TRAVELTIME_API]: "first",
         }
     )

src/traveltime_google_comparison/config.py

@@ -9,9 +9,11 @@
 )
 
 DEFAULT_GOOGLE_RPM = 60
+DEFAULT_TOMTOM_RPM = 60
 DEFAULT_TRAVELTIME_RPM = 60
 
 GOOGLE_API_KEY_VAR_NAME = "GOOGLE_API_KEY"
+TOMTOM_API_KEY_VAR_NAME = "TOMTOM_API_KEY"
 TRAVELTIME_APP_ID_VAR_NAME = "TRAVELTIME_APP_ID"
 TRAVELTIME_API_KEY_VAR_NAME = "TRAVELTIME_API_KEY"
 
@@ -48,13 +50,21 @@ def parse_args():
         default=DEFAULT_GOOGLE_RPM,
         help="Maximum number of requests sent to Google API per minute",
     )
+    parser.add_argument(
+        "--tomtom-max-rpm",
+        required=False,
+        type=int,
+        default=DEFAULT_TOMTOM_RPM,
+        help="Maximum number of requests sent to TomTom API per minute",
+    )
     parser.add_argument(
         "--traveltime-max-rpm",
         required=False,
         type=int,
         default=DEFAULT_TRAVELTIME_RPM,
         help="Maximum number of requests sent to TravelTime API per minute",
     )
+
     parser.add_argument(
         "--skip-data-gathering",
         action=argparse.BooleanOptionalAction,
@@ -74,6 +84,14 @@ def retrieve_google_api_key():
     return google_api_key
 
 
+def retrieve_tomtom_api_key():
+    tomtom_api_key = os.environ.get(TOMTOM_API_KEY_VAR_NAME)
+
+    if not tomtom_api_key:
+        raise ValueError(f"{TOMTOM_API_KEY_VAR_NAME} not set in environment variables.")
+    return tomtom_api_key
+
+
 def retrieve_traveltime_credentials() -> TravelTimeCredentials:
     app_id = os.environ.get(TRAVELTIME_APP_ID_VAR_NAME)
     api_key = os.environ.get(TRAVELTIME_API_KEY_VAR_NAME)

src/traveltime_google_comparison/main.py

@@ -6,7 +6,12 @@
 from traveltime_google_comparison import collect
 from traveltime_google_comparison import config
 from traveltime_google_comparison.analysis import run_analysis
-from traveltime_google_comparison.collect import Fields, GOOGLE_API, TRAVELTIME_API
+from traveltime_google_comparison.collect import (
+    Fields,
+    GOOGLE_API,
+    TRAVELTIME_API,
+    TOMTOM_API,
+)
 from traveltime_google_comparison.requests import factory
 
 logging.basicConfig(
@@ -19,6 +24,7 @@
 
 
 async def run():
+    providers = [GOOGLE_API, TOMTOM_API]
     args = config.parse_args()
     csv = pd.read_csv(
         args.input, usecols=[Fields.ORIGIN, Fields.DESTINATION]
@@ -29,7 +35,7 @@ async def run():
         return
 
     request_handlers = factory.initialize_request_handlers(
-        args.google_max_rpm, args.traveltime_max_rpm
+        args.google_max_rpm, args.tomtom_max_rpm, args.traveltime_max_rpm
     )
     if args.skip_data_gathering:
         travel_times_df = pd.read_csv(
@@ -39,15 +45,17 @@ async def run():
                 Fields.DESTINATION,
                 Fields.DEPARTURE_TIME,
                 Fields.TRAVEL_TIME[GOOGLE_API],
+                Fields.TRAVEL_TIME[TOMTOM_API],
                 Fields.TRAVEL_TIME[TRAVELTIME_API],
             ],
         )
     else:
         travel_times_df = await collect.collect_travel_times(
-            args, csv, request_handlers
+            args, csv, request_handlers, providers
         )
     filtered_travel_times_df = travel_times_df.loc[
         travel_times_df[Fields.TRAVEL_TIME[GOOGLE_API]].notna()
+        & travel_times_df[Fields.TRAVEL_TIME[TOMTOM_API]].notna()
         & travel_times_df[Fields.TRAVEL_TIME[TRAVELTIME_API]].notna(),
         :,
     ]
@@ -62,7 +70,7 @@ async def run():
             logger.info(
                 f"Skipped {skipped_rows} rows ({100 * skipped_rows / all_rows:.2f}%)"
             )
-        run_analysis(filtered_travel_times_df, args.output, 0.90)
+        run_analysis(filtered_travel_times_df, args.output, 0.90, providers)
 
 
 def main():