Overview

This page explains some of the general concepts and parameters that apply to various services of the API.

In each case, it lists the relevant endpoints.

More details for specific parameters (such as default values) can be found in each individual endpoint reference page.

Key Concepts

Search Types

Arrival vs Departure Searches

All of the regular travel time endpoints (i.e those that don’t have /fast in the URL) support both arrival and departure searches. This choice reflects the desired direction of travel, in the following ways:

Isochrones (/time-map), Isodistances (/distance-map), H3 (/h3), Geohashes (/geohash)

A departure search calculates the reachable area, departing from the search location at the chosen departure time.

An arrival search calculates the area from which journeys can begin, arriving at the search location at the chosen arrival time.

Matrices (/time-filter)

A departure search is a one-to-many search, calculating journeys that depart from the single departure location at the departure time, travelling towards the (max 2,000) arrival locations.

An arrival search is a many-to-one search, calculating journeys that depart from the (max 2,000) departure locations, travelling towards the single arrival location.

Routes (/routes)

A departure search is a one-to-one search, calculating the journey that departs from the departure location at the departure time.

An arrival search is a one-to-one search, calculating the journey that arrives at the arrival location at the arrival time.

One-to-many vs Many-to-one Searches

All of the Fast endpoints (i.e those that have /fast in the URL) support both one-to-many and many-to-one searches. This choice reflects the desired direction of travel, in the following ways:

Isochrones (/time-map/fast), H3 (/h3/fast), Geohashes (/geohash/fast)

A one-to-many search calculates the reachable area, for journeys departing from the search location.

An many-to-one search calculates the reachable area, for journeys arriving at the search location.

Matrices (/time-filter/fast)

A one-to-many search calculates journeys that depart from the single departure location, travelling towards the (max 100,000) arrival locations.

A many-to-one search calculates journeys that depart from the (max 100,000) departure locations, travelling towards the single arrival location.

Fast vs Regular APIs

Most of the core services (Isochrones, Matrices, H3, and Geohashes) come in two different versions, supported by different endpoints.

Regular Endpoints

These endpoints provide the most configurable parameters, including the ability to select a specific arrival or departure time, and configure detailed public transport parameters such as the maximum walking time.

They are available in all of the Supported Countries.

They have lower performance than the Fast endpoints.

The /time-filter endpoint supports fewer locations per request than the Fast endpoint (2,000 vs 100,000).

Fast Endpoints

These endpoints provide the best performance and scale, but with fewer configurable parameters. For example, it isn’t possible to select a specific arrival or departure time.

They are available in all of the Fast Supported Countries.

The /time-filter/fast endpoint supports more locations per request than the regular endpoint (100,000 vs 2,000).

Public Transport

The following concepts apply specifically to the public transport modes (e.g public_transport, bus, train, etc.).

These models use actual public transport timetables as the basis for the calculations.

Arrival / Departure Time

Our public transport models use actual public transport timetables, and so the arrival or departure time determines exactly what journeys are possible based on the services available at that time and day.

(For details of how the arrival or departure time impacts driving journeys, see Traffic Model).

We typically support timetables in a window of two weeks either side of the current date. So on the 1st June 2025, for example, you can use an arrival or departure time from 18th May 2025 - 15th June 2025.

Range

The range parameter can be used to add a window of time onto the chosen arrival or departure time. With range enabled, instead of optimising solely based on the specific departure/arrival time, the model will look for any journeys that depart or arrive within the window.

For a departure search, the range window is applied after the departure time. For an arrival search, the range window is applied before the arrival time.

The parameter is available in all the regular endpoints (i.e those that don’t have /fast in the URL).

For the best results, we recommend typically using a range value of between 1800s (30 minutes) and 3600s (1 hour).

Isochrones (/time-map), H3 (/h3), Geohashes (/geohash)

With range enabled, a combined shape is returned, of all possible journeys that arrive/depart within the window.

Walking Time

The walking_time parameter can be used to control the maximum time allowed for walking at both the start and end of a public transport journey, i.e:

• The maximum walking time from the departure location to the first stop/station and;
• The maximum walking time from the final stop/station to the arrival location

These limits are independent and not cumulative. They only apply to the first and last walking legs of the journey - all walking times between public transport legs are limited to 600s (10 minutes) each.

The parameter is available in all the regular endpoints (i.e those that don’t have /fast in the URL).

For the best results, we recommend typically using a walking_time value of between 900s (15 minutes) and 1800s (30 minutes).

