Routing

METRON Routes

Routes, matrices, isochrones and trace matching on OpenStreetMap data. The tier (Basis, Pro, Enterprise) follows from the options each request uses. With profile transit also public transport connections in Germany.

Pricing

Route (Basis)

50Credits

Route (Pro)

100Credits

Route (Enterprise)

200Credits

Matrix, first 625 pairs (Basis)

50Credits

Matrix, first 625 pairs (Pro)

100Credits

Matrix, first 625 pairs (Enterprise)

150Credits

Matrix, each further pair (Basis)

1Credits

Matrix, each further pair (Pro)

2Credits

Matrix, each further pair (Enterprise)

4Credits

Isochrone (Basis)

40Credits

Isochrone (Pro)

80Credits

Isochrone (Enterprise)

200Credits

Map matching (Pro)

100Credits

Map matching (Enterprise)

100Credits

Keys and access

On the server, use an sk_ key in the Authorization header. In the browser, use a pk_ key bound to allowed sites (origins) for route and isochrone; pass it as the key parameter. Matrix and trace matching require an sk_ key. Access is enabled per account (scope metron:routes).

Billing

Only a success (status 200) is billed. Responses with status 4xx, 422 or 503 cost nothing. A matrix is priced by its pairs (sources times targets): the first 625 pairs of a request at the per-pair price, each further pair at the lower extra price.

Tiers

The tier follows from the request: it falls into the highest tier that any of its options requires. The billed tier is in the response header X-Metron-Tier (basis, pro or enterprise).

TierOptions that trigger this tier
BasisProfiles auto, bicycle and pedestrian; up to 3 intermediate stops; one alternative; avoid with tolls, highways, ferries; text instructions.
ProProfiles truck, bus, taxi, motorcycle and scooter; 4 to 25 intermediate stops; 2 to 3 alternatives; avoid_areas; arrive_by; max_speed; attributes; navigation; format=osrm; allow_private; traffic=true (jams in route choice and duration). Trace matching is always Pro. Profile transit (public transport, billed as a Pro route).
Enterpriseoptimize (stop order), rest_times (driving and rest times under EU 561/2006), places_along (places along the route, at most 3 categories) and weather (weather along the route, DACH and South Tyrol).

If an enrichment fails (for example the places search along the route), the route still comes back and is billed as Pro. The enrichment_errors field then states the reason.

Cap with max_tier

max_tier (basis, pro or enterprise) caps the tier of a request. If the request needs more, the API answers 400 with the code tier_exceeded; the field required names the tier needed. Nothing is billed.

Response headers

X-Metron-Tier names the billed tier. For a matrix, X-Metron-Pairs also gives the number of billed pairs.

Limits

  • Route: up to 27 locations (start, destination and at most 25 intermediate stops).
  • Matrix: at most 2,500 pairs and at most 100 points in total. Without targets the sources count twice (they are also the targets). Split larger matrices into blocks.
  • Isochrone: at most 4 contours, each at most 60 minutes or 200 km.
  • Trace matching: at most 5,000 points.
  • optimize: at most 12 locations within 150 km.

Endpoints

Locations are objects of the form {"lat": 48.1371, "lon": 11.5754}.

POST/v1/metron/routes/route

Computes a route between two or more locations, optionally with alternatives, navigation data and Enterprise enrichments.

