What OTP 2 can express, and how to expose it to travellers

1. The engine's model in one paragraph

A trip is [access → transit → egress] computed together with [direct]. Each street slot takes one StreetMode; the transit part takes a set of TransportMode (optionally narrowed by submodes). On top of that, OTP accepts who may operate the legs (banned / whitelisted authorities, lines, rental networks), where the trip must pass (pass-through points, via trips), when (date-time, arrive-by, search window, paging), for whom (wheelchair, speeds, reluctances, slacks, transfer limits) and how many results (numTripPatterns, itinerary filters). Everything below is a way of asking a traveller one of those questions.

2. Street modes: the ten values and where they may go

Gaps this table showed, now addressed in the mockups:

• Scooter: Rental scooter preset, and a Scooter mode (rental only) in the toggle designs 4a/4b.
• Kiss & ride / taxi and other asymmetric trips are deliberately not presets: they are what custom is for (three selects, one query). Rental modes already fall back to walking when no vehicle is around (verified live: bike_rental ×3 gave foot → rail → foot → bicycle(rented) → foot), and car_pickup only needs a direct foot to keep its transit shapes.
• Return trips: the two park presets carry the note "return trip: reverse the shape, pick the vehicle up at the same stop". A UI responsibility, OTP cannot enforce it.
• Also added: Transit only (omit directMode), Just drive and Just cycle (transportModes= empty), On-demand transport (where flex data exists).
• Rental presets show two shapes from one query, exactly like rental bike did live.

3b. The transit-vs-street filter changes the query count

Verified live on the BMC OTP2 (2026-09-09, Grand-Place → Meiser, next morning 8:00):

OTP's itinerary filter (removeTransitWithHigherCostThanBestOnStreetOnly, on by default, server-wide) drops every transit itinerary that costs more than the best street-only one. A fast direct mode (car, taxi) therefore hides the transit shapes of the same query; bike does not, at city distances.

• Car (car trip and transit alternatives) is 2 queries: foot / foot / foot and foot / car / foot with transportModes= empty; the car preset does both in one document. modePreset=car
• Park & ride and dropped off keep foot as direct mode, otherwise the direct car kills the shape the preset is about.
• One-query alternative: itineraryFiltersDebug=listAll returns the filtered itineraries tagged in systemNotices; a client can keep them and hide the tag. Product-grade version: a keepTransitAlternatives flag that maps to listAll and strips the notices server side.
• Data caveat: in Brussels scooter_rental and car_rental returned no rental legs, OTP silently falls back to walking; scooters do show up in Antwerp (Lime). A preset should say so when its vehicle is not available; the rental network lists are how a customer would scope that.

3. Trip shapes and the unset slots: no polyfill

OTP 2 defaults the three street modes to foot when the modes input is omitted altogether, and leaves the missing ones unset when some are given (an unset slot produces no itinerary of that shape). A first version of planner-v2-1 polyfilled the missing slots with foot; that was dropped: the API keeps the OTP 2 semantics and only rejects the combinations that cannot return anything.

The preset recipe follows the same model: its transit-only preset leaves the direct slot unset. No special value such as none is needed.

4. Transit modes and submodes

5. Operators, lines, networks: the "who" dimension

6. Places: from, to, and in between

7. Time

8. The traveller profile: settings that outlive one search

These map naturally to a profile screen (saved once) rather than to the search form; the user preferences of the mockups are exactly that.

9. Is the option set complete? Check against the intents

9b. The preset recipe: planner-v2-1-preset

Same parameters as planner-v2-1 minus accessMode, directMode, egressMode (transportModes stays: it narrows the transit part of every query of the preset), plus:

The response adds modePreset (id, label in the requested locale, queries keys, skippedQueries on the next pages) and the cursor pair of planner-v2-1 (plan.nextPageCursor / plan.previousPageCursor, also cursors.trip), itineraries merged and sorted like planner-v2.

