An isochrone is a shape on a map that shows everywhere you can reach from a starting point within a set travel time or distance, given a mode of travel. Also called a travel time map, isoline, or reachable range, an isochrone follows the road, path, or transit network, so the shape reflects how people actually move, not just how far a straight line goes. The Stadia Maps Isochrone API returns them as GeoJSON polygons or linestrings for driving, walking, cycling, and nearly a dozen other travel modes.

Key Takeaways

  • An isochrone shows everywhere reachable from a starting point within a set travel time or distance, based on the real road, path, or transit network.
  • Unlike a fixed-radius buffer, an isochrone accounts for road geometry, one-way streets, mode of travel, and (optionally) real-time traffic.
  • The Stadia Maps Isochrone API supports nearly a dozen travel modes, including driving, walking, cycling, bus, taxi, and truck.
  • Output is a GeoJSON FeatureCollection that renders directly in MapLibre GL JS, Leaflet, or any GeoJSON-aware map library.
  • Isochrones are the right tool for site selection, service-area planning, and accessibility analysis. They are not a substitute for routing (single ETA) or matrix (ranked distances).

Why Not Just Use a Radius for Isochrones?

A fixed-radius buffer is fast, but for most real questions, it is wrong. A 10-minute drive out of downtown San Francisco covers a different area than a 10-minute drive out of suburban Phoenix. Highways, one-way streets, rivers with no bridges, transit availability, and pedestrian-only zones all bend the shape.

Cases where a radius breaks:

  • Rivers and rail corridors. A bridge or tunnel can be the only crossing for kilometers. A circle ignores that.
  • One-way networks. Driving out of a dense center is often slower than driving in. The reachable area is asymmetric.
  • Mode mismatch. A 15-minute walking radius reaches almost nothing on a road network built for cars, not people.
  • Time of day. A drive-time isochrone at 04:00 is much larger than the same isochrone at 17:30 when accounting for traffic.

If your product or application is making decisions based on who can reach a point quickly, then a radius is a meaningful penalty for accuracy. That is what the Stadia Maps Isochrone API is designed to fix.

How Isochrones Are Calculated

Isochrone engines work in roughly the same way:

  1. Take the road, path, and transit network as a graph.
  2. Assign a travel cost to every edge based on speed, mode, and any time-of-day model.
  3. Run a search outward from the origin, expanding by accumulated cost rather than distance.
  4. When the search hits each time or distance threshold, capture the reachable subgraph.
  5. Turn that subgraph into a polygon or linestring by buffering reachable edges and dissolving the result.

Stadia Maps runs isochrones on Valhalla, an open-source routing engine that Stadia Maps contributes to. Valhalla uses a tiled, multimodal graph and supports per-mode costing models, which is why the same endpoint can produce a useful pedestrian, bicycle, or automobile isochrone without swapping engines. For more on how the Stadia Maps routing stack fits together, see the Routing overview.

Isochrone Parameters That Matter

The Stadia Maps Isochrone API exposes the parameters that actually change the shape.

  • locations: The starting point (latitude and longitude). Required.
  • costing: The travel mode. Options include auto, bicycle, pedestrian, bus, taxi, and truck, among others. The full list is in the API reference.
  • contours: One or more time or distance thresholds. Each contour can carry a color that is echoed back in the response for direct rendering.
  • polygons: Set to true for filled polygons or false for linestrings. Use linestrings for accessibility plots or overlay layers.
  • date_time: For traffic-influenced modes, the departure or arrival time. Skipping this defaults to average conditions.

Two more that are less obvious but matter in production:

  • denoise: Removes small disconnected fragments below a relative size threshold. Lower it if you need to see remote islands of reachability.
  • generalize: Simplification tolerance in meters. Lower numbers produce more detailed shapes and larger payloads.

How Traffic Changes an Isochrone

For automobile, bus, taxi, and truck modes, the Stadia Maps Isochrone API supports traffic-influenced profiles via the _traffic and _traffic_premium suffixes. auto_traffic and truck_traffic_premium are two examples.

Traffic-influenced isochrones combine live conditions with historical data, so a rush-hour isochrone is typically smaller than the same isochrone at 03:00. If your product uses isochrones for logistics, dispatch, or delivery-zone decisions, a static-speed isochrone will overstate reachability during peak hours.

Traffic-influenced routing requires a Standard plan or higher. See the pricing page for plan details.

How Do You Generate an Isochrone?