Parameter

  • locationsarray<{lat, lon}>
    Yes

    Locations as a list of {lat, lon}, at least start and destination, up to 27.

  • profilestring
    Yes

    auto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).

  • truckobjectOptional

    Vehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).

  • alternativesinteger 0–3OptionalDefault: 0

    Number of alternative routes, 0 to 3. From 2, tier Pro.

  • avoidarray<string>Optional

    List of tolls, highways, ferries.

  • avoid_areasarray<GeoJSON>Optional

    Areas to avoid as GeoJSON (Polygon, MultiPolygon, Feature or FeatureCollection); at most 20 areas and 2,000 points. Pro.

  • headingfloat 0–360Optional

    Direction of travel at the start in degrees (0 to 360).

  • depart_atstringOptional

    Departure as local time in the format YYYY-MM-DDThh:mm. With transit: departure at the start; without it, now.

  • arrive_bystringOptional

    Arrival as local time in the format YYYY-MM-DDThh:mm. Pro; not together with depart_at. With transit: latest arrival as local time at the destination, the same as depart_at with transit.arrive_by.

  • transitobjectOptional

    Options for profile transit: arrive_by, modes, access, egress, max_transfers, alternatives. See the section Public transport.

  • languagestringOptionalDefault: de-DE

    Language of the instructions, for example de-DE (default) or en.

  • max_speedfloatOptional

    Top speed of the vehicle in km/h, up to 300. Pro.

  • attributesbooleanOptionalDefault: false

    Road attributes per section. Pro.

  • navigationbooleanOptionalDefault: false

    Voice and banner instructions, lanes, speed limits, traffic lights. Pro.

  • format"metron" | "osrm"OptionalDefault: metron

    metron (default) or osrm. osrm is Pro.

  • trafficbooleanOptionalDefault: false

    Take jams and current speeds into account for choice and duration (German motorways). Closures apply without traffic too. Pro.

  • allow_privatebooleanOptionalDefault: false

    Destinations may lie on private roads: switches off the arrival on the nearest public road (see Arrival at the destination). Pro.

  • optimizebooleanOptionalDefault: false

    Optimise the order of intermediate stops. Enterprise.

  • rest_timesobjectOptional

    Object {rules: "eu561", driving_so_far_min, start_of_shift}. Enterprise.

  • places_alongarray<string>Optional

    List of categories, at most 3. Enterprise.

  • weatherbooleanOptionalDefault: false

    Weather along the route. Enterprise.

  • max_tier"basis" | "pro" | "enterprise"Optional

    basis, pro or enterprise: cap on the tier.

  • keystringOptional

    pk_ key, if you cannot send an Authorization header.

Request

curl -X POST "https://api.centra.dbpg.io/v1/metron/routes/route" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "lat": 48.1371, "lon": 11.5754 },
      { "lat": 52.5200, "lon": 13.4050 }
    ],
    "profile": "auto",
    "alternatives": 1,
    "language": "de-DE"
  }'

Response

{
  "routes": [
    {
      "geometry": { "type": "LineString", "coordinates": [[11.5754, 48.1371], ...] },
      "distance_m": 585000,
      "duration_s": 22000,
      "legs": [ { "distance_m": 585000, "duration_s": 22000, "steps": [ ... ] } ]
    }
  ],
  "tier": "basis",
  "attribution": "© OpenStreetMap-Mitwirkende"
}
const res = await fetch("https://api.centra.dbpg.io/v1/metron/routes/route", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({
    locations: [{ lat: 48.1371, lon: 11.5754 }, { lat: 52.52, lon: 13.405 }],
    profile: "truck",
    truck: { height: 4, weight: 40 },
    traffic: true,
    max_tier: "pro",
  }),
});
console.log(res.headers.get("X-Metron-Tier")); // "pro"
const { routes, traffic } = await res.json();
POST/v1/metron/routes/matrix

Computes duration and distance for all pairs of sources and targets. Rows are sources, columns are targets, both in input order; seconds and metres as integers, null where a pair is unreachable.

Parameter

  • sourcesarray<{lat, lon}>
    Yes

    Sources as a list of {lat, lon}.

  • targetsarray<{lat, lon}>Optional

    Targets as a list of {lat, lon}. Without it the matrix is square over sources.

  • profilestring
    Yes

    auto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).

  • metricsarray<string>Optional

    Subset of duration and distance. Both if omitted.

  • truckobjectOptional

    Vehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).

  • avoidarray<string>Optional

    List of tolls, highways, ferries.

  • max_tier"basis" | "pro" | "enterprise"Optional

    basis, pro or enterprise: cap on the tier.

Request

curl -X POST "https://api.centra.dbpg.io/v1/metron/routes/matrix" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{ "lat": 48.1371, "lon": 11.5754 }, { "lat": 48.3705, "lon": 10.8978 }],
    "targets": [{ "lat": 47.4979, "lon": 19.0402 }, { "lat": 48.7758, "lon": 9.1829 }],
    "profile": "auto"
  }'

Response

{
  "duration": [[31000, 12400], [29000, 9800]],
  "distance": [[760000, 230000], [720000, 185000]],
  "traffic": null,
  "tier": "basis",
  "attribution": "© OpenStreetMap-Mitwirkende"
}
const res = await fetch("https://api.centra.dbpg.io/v1/metron/routes/matrix", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({ sources: points, profile: "auto", metrics: ["duration"] }),
});
console.log(res.headers.get("X-Metron-Pairs")); // pairs billed
POST/v1/metron/routes/isochrone

Returns the area reachable from a location within a time or distance, as GeoJSON.