Labels exist in en, fr, nl, de. Verified live: car-multimodal merges car, park & ride and rental car itineraries from one document; transit-only returns transit itineraries and no walk-only one: leaving the direct slot unset is the transit-only mechanism, in both recipes.

• The merge (planner-v2's mergeOtp2TripResponses) dedupes on every leg's mode + aimed times + end points (or otp leg id for transit legs): two queries of a preset returning the same itinerary (bike-multimodal: the direct bicycle trip of the own bike and the parked bike queries) keep one. Fixed 2026-09-10: the key was overridden by the legs' own id, null on street legs in OTP 2.9, so planner-v2 and the presets showed the duplicate.
• In a planner-v2 style fan out, the plain transit query of the multimodal profile sends modes: { transportModes } without access/egress modes, which OTP2 treats as no access at all: that query returns zero itineraries (verified live with the same variables the production builder sends). Flagged as a separate task.

9c. One cursor for many queries: how the preset recipe pages

What the client sees: planner-v2-1-preset pages exactly like planner-v2-1. One pageCursor parameter in, plan.nextPageCursor / plan.previousPageCursor (also cursors.trip) out, whatever the number of OTP 2 queries behind the preset. "Earlier" and "Later" are one link each, the client never learns the query keys. Try it: modePreset=car then page with the Earlier / Later buttons of the planner page.

What OTP 2 gives us (verified live on the staging OTP 2.9, 2026-09-10, Brussels Central → Leuven, next day 08:00)

An OTP 2 cursor is a base64 token, readable once decoded: 2|NEXT_PAGE|2026-09-11T06:31:42Z||40m|STREET_AND_ARRIVAL_TIME|false|<cut departure>|<cut arrival>|1|3804|41045|. The direct street search still runs on the next pages (OTP's RoutingWorker always calls it), but the paging filter removes the street itinerary because it sorts before the cut: inside one query OTP itself treats the door to door trip as a first page thing.

The policy

Why this and not…

• One JSON parameter keyed by query key (the first version, pageCursors): the client had to know which preset runs which queries, the contract changed with every preset edit, a single pageCursor was refused on multi query presets, and it was JSON in a query string.
• Give the transit cursor to every query: proven to return nothing for the street-only queries (table above) and wrong for the other transit queries (the page cut belongs to one query).
• Re-date the street-only queries on every page: works (verified live, car at 08:44) but buys nothing, see the policy.
• Force the same searchWindow on every query to align the pages: OTP takes the window from the cursor when paging, and a shared window would still not share the cut.
• Only allow paging on single query presets (what the mockups assumed): it made the multi query options second class for no engine reason.

What stays imperfect

• The transit queries of a preset do not cover one clean time span per page: OTP sizes the window per query (live: page 2 of bike-multimodal was 08:42 → 09:15 for the own bike and 08:29 → 08:37 for the parked bike). The merged list is still sorted, and planner-v2 lives with the same drift.
• The dedupe across queries (leg modes + times + coordinates) cannot dedupe across pages.
• The cursor is about 350 characters per transit query (the OTP token is most of it); a three query preset is under 900 characters, fine for a query string.

For the UX options

Multi query presets (car, bike-multimodal, car-multimodal, the toggle designs) page like single query ones, so their remaining cost is the query count: about 2 s for car and 7 s for bike-multimodal live, against 1 to 2 s for one query. Option pages that used to warn about "as many cursors as queries" now only weigh latency; how many rows a multi query preset shows is the budget rule of 9d. modePreset=bike-multimodal

Source

• Backend: src/utils/api/otp/preset-page-cursor.ts (encode, decode, build), parsePlannerV21PresetParams in src/utils/api/routing/parse-planner-v2-1-params.ts (which queries run on a page), routingPlannerV21PresetFactory.ts (the response), the pageCursor description of the preset OpenAPI.
• Lab and demo mirror: packages/data-services/src/routing/planner-v2-1/preset-page-cursor.ts and planner-v2-1.server.ts, same format and policy.

9d. How many rows: a budget per shape

What the client sees: numTripPatterns keeps its name and its meaning of "at most this many transit itineraries", but on the preset recipe it is the budget of the merged list, whatever the number of OTP 2 queries behind the preset. Omitted, the recipe picks a sane default; the split is reported in modePreset.numTripPatterns. Try it: modePreset=bike-multimodal&numTripPatterns=8

The problem

OTP's numItineraries is per query. Passed through unchanged, a preset returned it once per query (three times 5 for bike-multimodal), and omitted it was OTP's server value of 50 per query, tamed only by the search window (12 to 15 rows live). The obvious fix, cutting the merged list to N after the merge, is wrong with paging: an OTP cursor encodes the page cut at the last itinerary OTP returned, so a row trimmed from page 1 never shows up on page 2 either. The only safe knob is what each query asks OTP for.

The policy

Why a budget per shape and not a global top N

• Paging, as above: a cut after the merge loses rows for good.
• A global cut by arrival time lets one shape crowd the others out: plain transit usually arrives before a park & ride trip, so "Car, all options" would show no park & ride at all. A quota per shape is a diversity guarantee, which is what a multi query preset is for.
• Over-fetching and trimming (ask for more, keep N) has the same paging problem and costs OTP time for rows that are thrown away.

Caveats

• numTripPatterns is a maximum for OTP, not a target: a short search window returns fewer, and the dedupe across queries can lower the total (the direct bike of the own bike and parked bike queries counts once).
• A transit query's own direct trip counts inside its quota (own bike: one bike trip plus bike & rail alternatives).
• Small quotas mean short pages: OTP sizes the search window to reach the quota, so page 2 of a quota of 2 can cover a quarter of an hour. Earlier / Later still work, they just move in smaller steps.
• planner-v2-1, the single triplet recipe, defaults to 4 as well: the one default the recipe injects over OTP's semantics (OTP's own is 50, too many for a planner ui). Pass numTripPatterns explicitly for anything else.

Source

• Backend: src/utils/api/otp/preset-num-trip-patterns.ts (the split and the defaults, with its test), applied in parsePlannerV21PresetParams, reported by routingPlannerV21PresetFactory.ts, described on the preset's numTripPatterns parameter in the OpenAPI.
• Lab and demo mirror: packages/data-services/src/routing/planner-v2-1/preset-num-trip-patterns.ts, used by planner-v2-1.server.ts.

10. Recommendations, in order

1. API, small: done on 2026-09-09: whiteListedAgencies, bannedLines / whiteListedLines, bannedServiceJourneys, bannedRentalNetworks / whiteListedRentalNetworks, fromPlaceId / toPlaceId (undocumented), passThroughPoints, relaxTransitGroupPriorityRatio / Constant, maxAccessEgressDurationForMode (+ per-mode split), all as separate params (no JSON), in both recipes (enforced by a test), transportModes included in the preset recipe since 2026-09-10. Still open: keepTransitAlternatives (one-query car preset, maps to listAll and strips the notices).
2. API, medium: the two recipes run on OTP 2.9 since 2026-09-10 (via replaces passThroughPoints, bikePreferences groups the bike settings, carpool is a new street mode, greenways is gone from the bike optimisation methods); rail transportSubModes once we know what the graph carries; filters deliberately not exposed (JSON, and it disables the banned/whitelisted params).
3. UX, presets: done in the mockups (scooter, transit only, just drive, just cycle, on-demand; asymmetric trips stay in custom); the return-trip reversal for park presets is still only a note, it needs a real design.
4. UX, structure: split the form in two: trip intent (mode presets or toggles, per search, one query) and traveller profile (operators, rental networks, accessibility, pace, max walk, transfers; saved once, applied to every query). Done in the mockups: option 1 is Global settings with 1a user preferences and 1b routing settings; both are pieces of the profile, not an alternative to the presets.
5. Keep the one-query rule: anything that needs several triples (custom with lists, both toggles checked) is a client concern (parallel calls shown as tabs, not merged) or a multimodal preset of the preset recipe.