Response & schema reference
Download the complete schema set
Section titled “Download the complete schema set”Download all four files for your client.
The downloadable schemas include the upcoming scheduled and expected quay fields. Some values may be absent or empty in responses. See the changelog for new fields, breaking changes and removals.
| File | Contents |
|---|---|
| PlanRequest.proto | Request, user speeds, flex and pricing options |
| PlanResult.proto | Results, trips, legs, places, alerts, booking and fares |
| Modes.proto | Transit and non-transit enums |
| DirectionType.proto | Journey direction enum |
PlanResult
Section titled “PlanResult”| Field | Meaning |
|---|---|
trips[] | Travel options in this result frame |
timestamp | Result timestamp |
errors[] | Routing errors (code, message) |
modifiers[] | Request modifications used for this group |
grade | Group-level relative grade |
containsOnDemand, containsWithSurcharge | Optional, source-dependent flags |
TripPattern
Section titled “TripPattern”| Fields | Meaning |
|---|---|
aimedStartTime, aimedEndTime | Scheduled/planned times |
expectedStartTime, expectedEndTime | Expected times when mapped |
duration, transfers | Minutes and transfer count |
waitingTime, walkTime | Optional minutes |
distance, streetDistance | Optional metres |
legs[], systemNotices[] | Timeline and general notices |
id | Source-derived trip identity; not guaranteed unique across service dates or departures |
itineraryHash | Opaque replay identifier for transit/flex itineraries; empty for purely non-transit trips |
grade | Individual trip grade |
pricingInfo | Optional total, leg fares, discounts and transfer instructions |
Response details by experience
Section titled “Response details by experience”- Trips, legs and maps: place labels, geometry, waiting, branding and rental data.
- Realtime and alerts: expected times, platforms, cancellations and scoped situations.
- Flexible journeys: booking arrangements and uncertainty flags.
- Fares: cents, status, discounts and check-in changes.
- Accessibility: optional wheelchair and bike-permission flags.
Upcoming: scheduled and expected quays
Section titled “Upcoming: scheduled and expected quays”Each boarding, alighting and intermediate EstimatedCall will expose:
| Field | Meaning |
|---|---|
scheduledQuay | Originally scheduled quay, including its ID, coordinates and platform label |
expectedQuay | Effective quay for boarding or alighting, including realtime changes |
The two quays are equal when there is no quay change. Their platform labels are scheduledQuay.publicCode and expectedQuay.publicCode. A missing expected platform label means it is unavailable; do not substitute the scheduled label when displaying the expected platform.
JSON migration: Replace quay with expectedQuay. During the transition, read expectedQuay when present and fall back to quay for current responses. Older responses may not include scheduledQuay.
Protobuf migration: expectedQuay keeps the former quay field number 1; scheduledQuay is added at field 13. Existing binary clients retain access to the effective quay. Regenerate clients from the downloadable schema to access both fields.
aimedPlatform and expectedPlatform are deprecated in the upcoming schema. They continue to carry the scheduled and expected platform labels during the transition; new integrations should use the quay’s publicCode.
Stop identity and parent stations
Section titled “Stop identity and parent stations”The upcoming EstimatedCall.scheduledQuay and expectedQuay (currently quay) can carry privateCode, a source or journey-pattern stop code, and stopPlace, the parent station or stop group. stopPlace has an ID, name, optional town and coordinates, and transport modes. It is optional: some quays have no parent data. Existing quayCode remains in the schema for quay-code context; it may be empty and has no guaranteed universal format. Use id for the returned quay identity and treat privateCode as a separate code, not as a physical quay ID.
These fields may be absent or empty in responses.
Field availability and future development
Section titled “Field availability and future development”Some values may only be filled in the future, but are already provided in the Proto for development purposes. The schema describes the wire contract and allows clients to generate types and prepare integrations ahead of full data availability. It does not guarantee that every value is populated for every journey.
| Field | Current availability / client behavior |
|---|---|
NonTransitLeg.steps, tripWeatherJson | Not currently populated; allow an empty list or absent weather value |
EstimatedCall.stopPositionInPattern | Provided in the Proto for development; not currently populated |
PlanResult.previousPageCursor, nextPageCursor | Source cursors may be returned; public requests do not accept them for pagination |
Quay.stopPlace, stop codes, notices, situations and rental details | Available for some journeys; tolerate missing or empty details |
| Expected/actual times and expected platforms | Depend on realtime/source coverage; fall back to scheduled times and platforms |
pricingInfo, bookingArrangement | Optional enrichment; absence is not a zero fare or proof that booking is unnecessary |
Preserve optional presence when decoding. Non-optional Proto scalars have defaults such as false, 0 or an empty string; repeated fields may be empty. These defaults do not by themselves prove that a source supplied a value. In particular, Quay.wheelchairAccessible cannot represent unknown accessibility separately by presence. Use the optional service-journey accessibility fields when you need a Yes / No / Information unavailable distinction.
Use a matching schema set
Section titled “Use a matching schema set”Keep these files together and update them as a set. Use enum names in your display code and preserve optional values when decoding.