GET /v1/isochrone

Overview

An isochrone is the area reachable from a point within a given time budget: "everything I can reach in 15 minutes by bike". The response is a GeoJSON FeatureCollection ready to overlay on a MapLibre or Leaflet map. Typical uses: delivery zones, catchment analysis for stores or agencies, real-estate search by commute time.

Cost: 10 credits per request. Availability: from the Startup plan. The maximum time budget depends on your plan: 30 minutes on Startup, 60 on Growth, 120 on Pro.

Request

GET https://api.geocodeme.net/v1/isochrone

Required header: X-Api-Key: gm_YOUR_API_KEY

Parameters

Parameter	Type	Required	Default	Description
point	string	Yes	n/a	Origin as lon,lat (e.g. 2.3522,48.8566)
minutes	integer	Yes	n/a	Time budget in minutes (1 to 120, capped by your plan)
profile	string	No	car	Vehicle profile: car, bike, foot, truck, or moto (plan-gated: bike/foot Startup+, truck/moto Growth+)
use_tolls	boolean	No	n/a	Prefer (true) or avoid (false) toll roads. Motorized profiles only
truck_height	float	No	n/a	Vehicle height in meters (0 to 10). Requires profile=truck
truck_width	float	No	n/a	Vehicle width in meters (0 to 5). Requires profile=truck
truck_weight	float	No	n/a	Vehicle weight in metric tons (0 to 100). Requires profile=truck

Costing option rules

truck_* parameters require profile=truck, and use_tolls cannot be combined with bike or foot; otherwise the API returns a 400 INVALID_PARAMETER. Requests rejected by these validations are not charged any credits.

Code Examples

cURL

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/isochrone?point=2.3522,48.8566&minutes=15&profile=bike"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/isochrone",
    params={"point": "2.3522,48.8566", "minutes": 15, "profile": "bike"},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
feature = data["isochrones"]["features"][0]
print(f"Contour: {feature['properties']['contour']} min")
print(f"Polygon points: {len(feature['geometry']['coordinates'][0])}")

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/isochrone?point=2.3522,48.8566&minutes=15&profile=bike",
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();

// The FeatureCollection can be handed to MapLibre directly:
// map.addSource("isochrone", { type: "geojson", data: data.isochrones });
console.log(data.isochrones.features[0].properties);

Response

info

All responses include rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

isochrones is a standard GeoJSON FeatureCollection with one Polygon feature per contour (polygon ring shortened for readability):

{
  "isochrones": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [2.3901, 48.8566],
              [2.3760, 48.8721],
              [2.3522, 48.8790],
              [2.3280, 48.8722],
              [2.3138, 48.8566],
              [2.3279, 48.8410],
              [2.3522, 48.8341],
              [2.3764, 48.8409],
              [2.3901, 48.8566]
            ]
          ]
        },
        "properties": {
          "contour": 15,
          "metric": "time",
          "color": "#bf4040",
          "fill": "#bf4040",
          "fillColor": "#bf4040",
          "opacity": 0.33,
          "fillOpacity": 0.33,
          "fill-opacity": 0.33
        }
      }
    ]
  },
  "attribution": "Route data (c) OpenStreetMap contributors",
  "meta": {
    "took_ms": 210,
    "cache_hit": false
  }
}

Schema

Field	Type	Description
isochrones	object	GeoJSON FeatureCollection, one Polygon feature per contour
isochrones.features[].geometry	object	GeoJSON Polygon (coordinates in [longitude, latitude] order)
isochrones.features[].properties.contour	integer	The contour's time budget in minutes
isochrones.features[].properties.metric	string	Always "time"
isochrones.features[].properties (other keys)	n/a	Display hints emitted by the routing engine (color, fill, opacity, ...), usable as default map styling
attribution	string	Always "Route data (c) OpenStreetMap contributors"
meta.took_ms	integer	Server processing time in milliseconds
meta.cache_hit	boolean	Whether the response was served from cache

Error Responses

Time budget above your plan's cap

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Your plan allows up to 30 minutes. Upgrade to raise the limit.",
    "field": "minutes",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Endpoint not included in your plan (Free)

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "This feature is not included in your plan. Upgrade to unlock it.",
    "field": "minutes",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Malformed coordinate

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "'point' must be 'lon,lat' (e.g. 2.3522,48.8566)",
    "field": "point"
  }
}

tip

All endpoints are also subject to INVALID_API_KEY (401) and RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429) errors. See Error Codes for the full reference.