Parameter

  • location{lat, lon}
    Yes

    Origin as {lat, lon}.

  • profilestring
    Yes

    auto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).

  • truckobjectOptional

    Vehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).

  • contoursarray<object>
    Yes

    List of {time} in minutes (up to 60) or {distance} in kilometres (up to 200); at most 4, time and distance not mixed.

  • avoid_areasarray<GeoJSON>Optional

    Areas to avoid as GeoJSON (Polygon, MultiPolygon, Feature or FeatureCollection); at most 20 areas and 2,000 points. Pro.

  • max_tier"basis" | "pro" | "enterprise"Optional

    basis, pro or enterprise: cap on the tier.

  • keystringOptional

    pk_ key, if you cannot send an Authorization header.

Request

curl -X POST "https://api.centra.dbpg.io/v1/metron/routes/isochrone" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "location": { "lat": 48.1371, "lon": 11.5754 },
    "profile": "auto",
    "contours": [{ "time": 10 }, { "time": 20 }]
  }'

Response

{
  "type": "FeatureCollection",
  "features": [ { "type": "Feature", "geometry": { "type": "Polygon", ... }, "properties": { ... } } ],
  "tier": "basis",
  "attribution": "© OpenStreetMap-Mitwirkende"
}
const res = await fetch("https://api.centra.dbpg.io/v1/metron/routes/isochrone?key=pk_your_public_key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    location: { lat: 48.1371, lon: 11.5754 },
    profile: "bicycle",
    contours: [{ time: 15 }],
  }),
});
const areas = await res.json();
POST/v1/metron/routes/match

Matches a recorded GPS trace to the road network.

Parameter

  • pointsarray<{lat, lon, time}>
    Yes

    GPS points as a list of {lat, lon, time}; time (Unix seconds) is optional. 2 to 5,000 points.

  • profilestring
    Yes

    auto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).

  • truckobjectOptional

    Vehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).

  • max_tier"basis" | "pro" | "enterprise"Optional

    basis, pro or enterprise: cap on the tier.

Request

curl -X POST "https://api.centra.dbpg.io/v1/metron/routes/match" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "auto",
    "points": [
      { "lat": 48.1371, "lon": 11.5754, "time": 1761730000 },
      { "lat": 48.1402, "lon": 11.5811, "time": 1761730030 }
    ]
  }'

Response

