From c4c63ffd62925de7020f499e9fd3737ca9f97b5f Mon Sep 17 00:00:00 2001 From: Maurice Date: Fri, 30 Oct 2026 23:01:17 +0100 Subject: [PATCH] docs(transit): describe the empty-result fallback between transit providers Admin settings, transport, environment and MCP pages still said Transitous is the only fallback and that Google is billed only when picked. Document that an empty plan asks the other backend, that the Google fallback uses only an instance key within the daily limit, and mention it in the search_transit_routes tool description. --- server/src/nest/transit/transit.mcp.ts | 2 +- server/src/nest/transit/transit.service.ts | 7 ++++--- wiki/Admin-Settings.md | 2 ++ wiki/Environment-Variables.md | 2 +- wiki/MCP-Tools-and-Resources.md | 2 +- wiki/Transport-Flights-Trains-Cars.md | 2 +- 6 files changed, 10 insertions(+), 7 deletions(-) diff --git a/server/src/nest/transit/transit.mcp.ts b/server/src/nest/transit/transit.mcp.ts index 9d4e9a699..537fe103b 100644 --- a/server/src/nest/transit/transit.mcp.ts +++ b/server/src/nest/transit/transit.mcp.ts @@ -110,7 +110,7 @@ export class TransitMcp { @Tool({ name: 'search_transit_routes', description: - 'Search scheduled public-transit routes between two coordinates, via whichever backend the instance is configured for. Returns itineraries that can be passed unchanged to create_transit_journey, and `provider`, the backend that answered. `dropped` counts provider itineraries that failed validation and are therefore absent from the results — a non-zero value means the provider offered routes this tool could not represent.', + 'Search scheduled public-transit routes between two coordinates, via the backend the instance is configured for, falling back to the other backend when it finds no route. Returns itineraries that can be passed unchanged to create_transit_journey, and `provider`, the backend that answered. `dropped` counts provider itineraries that failed validation and are therefore absent from the results — a non-zero value means the provider offered routes this tool could not represent.', inputSchema: { from: transitPlaceInput, to: transitPlaceInput, diff --git a/server/src/nest/transit/transit.service.ts b/server/src/nest/transit/transit.service.ts index 69eb91098..03b1c1c35 100644 --- a/server/src/nest/transit/transit.service.ts +++ b/server/src/nest/transit/transit.service.ts @@ -28,9 +28,10 @@ import type { TransitProvider } from '@trek/shared'; * the same compact shape. Transitous remains the default. Empty plans try the * other backend when available; Google fallback requires an admin-set key. * - * Both responses name the backend that answered. The fallback is silent by - * design, so without this an empty result is indistinguishable between "this - * provider has no data here" and "the provider you picked never ran" — which is + * Both responses name the backend that answered. Both fallbacks (no Google key, + * and the empty-plan retry) are silent by design, so without this an empty + * result is indistinguishable between "this provider has no data here" and + * "the provider you picked never ran" — which is * exactly the guessing game a Paris search ran into when the Île-de-France feed * ended before the trip date. * diff --git a/wiki/Admin-Settings.md b/wiki/Admin-Settings.md index 541ac3047..7ce96db0b 100644 --- a/wiki/Admin-Settings.md +++ b/wiki/Admin-Settings.md @@ -118,6 +118,8 @@ Which service answers public transit search. It saves as soon as you pick. With **Google** picked but no Google key configured, a warning says transit search is still using Transitous. When only your own personal Google key is set, a warning says that other members still fall back to Transitous until the key is saved here as the instance key. See [Transport-Flights-Trains-Cars](Transport-Flights-Trains-Cars). +When the picked service finds no connection, the search asks the other one before it reports an empty result. From Google, that is Transitous. From **Transitous**, Google is asked only when an instance key (saved here or set through `PLACES_API_KEY`) is available and the **Daily limit for Google calls** is not reached; a member's personal key is never billed for it. Each such fallback counts as one billed Google search. An error from the picked service is shown as before and does not trigger the fallback. + ### Place search provider TREK's own index and OpenStreetMap answer every search. This picks who else is asked when they find nothing: diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 59bec8030..d554582cf 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -354,7 +354,7 @@ Booking import can also fall back to an AI model for documents KDE Itinerary can Public-transit routing in the planner is powered by [Transitous](https://transitous.org/), a free community MOTIS service — no API key is required. See [Transport: Flights, Trains, Cars](Transport-Flights-Trains-Cars) for the feature itself. -An admin can switch the backend under **Admin → Settings → API Keys → Transit Provider**: **Transitous (free)** is the default and the fallback, **Google** answers with the Google API key set on the same card and is billed per search. While no Google key is set, searches keep going to Transitous. `TRANSIT_API_URL` below only applies to the Transitous path. +An admin can switch the backend under **Admin → Settings → API Keys → Transit Provider**: **Transitous (free)** is the default and the fallback, **Google** answers with the Google API key set on the same card and is billed per search. While no Google key is set, searches keep going to Transitous. A search that finds no connection asks the other backend before it comes back empty; with Transitous picked, Google is asked only through an instance key (the admin's or `PLACES_API_KEY`) within the daily Google limit. `TRANSIT_API_URL` below only applies to the Transitous path. | Variable | Description | Default | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| diff --git a/wiki/MCP-Tools-and-Resources.md b/wiki/MCP-Tools-and-Resources.md index 18a0af192..f17121b65 100644 --- a/wiki/MCP-Tools-and-Resources.md +++ b/wiki/MCP-Tools-and-Resources.md @@ -128,7 +128,7 @@ Requires `reservations:write` scope. ### Automated public transit -Transit search is powered by Transitous and uses the existing `geo:read` and `reservations:write` scopes. +Transit search is powered by the configured transit provider (Transitous by default, or Google), falls back to the other one when the first finds no route, and uses the existing `geo:read` and `reservations:write` scopes. | Tool | Scope required | Description | |---|---|---| diff --git a/wiki/Transport-Flights-Trains-Cars.md b/wiki/Transport-Flights-Trains-Cars.md index c1febec77..8d3cc6d9d 100644 --- a/wiki/Transport-Flights-Trains-Cars.md +++ b/wiki/Transport-Flights-Trains-Cars.md @@ -116,7 +116,7 @@ On a phone, the journey opens in its own view with the same itinerary and action Self-hosters can point the `TRANSIT_API_URL` environment variable at their own MOTIS instance. -> **Admin:** which service answers the search is set under **Admin → Settings → API Keys → Transit Provider**. **Transitous (free)** is the default: community GTFS feeds, keyless, with the best coverage in Europe. **Google** runs the stop search and the route plan through the Google Maps API key in the same card, for regions Transitous has no data for. Google bills per search, and the key has to be allowed to call the **Routes API** and the **Places API (New)** (text search); the legacy Directions API is not used. A key saved only in a member's own settings serves that member alone, so save it as an admin to apply it to the whole instance. While no Google key is available, the search stays on Transitous even with Google selected, which is why an empty result names the service that answered (*No connections found via Google*). +> **Admin:** which service answers the search is set under **Admin → Settings → API Keys → Transit Provider**. **Transitous (free)** is the default: community GTFS feeds, keyless, with the best coverage in Europe. **Google** runs the stop search and the route plan through the Google Maps API key in the same card, for regions Transitous has no data for. Google bills per search, and the key has to be allowed to call the **Routes API** and the **Places API (New)** (text search); the legacy Directions API is not used. A key saved only in a member's own settings serves that member alone, so save it as an admin to apply it to the whole instance. While no Google key is available, the search stays on Transitous even with Google selected, which is why an empty result names the service that answered (*No connections found via Google*). When the picked service returns no connection, the other one is asked before the empty result is shown: Transitous after Google, and Google after Transitous as long as an instance Google key and daily quota are available (that fallback is billed like any Google search). The routes found say which service they came from, and an added journey keeps that service as its provider. ## Offline