Skip to main content

Isochrones API

Last updated: October 5, 2026 | 5 minutes read

Current version: 1.0.3 | View Release Notes

The Isochrones API is a sophisticated geospatial analysis service that calculates and visualizes reachable areas from any given location based on travel time, distance, or battery consumption constraints. This powerful tool enables you to answer critical questions like "What areas can I reach within 30 minutes?" or "How far can my electric vehicle travel on its current charge?" by generating precise polygon boundaries that represent accessible regions.

Isochrones (also known as service areas or catchment areas) are essential for location intelligence, site selection, delivery zone planning, service coverage analysis, and accessibility studies. The API supports multiple range calculations in a single request, allowing you to visualize nested coverage zones (e.g., 10, 20, and 30-minute travel times) and compare accessibility across different scenarios. With support for all transport modes - including specialized profiles for electric vehicles with battery consumption modeling - you can perform accurate reachability analysis for diverse use cases.

The returned polygon coordinates can be directly displayed on interactive maps and used as geographic filters for location searches, demographic analysis, and other spatial queries. Whether you're optimizing delivery territories, analyzing market coverage, planning emergency response zones, or studying urban accessibility, the Isochrones API provides the geospatial intelligence needed to make data-driven decisions about location-based services and resource allocation.

:::info Complete API Reference View the complete Isochrones API Reference for detailed request/response schemas, examples, and interactive documentation. :::

Endpoint: POST /isochrones

Base URL: https://api.magiclane.net/api/v1

Key Features​

  • Calculate reachable areas based on time, distance, or EV battery consumption
  • Support for transport modes (car, lorry, truck, pedestrian, bike)
  • Multiple range intervals in a single request
  • Returns polygon coordinates for display on maps
  • Integration with route avoidance options
  • E-bike battery consumption calculations for reachability analysis
  • Customizable vehicle specifications

Required Parameters​

  • departure - Starting location as [longitude, latitude]
  • ranges - Array of range values, each greater than 0 (max 10). Unit depends on type: seconds for fastest, meters for shortest, watt-hours for economic (e-bikes only)

Optional Parameters​

  • transport - Route transport mode (car, lorry, truck, pedestrian, bike)
  • type - Route type (fastest, shortest, economic, scenic); the accepted values depend on the transport mode - see Common Parameters
  • avoid - Features to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks, immutable_roadblocks) - see Common Parameters
  • profile - Detailed transport profile (road, cross, city, mountain, road_pedelec, cross_pedelec, city_pedelec, mountain_pedelec, road_spedelec, cross_spedelec, city_spedelec, mountain_spedelec, hike, walk), a shortcut for vehicle.profile (send one or the other) - see Common Parameters
  • fitness - Fitness factor [0,1] for tuning bike/pedestrian isochrones; values outside [0,1] are rejected as invalid
  • geometry - Geometry encoding (lineString, polyline)
  • emergency - Emergency vehicle mode
  • vehicle - Detailed vehicle specifications - see Common Parameters
  • avoid_geofence_areas - Geofence area tokens to avoid
  • avoid_geofence_anti_areas - Geofence anti-area tokens to avoid
  • locale - Language code, in the same format as for the Routing API (e.g., en, eng). The isochrone result contains no translated text. Default en
  • debug - If true, the output will be formatted. (default: false)

Example Request - Time-based Isochrones​

curl -X POST https://api.magiclane.net/api/v1/isochrones \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "car",
    "type": "fastest",
    "departure": [13.388860, 52.517037],
    "ranges": [600, 1200, 1800],
    "locale": "en"
  }'

This request calculates areas reachable within 10, 20, and 30 minutes by car.

Example Request - Distance-based Isochrones​

curl -X POST https://api.magiclane.net/api/v1/isochrones \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "bike",
    "type": "shortest",
    "departure": [13.388860, 52.517037],
    "ranges": [2000, 5000, 10000],
    "vehicle": {
      "profile": "city"
    }
  }'

This request calculates areas reachable within 2km, 5km, and 10km by bike.

Example Request - E-Bike Battery Consumption Isochrones​

curl -X POST https://api.magiclane.net/api/v1/isochrones \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "bike",
    "type": "economic",
    "departure": [13.388860, 52.517037],
    "ranges": [100, 250, 500],
    "geometry":"polyline",
    "vehicle": {
      "profile": "city_spedelec",
      "mass": 25,
      "speed": 10.9
    }
  }'

This request calculates reachable areas for a speed-pedelec setup using 100Wh, 250Wh, and 500Wh battery consumption ranges. Because geometry is set to polyline, each route's points is returned as an encoded polyline string instead of a coordinate array.

Response Structure​

The API returns a JSON object containing:

  • info - Copyright and attribution information
  • routes - Array of isochrone objects (one for each range value, in the order of ranges), each containing:
    • distance - The requested range value of this isochrone, in the unit of the range (seconds, meters or watt-hours, see ranges)
    • time - Same value as distance
    • bbox - Bounding box [west, south, east, north] (min longitude, min latitude, max longitude, max latitude)
    • points - Polygon defining the reachable area
      • type - Encoding type ("LineString" or "polyline")
      • coordinates - Array of coordinate arrays [[lon, lat], ...] (when type is "LineString"); isochrone coordinates carry no altitude
      • polyline - Google polyline encoded string (when type is "polyline")
  • error - Returned instead of routes when the request is invalid (HTTP 400) or no isochrone can be computed (HTTP 200)
    • code - Numeric error code, for support and diagnostics; use reason and details for display
    • reason - Short error explanation, e.g., "Invalid input", "No routes available between these locations"; may be empty for some errors
    • details - What was wrong with the request (invalid requests only)

The returned polygon coordinates can be displayed on a map and used as a geographic filter for location searches and other spatial queries.

Last updated on