{
  "tier": "pro",
  "attribution": "© OpenStreetMap-Mitwirkende"
}
const res = await fetch("https://api.centra.dbpg.io/v1/metron/routes/match", {
  method: "POST",
  headers: { Authorization: "Bearer sk_your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({ profile: "auto", points: trace }),
});
if (res.status === 422) console.log((await res.json()).error); // unmatched_trace

Matrix as input for Kairos Graph

The matrix fits the matrices field of Kairos Graph directly. The following example fetches the duration matrix and inserts it as cost and duration into a Kairos Graph request.

const headers = { Authorization: "Bearer sk_your_api_key", "Content-Type": "application/json" };

// 1. Duration matrix over all nodes (depot first)
const m = await (await fetch("https://api.centra.dbpg.io/v1/metron/routes/matrix", {
  method: "POST",
  headers,
  body: JSON.stringify({ sources: places, profile: "auto", metrics: ["duration"] }),
})).json();

// 2. The matrix goes straight into Kairos Graph
const result = await (await fetch("https://api.centra.dbpg.io/v1/kairos/graph", {
  method: "POST",
  headers,
  body: JSON.stringify({
    graph: {
      nodes: places.map((_, i) => ({ id: "n" + i })),
      matrices: { default: { cost: m.duration, duration: m.duration } },
    },
    task: {
      type: "tours",
      agents: [{ id: "van-1", start: "n0", end: "n0", capacity: [10] }],
      visits: places.slice(1).map((_, i) => ({ id: "v" + i, node: "n" + (i + 1), demand: [1], service_duration: 300 })),
    },
    config: { time_limit_seconds: 30 },
  }),
})).json();

Traffic

Every route, matrix and isochrone for motor vehicles avoids closures on motorways in Germany and on motorways and expressways in Austria, in every tier and also without traffic=true; traffic then names the sources and closures_considered. Mandatory closures from ASFINAG always apply. With traffic=true (Pro) the route also takes jams and current speeds into account for choice and duration. Only the reported direction is closed, both directions for closures in both directions. Closures whose location is only approximately known are avoided as an area around the reported location. If a start, stop or target lies inside a closure or within 250 m of it and can only be reached through it, only that closure is left out; all others still apply. The data for Germany comes from "Die Autobahn GmbH des Bundes" (GeoNutzV), for Austria from ASFINAG (CC BY 4.0, modified). Jams and delays are available for Germany only. Traffic applies to motor-vehicle profiles only; bicycle and pedestrian give 400 (field: traffic). The traffic object contains source (all source credits in one string, separated by " | "), attributions (the same credits as a list), sources (["api"] or ["api","datex"]), as_of, jams_as_of (state of the jam data), live_speeds (true when live speeds were used) and closures_considered (number of closure areas taken into account; this counts what entered the calculation, not detours actually taken). Traffic applies only to departures from 15 minutes ago to 60 minutes ahead; outside that window traffic.skipped holds future_departure or past_departure, and the route is not billed as a traffic route. If the data is older than 30 minutes or the updater is down, traffic is null, enrichment_errors contains "traffic", and the route is delivered and billed without traffic. Matrix and isochrone with traffic=true answer 400 (not_available).

Truck coverage

Restrictions for trucks (height, width, length, weight, axle load, hazardous goods) come from OpenStreetMap and are not recorded completely everywhere. The route is a planning basis; the signs on site apply.

Public transport

With profile transit, /v1/metron/routes/route computes door-to-door connections by bus, tram, subway, suburban rail, regional and long-distance trains and ferry, including walks and transfers. The profile belongs to tier Pro and is billed as a Pro route; access and egress by bicycle or car cost nothing extra.

Coverage: Germany. The basis is the scheduled timetable; delays and cancellations are not included. The timetable reaches a few weeks ahead. For a time outside it we answer outside_timetable and give the valid period in valid_from and valid_until.

The request holds exactly two locations (start and destination) and depart_at as local time at the start; without depart_at it is now. With transit.arrive_by: true, depart_at is the latest arrival, as local time at the destination; arrive_by is the short form. Options for road routes (for example truck, avoid, alternatives, navigation, traffic) are not allowed with transit and are answered with bad_request.

  • transit.modes: means of transport, all when omitted. rail (all trains except the subway), long_distance, regional, suburban, subway, tram, bus, coach (long-distance bus), ferry, other (cable cars and the like). Without long-distance trains, for example: ["regional", "suburban", "subway", "tram", "bus", "ferry"].
  • transit.access and transit.egress: the way to the first and from the last stop. walk (default), bicycle (own bicycle), car (access only: drive to a stop with parking). At most 30 minutes each. rental (shared bicycles and scooters) is reserved and currently answered with not_available.
  • transit.max_transfers: at most this many transfers, 0 to 8. transit.alternatives: number of connections in the answer, 1 to 5, default 3.
curl -X POST "https://api.centra.dbpg.io/v1/metron/routes/route" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "transit",
    "locations": [
      { "lat": 52.4990, "lon": 13.4177 },
      { "lat": 52.5356, "lon": 13.1998 }
    ],
    "depart_at": "2026-11-03T12:00",
    "transit": {
      "modes": ["regional", "suburban", "subway", "tram", "bus"],
      "access": ["walk"],
      "max_transfers": 3,
      "alternatives": 3
    }
  }'

The answer holds up to alternatives connections in routes. For a departure time the earliest arrival comes first, ties with fewer transfers first; for an arrival time the latest departure that still arrives in time. Each connection has departure and arrival (local time with UTC offset), duration_s, distance_m, transfers, geometry and legs.

Each section in legs has mode (walk, bicycle, car or a means of transport from transit.modes), departure, arrival, duration_s, distance_m and geometry. Rides also have line (for example U8, RE8, ICE 785), headsign (destination), operator, from and to (stop with name, lat, lon and, where the timetable gives it, track), intermediate_stops (number of stops in between) and color and text_color when the line has a colour. If the destination is close, a connection can be a single walk (up to 30 minutes). The lines in geometry are simplified to within 4 metres and keep a point at every stop; distance_m measures the full path.

