Migration Guide: HERE Matrix Routing API to TravelTime Time Filter Fast API

1. Introduction

This guide is aimed at helping a migration from HERE’s Matrix Routing API v8, to the Travel Time Matrix (Fast) endpoint.

Why migrate to TravelTime?

Larger matrices (up to 10 x 100,000)
Support for fully multi-modal public transit
Exceptional performance, even for large requests
Fixed cost and unlimited usage, instead of transactional pricing
Permissive caching policy

2. Features Comparison

The table below covers the main features of the two services.

Feature	HERE API	TravelTime API
Maximum Matrix Size	15 x 100 OR 100 x 1 OR 500 x 500 OR 1 x 2000 (depending on parameters, for synchronous requests)	10 x 100,000
Sync / Async	Both	Synchronous
Transport Modes	Car, Pedestrian, Truck, Scooter	Car, Pedestrian, Bicycle, Public Transit
Calculated Properties	Travel time, Distance	Travel time, Distance
Time of Day Configuration	Yes (for some parameter combinations)	Peak and Off Peak options
Pricing	Usage based	Fixed price, unlimited usage
Endpoint Playground	N/A	playground.traveltime.com/travel-time-distance-matrix-fast
Support	Paid	Included in all licences
Caching	Restricted	Permitted

3. Request Comparison

The sections below cover the main details of the API requests for each service, including endpoint details, authentication, and request structure.

A side-by-side comparison is provided to show how the same 2x2 matrix can be generated using each service.

Endpoint

Feature	HERE API	TravelTime API
Base URL	`matrix.router.hereapi.com/v8/matrix`	`api.traveltimeapp.com/v4/time-filter/fast`
API Version	Included in URL path (`/v8`)	Included in URL path (`/v4`)
Request Type	POST	POST*

*TravelTime API supports GET requests through the Travel Time Matrix endpoint

Authentication

Feature	HERE API	TravelTime API
Authentication Method	`apiKey` in query string OR Bearer token (JWT)	`X-Application-Id` and `X-Api-Key` headers
Required Headers	`Content-Type: application/json`	`Content-Type: application/json` `X-Application-Id: {Your_App_ID}` `X-Api-Key: {Your_API_Key}`

Request Structure

Both the HERE API and the TravelTime API use POST requests for generating matrices, with the parameters included in the request body.

Feature	HERE API	TravelTime API
Search Structure	`origins` and `destinations` arrays	Individual `one-to-many` or `many-to-one` searches grouped in one request
Location Format	Waypoint objects containing `lat` and `lng` doubles	`locations` array with IDs and `coords` objects, containing `lat` and `lng` floats
Configuration	Via parameters within the request body	Via parameters within the request body, which can differ between searches
Transport Type	`transportMode=` `car /` `truck /` `pedestrian /` `taxi /` `scooter`	`transportation: { type:` `driving+ferry /` `cycling+ferry /` `walking+ferry /` `public_transport` `}`
Time of Day Configuration	`departureTime=2025-01-01` `T00:00:00:000Z`	`arrival_time_period: weekday_morning`
Result Properties	Requested via `matrixAttributes` array	Requested via `properties` array

Request Examples

The examples below both show how to generate the drive times and distances between two origins and two destinations in the UK with a cURL request.

HERE API Request:

curl -X POST
 "https://matrix.router.hereapi.com/v8/matrix?async=false&apiKey={Your_API_Key}" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": [
        { "lat": 51.532131, "lng": -0.293897 },
        { "lat": 51.871461, "lng": -0.435683 }
    ],
    "destinations": [
        { "lat": 51.749232, "lng": -1.258321 },
        { "lat": 50.899630, "lng": -1.011401 }
    ],
    "regionDefinition": {
        "type": "world"
    },
    "transportMode": "car",
    "matrixAttributes": [
        "travelTimes",
        "distances"
    ]
}'

TravelTime API Request:

