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)
Route (Pro)
Route (Enterprise)
Matrix, first 625 pairs (Basis)
Matrix, first 625 pairs (Pro)
Matrix, first 625 pairs (Enterprise)
Matrix, each further pair (Basis)
Matrix, each further pair (Pro)
Matrix, each further pair (Enterprise)
Isochrone (Basis)
Isochrone (Pro)
Isochrone (Enterprise)
Map matching (Pro)
Map matching (Enterprise)
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).
| Tier | Options that trigger this tier |
|---|---|
| Basis | Profiles auto, bicycle and pedestrian; up to 3 intermediate stops; one alternative; avoid with tolls, highways, ferries; text instructions. |
| Pro | Profiles 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). |
| Enterprise | optimize (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}.
/v1/metron/routes/routeComputes a route between two or more locations, optionally with alternatives, navigation data and Enterprise enrichments.
Parameter
locationsarray<{lat, lon}>YesLocations as a list of {lat, lon}, at least start and destination, up to 27.
profilestringYesauto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).
truckobjectOptionalVehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).
alternativesinteger 0–3OptionalDefault:0Number of alternative routes, 0 to 3. From 2, tier Pro.
avoidarray<string>OptionalList of tolls, highways, ferries.
avoid_areasarray<GeoJSON>OptionalAreas to avoid as GeoJSON (Polygon, MultiPolygon, Feature or FeatureCollection); at most 20 areas and 2,000 points. Pro.
headingfloat 0–360OptionalDirection of travel at the start in degrees (0 to 360).
depart_atstringOptionalDeparture as local time in the format YYYY-MM-DDThh:mm. With transit: departure at the start; without it, now.
arrive_bystringOptionalArrival 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.
transitobjectOptionalOptions for profile transit: arrive_by, modes, access, egress, max_transfers, alternatives. See the section Public transport.
languagestringOptionalDefault:de-DELanguage of the instructions, for example de-DE (default) or en.
max_speedfloatOptionalTop speed of the vehicle in km/h, up to 300. Pro.
attributesbooleanOptionalDefault:falseRoad attributes per section. Pro.
navigationbooleanOptionalDefault:falseVoice and banner instructions, lanes, speed limits, traffic lights. Pro.
format"metron" | "osrm"OptionalDefault:metronmetron (default) or osrm. osrm is Pro.
trafficbooleanOptionalDefault:falseTake jams and current speeds into account for choice and duration (German motorways). Closures apply without traffic too. Pro.
allow_privatebooleanOptionalDefault:falseDestinations may lie on private roads: switches off the arrival on the nearest public road (see Arrival at the destination). Pro.
optimizebooleanOptionalDefault:falseOptimise the order of intermediate stops. Enterprise.
rest_timesobjectOptionalObject {rules: "eu561", driving_so_far_min, start_of_shift}. Enterprise.
places_alongarray<string>OptionalList of categories, at most 3. Enterprise.
weatherbooleanOptionalDefault:falseWeather along the route. Enterprise.
max_tier"basis" | "pro" | "enterprise"Optionalbasis, pro or enterprise: cap on the tier.
keystringOptionalpk_ 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();/v1/metron/routes/matrixComputes 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}>YesSources as a list of {lat, lon}.
targetsarray<{lat, lon}>OptionalTargets as a list of {lat, lon}. Without it the matrix is square over sources.
profilestringYesauto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).
metricsarray<string>OptionalSubset of duration and distance. Both if omitted.
truckobjectOptionalVehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).
avoidarray<string>OptionalList of tolls, highways, ferries.
max_tier"basis" | "pro" | "enterprise"Optionalbasis, 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/v1/metron/routes/isochroneReturns the area reachable from a location within a time or distance, as GeoJSON.
Parameter
location{lat, lon}YesOrigin as {lat, lon}.
profilestringYesauto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).
truckobjectOptionalVehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).
contoursarray<object>YesList 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>OptionalAreas to avoid as GeoJSON (Polygon, MultiPolygon, Feature or FeatureCollection); at most 20 areas and 2,000 points. Pro.
max_tier"basis" | "pro" | "enterprise"Optionalbasis, pro or enterprise: cap on the tier.
keystringOptionalpk_ 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();/v1/metron/routes/matchMatches a recorded GPS trace to the road network.
Parameter
pointsarray<{lat, lon, time}>YesGPS points as a list of {lat, lon, time}; time (Unix seconds) is optional. 2 to 5,000 points.
profilestringYesauto, bicycle, pedestrian (Basis); truck, bus, taxi, motorcycle, scooter (Pro). transit (public transport, Pro).
truckobjectOptionalVehicle data for truck: height, width, length (metres), weight, axle_load (tonnes), hazmat (boolean).
max_tier"basis" | "pro" | "enterprise"Optionalbasis, 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_traceMatrix 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_request400. An option is invalid; the field field names it.tier_exceeded400. The request needs more than max_tier allows; required names the tier.not_available400. 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_route422. There is no connection between the locations. With profile transit also when a location lies outside Germany or no stop is within reach.outside_timetable422. The time lies outside the loaded timetable (profile transit); valid_from and valid_until give the valid period.unmatched_location422. A location is too far from a drivable road; index gives its position, for the matrix together with index_side (sources or targets).unmatched_trace422. The trace cannot be matched to a road course.unavailable503. 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.