Here is what a request to the Stadia Maps Isochrone API looks like. This example asks for a 5-minute pedestrian isochrone from a point in Tallinn, Estonia.

POST https://api.stadiamaps.com/isochrone/v1
Content-Type: application/json

{
  "locations": [{"lat": 59.436884, "lon": 24.742595}],
  "costing": "pedestrian",
  "contours": [{"time": 5, "color": "aabbcc"}],
  "polygons": true
}

The response is a GeoJSON FeatureCollection with one feature per contour. It renders directly in MapLibre GL JS, Leaflet, or any GeoJSON-aware renderer.

For runnable code in TypeScript, Python, Kotlin, Swift, PHP, or cURL, see the Stadia Maps Isochrone API docs. A step-by-step MapLibre GL JS walkthrough is in the Display Isochrones on a Map tutorial.

Where Isochrones Fall Short

Isochrones are not always the right tool. Beyond the parameter details in the Isochrones documentation, here are the practical patterns worth knowing:

  • Very small time bands are noisy. A 1-minute isochrone is mostly buffer around the origin. For travel times below a few minutes, results depend heavily on off-road buffering rather than on real network travel, so use very short contours with caution.
  • Static isochrones do not reflect traffic. Without a date_time parameter, automobile isochrones can dramatically overstate reachability at rush hour or understate it at night.
  • Cross-provider comparisons rarely agree. Two providers will produce different polygons for the same origin because they use different graphs, different speed models, and different generalization settings. Standardize on a single provider for consistency across your product.
  • Isochrones describe geographic reachability, not service areas. Delivery zones, minimum-order distances, and exclusion rules are business logic that should sit on top of the isochrone, not inside it.

Isochrone vs. Matrix vs. Routing: Which Do You Need?

The Stadia Maps Routing API family includes several related endpoints. Pick the right one:

  • For a single point-to-point travel time or ETA, use standard routing. It is cheaper and more precise than an isochrone.
  • For "which of these N destinations is closest by drive time," use the Time/Distance Matrix API. Isochrones describe an area, not a ranking.
  • For service-area billing logic, compute the isochrone once, store the polygon, and query against it. Recomputing on every request wastes API credits.

Common Isochrone Use Cases

Isochrones answer questions where a "how far in time" constraint matters more than a "how far in miles" constraint. The Stadia Maps Isochrones product page frames it as "reachable range decision-making" and lists example questions this API commonly answers:

  • Site selection. Retail, healthcare, and logistics teams compare reachable population, demographics, or competitor density inside a drive-time band. A 20-minute isochrone is a better proxy for catchment than a 10-mile radius.
  • Accessibility and mobility analysis. Walking or transit isochrones show real access to schools, clinics, or grocery stores, not just distance.
  • EV and fuel planning. A driving isochrone with a distance constraint answers "what is reachable in the last 20 miles before I need to charge or refuel?"
  • Marketplace coverage. When a merchant joins a delivery platform, an isochrone defines the visible service area.
  • Real estate search. Filtering listings by "30 minutes from my office by transit" is an isochrone query against a property index.

Frequently Asked Questions

What is an isochrone map?

An isochrone map displays one or more isochrone shapes, each connecting all points reachable within a set travel time or distance from a common starting point. Isochrone maps are used for site selection, accessibility analysis, service-area planning, and mobility studies.

What is the difference between an isochrone and an isodistance?

Isochrones measure reachability in units of time; isodistances measure reachability in units of distance. The Stadia Maps Isochrone API can be used to produce either by setting a time or distance value on each contour in the request.

What travel modes does the Stadia Maps Isochrone API support?

The Stadia Maps Isochrone API supports nearly a dozen travel modes, including auto, bicycle, pedestrian, bus, taxi, and truck. Traffic-influenced variants exist for auto, bus, taxi, and truck. The full list is in the API reference.

Do isochrones account for traffic?

They can. The Stadia Maps Isochrone API offers traffic-influenced profiles via _traffic and _traffic_premium suffixes on supported costing models. A traffic-influenced isochrone with an explicit date_time reflects live conditions and historical patterns; a static isochrone assumes average speeds. Traffic-influenced routing requires a Standard plan or higher.

How is an isochrone request billed on Stadia Maps?

Isochrone requests are billed as routing requests on the Stadia Maps API credit system. Contour count does not multiply the cost; a single request with three contours is a single billable request.

Where to Go Next

From the Blog

More on isochrones and adjacent routing topics:

Routing & Navigation