curl -X POST "https://api.traveltimeapp.com/v4/time-filter/fast" \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: {YOUR_APP_ID}" \
  -H "X-Api-Key: {YOUR_APP_KEY}" \
  -d '{
  "locations": [
    {
      "id": "Origin 1",
      "coords": {
        "lat": 51.532131,
        "lng": -0.293897
      }
    },
    {
      "id": "Origin 2",
      "coords": {
        "lat": 51.871461,
        "lng": -0.435683
      }
    },
    {
      "id": "Destination 1",
      "coords": {
        "lat": 51.749232,
        "lng": -1.258321
      }
    },
    {
      "id": "Destination 2",
      "coords": {
        "lat": 50.899630,
        "lng": -1.011401
      }
    }
  ],
  "arrival_searches": {
    "one_to_many": [
      {
        "id": "Origin 1",
        "departure_location_id": "Origin 1",
        "arrival_location_ids": [
          "Destination 1",
          "Destination 2"
        ],
        "travel_time": 10800,
        "arrival_time_period": "weekday_morning",
        "properties": [
          "travel_time",
          "distance"
        ],
        "transportation": {
          "type": "driving"
        }
      },
      {
        "id": "Origin 2",
        "departure_location_id": "Origin 2",
        "arrival_location_ids": [
          "Destination 1",
          "Destination 2"
        ],
        "travel_time": 10800,
        "arrival_time_period": "weekday_morning",
        "properties": [
          "travel_time",
          "distance"
        ],
        "transportation": {
          "type": "driving"
        }
      }
    ]
  }
}

4. Response Comparison

The sections below cover the main details of the API response for each service.

A side-by-side comparison is provided to show how the same 2x2 matrix is returned using each service.

Structure Differences

Feature	HERE API	TravelTime API
Matrix Format	Flat arrays (`travelTimes`, `distances`) aligned to origin-destination index	Travel times and distances structured as a list of results per origin (`search_id`)
Unsuccessful Results	Represented via `errorCodes` array	Listed in `unreachable` arrays (one per search)
Entry Identification	Implicit through index of `origins` and `destinations`	Explicit through string IDs (`search_id`, `id`)
Distance Unit	`Metres`	`Metres`
Travel Time Unit	`Seconds`	`Seconds`

Response Examples

The response examples below both show the drive times between two origins and two destinations in the UK.

HERE API Response:

{
   "matrixId": "0d2e4640-03b1-430f-b9f7-14927ae8b4f2",
   "matrix": {
       "numOrigins": 2,
       "numDestinations": 2,
       "travelTimes": [
           11126,
           6966,
           11899,
           7657
       ],
       "distances": [
           150746,
           115821,
           176913,
           143647
       ]
   },
   "regionDefinition": {
       "type": "world"
   }
}

TravelTime API Response:

{
  "results": [
      {
          "search_id": "Origin 1",
          "locations": [
              {
                  "id": "Destination 1",
                  "properties": {
                      "travel_time": 4123,
                      "distance": 81870
                  }
              },
              {
                  "id": "Destination 2",
                  "properties": {
                      "travel_time": 5278,
                      "distance": 109859
                  }
              }
          ],
          "unreachable": []
      },
      {
          "search_id": "Origin 2",
          "locations": [
              {
                  "id": "Destination 1",
                  "properties": {
                      "travel_time": 4932,
                      "distance": 108815
                  }
              },
              {
                  "id": "Destination 2",
                  "properties": {
                      "travel_time": 6107,
                      "distance": 143597
                  }
              }
          ],
          "unreachable": []
      }
  ]
}

5. Error Handling

Both the TravelTIme API and the HERE API use standard http status codes, such as 401 Unauthorized and 500 Internal Server Error.

The table below details the main differences in the structures of the error response for each service.

Feature	HERE API	TravelTime API
Structude	Flat (no nesting)	Nested `additional_info`
HTTP Status Code	Included in JSON body	Included in JSON body
Root Elements	`title` `status` `code` `cause` `action` `correlationID`	`http_status` `error_code` `description` `documentation_link` `additional_info`

Error Message Examples

The response examples below show the error response for an invalid query, with http error code 400.

HERE API Response:

{
   "title": "invalid HTTP request",
   "status": 400,
   "code": "E601101",
   "cause": "invalid JSON: key must be a string at line 12 column 7",
   "action": "Check that the request body is in valid JSON format.",
   "correlationId": "02ba60db-3007-4291-950a-c7de8be12e40"
}

TravelTime API Response:

{
  "http_status": 400,
  "error_code": 3,
  "description": "Failed to parse json - syntax error",
  "documentation_link": "https://docs.traveltime.com/reference/error-codes",
  "additional_info": {
      "syntax_errors": [
          "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries"
      ]
  }
}

6. Next Steps

If you are looking to migrate from using the HERE Matrix Routing API to TravelTime, you’ll need to first sign up for an API key.

To help you get up and running, check out some of the links to more resources below.

Endpoint Reference Endpoint Playground SDKs Postman Collection