Trips, legs & maps

Four leg types, one timeline

PlanResult.trips[] contains TripPattern objects. Each trip has legs[]; each leg contains one of four detail objects.

Leg	Start / end labels	Useful details
transitLeg	fromEstimatedCall.quay / toEstimatedCall.quay	Line, destination, platforms, intermediate stops, realtime, alerts
nonTransitLeg	fromPlace / toPlace	WALK, BICYCLE, CAR or rental mode; rental station/vehicle data
waitingLeg	Surrounding travel legs	Waiting start and end time
flexibleLeg	fromPlace / toPlace	Booking arrangement, uncertain times, line, operator

Use leg.duration in minutes and leg.distance in metres. Trip-level duration, walking time and waiting time are minutes too.

Leg summary — enums normalized to strings

function describeLeg(leg) {
  if (leg.transitLeg) {
    const t = leg.transitLeg;
    const label = t.line?.publicCode || t.line?.name || t.mode;
    const from = t.fromEstimatedCall?.quay?.name || 'Board';
    const to = t.toEstimatedCall?.quay?.name || 'Alight';
    return `${label}: ${from} → ${to}`;
  }
  if (leg.flexibleLeg) {
    const f = leg.flexibleLeg;
    return `Flexible: ${f.fromPlace?.name ?? ''} → ${f.toPlace?.name ?? ''}`;
  }
  if (leg.nonTransitLeg) {
    return `${leg.nonTransitLeg.mode}: ${(leg.distance / 1000).toFixed(1)} km`;
  }
  if (leg.waitingLeg) return `Wait ${leg.duration} min`;
  return 'Journey segment';
}

Put the right identity on screen

Use line.publicCode for the line badge, destinationDisplay.frontText for its destination and line.branding for a passenger-facing brand. operator identifies the service operator.

Use returned line presentation colors where available, with a readable fallback. Render notices and names as text.

Stops and transfers

Show boarding/alighting calls, expand intermediateEstimatedCalls, and display cancelled calls as unavailable. Show staySeated as “Stay on board” and use returned waiting legs in the timeline.

If pricing supplies transferInstruction, use its full-array leg indices. Walking and waiting legs may exist between the two referenced transit legs.

Draw the route

leg.pointsOnLink.points is an encoded polyline. Decode it to coordinate pairs, then adapt coordinate order for your map library. A typical polyline decoder returns [latitude, longitude], while GeoJSON uses [longitude, latitude].

Install the decoder with npm install @mapbox/polyline.

Using @mapbox/polyline

import polyline from '@mapbox/polyline';
function legFeature(leg) {
  const encoded = leg.pointsOnLink?.points;
  if (!encoded) return null;
  const coordinates = polyline.decode(encoded).map(([lat, lon]) => [lon, lat]);
  if (coordinates.length < 2) return null;
  return {
    type: 'Feature', properties: { legId: leg.id },
    geometry: { type: 'LineString', coordinates }
  };
}

Draw the geometry where it is available. Rental stations and vehicles use their own place coordinates and may include availability or range information when supplied by the source.

A complete journey, leg by leg

Tram 20 through Utrecht, with intermediate stops and the selected route on the map.