Services and field tools
Routes and reachable areas
Request road routes, alternatives, directions and time-based isochrones.
On this page
Request and display a route #
Prerequisites: route scope, running Valhalla service, and two road-accessible points inside service coverage. These are road routes, not vessel or marine routes.
import { configure, route, formatDistance, formatDuration } from 'https://maps.example/sw-services.js';
configure({ baseUrl: 'https://maps.example/', apiKey: 'YOUR_API_KEY' });
const routes = await route([120.9787, 14.5826], [121.0493, 14.6516], {
mode: 'car', via: [], alternates: 1
});
const best = routes.features[0];
if (!best) throw new Error('No route returned');
console.log(formatDistance(best.properties.distance_m),
formatDuration(best.properties.duration_s), best.properties.arrive_at);
for (const leg of best.properties.legs) {
for (const step of leg.steps) console.log(step.instruction);
}
// After your MapLibre map loads:
map.addSource('route', { type: 'geojson', data: best });
map.addLayer({ id: 'route-line', type: 'line', source: 'route',
paint: { 'line-color': '#087c64', 'line-width': 5 } });Expected result: GeoJSON LineStrings, best first. Each route includes mode, distance_m, duration_s, depart_at, arrive_at and legs. Each leg has distance, duration and steps with instruction, streets and location. Re-add the route source/layer after changing map styles.
Modes, stops and departure #
| Parameter | Accepted values |
|---|---|
| from, to | Required longitude,latitude |
| mode | car (default), foot or bike |
| via | Up to 5 points, encoded lng,lat;lng,lat in HTTP |
| alternates | Integer 0–2, default 0; availability depends on engine results |
| depart | Optional YYYY-MM-DDTHH:MM Philippine local time; returned ETA timestamps are ISO format |
curl --fail-with-body -G https://maps.example/route -H "X-API-Key: YOUR_API_KEY" --data-urlencode "from=120.9787,14.5826" --data-urlencode "to=121.0493,14.6516" --data-urlencode "mode=car" --data-urlencode "alternates=1"Departure time is supplied to the routing engine when present. Do not treat the ETA as a live traffic prediction: this platform does not provide a live traffic feed. Route quality depends on OSM road access, connectivity and the release date.
Reachable areas #
import { configure, isochrone } from 'https://maps.example/sw-services.js';
configure({ baseUrl: 'https://maps.example/', apiKey: 'YOUR_API_KEY' });
const zones = await isochrone([120.9787, 14.5826], {
mode: 'foot', minutes: [10, 20, 30]
});
console.log(zones.features.map(f => f.properties.minutes));
// Add zones as a GeoJSON source and a fill layer; largest polygons are first.Expected result: Polygon/MultiPolygon features with mode and minutes, ordered largest first. Use one to four integer contours, each 1–120 minutes. Defaults are car and 10,20,30 minutes. The engine deduplicates contour times.
No route and offline limits #
Malformed parameters return 400, out-of-coverage inputs or other supported engine refusals return 422, and no connected route or no nearby road can return 404. Engine failure is 502; timeout is 504. Let users move endpoints onto a connected road or select another mode rather than silently drawing a straight line as a route.