{
  "routes": [
    {
      "departure": "2026-11-03T12:00:00+01:00",
      "arrival": "2026-11-03T12:40:00+01:00",
      "duration_s": 2400,
      "distance_m": 18500,
      "transfers": 2,
      "geometry": { "type": "LineString", "coordinates": [[13.417748, 52.499047], ...] },
      "legs": [
        { "mode": "walk", "departure": "2026-11-03T12:00:00+01:00", "arrival": "2026-11-03T12:01:00+01:00",
          "duration_s": 60, "distance_m": 26, "geometry": { ... } },
        { "mode": "subway", "line": "U8", "headsign": "S+U Wittenau (Berlin)", "operator": "Berliner Verkehrsbetriebe",
          "from": { "name": "U Kottbusser Tor (Berlin)", "lat": 52.498959, "lon": 13.418101, "track": "2 (U8)" },
          "to": { "name": "S+U Alexanderplatz Bhf (Berlin)", "lat": 52.521048, "lon": 13.412764, "track": "2 (U8)" },
          "departure": "2026-11-03T12:01:00+01:00", "arrival": "2026-11-03T12:08:00+01:00",
          "intermediate_stops": 3, "duration_s": 420, "distance_m": 2600, "geometry": { ... } },
        ...
      ]
    }
  ],
  "tier": "pro",
  "attribution": "© OpenStreetMap-Mitwirkende; Fahrplandaten: DELFI e.V. (delfi.de), CC BY 4.0, von dbpg bearbeitet"
}

Arrival at the destination

When a destination or intermediate stop lies on a way that OpenStreetMap marks as private or closed for cars (such as service roads on an airport apron or staff car parks), the route ends on the nearest public way nearby, at most three times the distance to the nearest road or that distance plus 200 m away. If there is none, the destination stays as given. Private sections on the approach remain allowed; only the end point is affected. Ways open to residents, customers or deliveries count as public. The start is never moved. This applies in every tier at no extra cost; allow_private: true (Pro) switches it off. For airports and stations we recommend the navigation_point from METRON Places as destination, where present.

Weather along the route

With weather=true (Enterprise) the response carries weather at points along the route, timed to the expected arrival. Coverage is Germany, Austria, Switzerland and South Tyrol.

Driving and rest times

With rest_times (Enterprise) the route plans breaks and rest periods under EU 561/2006, with a rest area where one is found. The rules field is eu561; optionally pass driving_so_far_min (up to 1,440) and start_of_shift. Available for the profiles truck, bus and auto, not together with arrive_by. The response carries the note "Planungshilfe ohne Gewähr" (planning aid, no warranty); it replaces neither the tachograph nor legal advice. Times in the response (arrival_with_breaks, eta) are in the local time of their place, with the UTC offset per ISO 8601: the arrival in the destination's time zone, each weather point in its own.

places_along (Enterprise) returns places along the route from METRON Places. Categories: fuel, charging_station, parking, toilets, restaurant, fast_food, cafe, hotel, supermarket; at most 3 per request.

Attribution

Every response carries the attribution field with "© OpenStreetMap-Mitwirkende" (© OpenStreetMap contributors). Display it. If traffic is not null, also display the text from traffic.source (or every credit from traffic.attributions). It names every source used: "Die Autobahn GmbH des Bundes", with jam data "Die Autobahn GmbH des Bundes; Verortung: BASt TMC-LCL (CC BY 4.0)", and for Austria the ASFINAG credit with the CC BY 4.0 licence, the note that the data was modified, and "© OpenStreetMap-Mitwirkende, ODbL". Use the text unchanged. Public transport answers (profile transit) also credit "Fahrplandaten: DELFI e.V. (delfi.de), CC BY 4.0, von dbpg bearbeitet" (timetable data); display both credits.

Privacy

Positions, traces and destinations are not stored permanently. The usage log holds only endpoint, status, duration, tier and account.

Errors

Errors come as JSON with an error field.

  • bad_request 400. An option is invalid; the field field names it.
  • tier_exceeded 400. The request needs more than max_tier allows; required names the tier.
  • not_available 400. The option is not yet offered for this endpoint or profile (for example traffic on the matrix). With profile transit: intermediate stops (field locations) and rental as access or egress (field transit.access or transit.egress).
  • no_route 422. There is no connection between the locations. With profile transit also when a location lies outside Germany or no stop is within reach.
  • outside_timetable 422. The time lies outside the loaded timetable (profile transit); valid_from and valid_until give the valid period.
  • unmatched_location 422. A location is too far from a drivable road; index gives its position, for the matrix together with index_side (sources or targets).
  • unmatched_trace 422. The trace cannot be matched to a road course.
  • unavailable 503. The service is at capacity; the Retry-After header gives the wait in seconds.
  • As with all services: 401 without a valid key, 402 on insufficient balance, 403 for a missing scope or a pk_ key on matrix or trace matching, 429 when the rate limit is exceeded.