Skip to main content
GuidesAPI ReferenceExamples

Isochrones API

|

Current version: 1.0.0, 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.

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 all transport modes (car, lorry, truck, pedestrian, bike, public transport)
  • Multiple range intervals in a single request
  • Returns polygon coordinates for display on maps
  • Integration with route avoidance options
  • EV-specific calculations with charging considerations
  • Customizable vehicle specifications

Required Parameters:

  • waypoints - Starting location as array of coordinates [[longitude, latitude]]

Optional Parameters:

  • transport - Route transport mode (car, lorry, truck, pedestrian, bike, public)
  • type - Route type (fastest, shortest, economic, scenic) - see Common Parameters
  • range - Array of ranges (e.g., [600, 1200, 1800] for 10, 20, 30 minutes)
  • range_type - Type of range calculation (time, distance, consumption)
    • time - Range in seconds (default)
    • distance - Range in meters
    • consumption - Battery consumption in watt-hours (for EVs)
  • avoid - Features to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) - see Common Parameters
  • vehicle - Detailed vehicle specifications - see Common Parameters
  • locale - ISO 3166-1 language code

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",
    "waypoints": [[13.388860, 52.517037]],
    "range": [600, 1200, 1800],
    "range_type": "time",
    "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",
    "waypoints": [[13.388860, 52.517037]],
    "range": [2000, 5000, 10000],
    "range_type": "distance",
    "vehicle": {
      "profile": "city"
    }
  }'

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

Example Request - EV 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": "car",
    "waypoints": [[13.388860, 52.517037]],
    "range": [5000, 10000, 15000],
    "range_type": "consumption",
    "vehicle": {
      "fuel": "electric",
      "batt_capacity": 75000,
      "departure_soc": 0.8
    }
  }'

This request calculates reachable areas based on EV battery consumption (5kWh, 10kWh, 15kWh).

Response Structure​

The API returns a JSON object containing:

  • info - Copyright and attribution information
  • routes - Array of isochrone objects (one for each range value), each containing:
    • distance - Maximum distance in meters for this isochrone
    • time - Maximum time in seconds for this isochrone
    • bbox - Bounding box coordinates [east, south, west, north]
    • points - Polygon coordinates defining the reachable area (as coordinate array or encoded polyline)

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