Driving

The following concepts apply specifically to the driving mode.

Our driving models are built from the ground up. They do not incorporate live traffic, but instead use historic traffic and other data sources to predict accurate drive times.

The models perform extremely well when benchmarked against other leading drive time providers. We have built a benchmarking tool which you can use to run your own benchmarks.

Traffic Model

In our core territories, we support a sophisticated traffic model. In the remaining countries, we support a more simple traffic model.

Note - when selecting an arrival or departure time for driving requests, it is only the time that matters (and not the date). The times are used by the models to reflect a midweek day based on the latest data. Selecting a weekend day, or a day in the past or future, will have no impact on the results.

Sophisticated Traffic Model

This model uses historic traffic data to accurately model different region-specific congestion windows throughout the day, and the level of congestion to apply during each window, based on the selected arrival or departure time. For example:

Congestion factors can be manipulated further using the Traffic Model parameter. This takes values of “pessimistic”, “balanced”, or “optimistic”, and can be used to further increase/decrease congestion levels.

The parameter has a bigger impact when congestion levels are higher, such as:

• Major urban areas
• Peak times of the day

Conversely, the parameter will have very little (or no) impact when congestion levels are low.

Simple Traffic Model

This model applies a standard congestion factor across all urban areas during fixed peak time windows. Peak time windows are 07:00-10:00 and 16:00-19:00.

Snapping Behaviour

The snapping parameters control the behaviour of journeys that start and/or end away from the road network. ‘snapping’ is the name given to the process of getting between the departure/arrival location and the nearest point on the road network.

Snapping Penalty

This parameter determines whether the time and distance involved in snapping to the road network is included in the total travel time and distance for the journey.

With the parameter enabled, the time it takes to walk to/from the nearest point on the road network is included.

With the parameter disabled, this walking time is excluded, and journeys effectively start and end at the nearest point on the road network.

Accept Roads

This parameter controls what road types are permitted for a journey to start and end on.

By default, journeys are not permitted to start and end on roads where walking is not permitted (e.g motorways) but this parameter can be used to override this and allow journeys to start and end on all roads.

Isochrones

Islands and Holes

For any of the endpoints which return a form of catchment area (in the form of an isochrone, or an isodistance, or reachable H3 cells / geohashes), it is possible for the catchment area to consist of multiple disconnected regions, or ‘islands’. Similarly, it is possible to include ‘holes’ which are unreachable areas entirely surrounded by reachable areas.

In the case of public transport, islands are likely to occur around train stations - the area surrounding the station will be reachable, but the connecting area between stations may not be as you can‘t get off the train between stops.

For driving, the same thing can happen where the gap between junctions on a motorway may be unreachable because it is not possible to stop or get off the road at that point. By default we don‘t allow driving journeys to end on a road where you can‘t stop and continue by walking. (This behaviour can be configured using the accept_roads snapping parameter.)

Polygon Filter

For the endpoints that explicitly return a polygon (/time-map, /distance-map, /time-map/fast), the polygon filter parameter can be used to limit the number of polygons returned.

Note - this does not combine disconnected polygons into one, but simply returns the largest X polygons by area.

For other ways to connect disconnected driving islands into one shape, see Render Mode.

No Holes

For the endpoints that explicitly return a polygon (/time-map, /distance-map, /time-map/fast), the no holes parameter can be used to fill in any areas of the polygon that are unreachable but surrounded entirely by reachable areas. This can be used to simplify the geometry of the shape to make it easier to process.

Controlling the level of detail for polygons

For the endpoints that explicitly return a polygon (/time-map, /distance-map, /time-map/fast), the level of detail parameter can be used to determine how granular the outline of the shape is.

The higher the level, the finer the grid used to trace the outline of the shape.

Note - higher levels of detail come with larger response sizes due to the increased number of points, so there may be a performance impact.

We would recommend generally using the Medium level.

Generating simplified polygons

The isochrone endpoints (/time-map and /time-map/fast) come with two different ways to represent the reachable area, controlled by the render_mode parameter.

approximate_time_filter

This mode represents the most accurate way of generating the polygon. For example, roads that are traversed but can’t be stopped on (e.g motorways) won’t be included in the reachable area.

road_buffering

This mode represents a more approximate reachable area, where all roads traversed as part of the search are covered in what looks like a wide brush stroke. This can be useful when looking to ‘attach’ any disconnected islands in a driving polygon together.