Travel and places · SearchApi

transit.routes

Returns source-reported transit itineraries with timed legs, stops and operator links. Preserves local clock labels and timezones; schedules are not guaranteed real-time predictions, and route preferences do not confirm operational accessibility or ticket availability.

Operation: POST /v1/capabilities/transit.routes/execute
operationId: executeTransitRoutes
Typical credits: 4
Search deadline: 40 s server-side
Paging: local
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per route search or refresh; local alternatives and cached details are free. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/transit.routes/execute, JSON, validated against the TransitRoutesRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of transit.routes
Field	Type	Required	Default	Constraints and description
origin	string \| object	yes
origin.latwhen option 2	number	yes		min -90, max 90
origin.lonwhen option 2	number	yes		min -180, max 180
destination	string \| object	yes
destination.latwhen option 2	number	yes		min -90, max 90
destination.lonwhen option 2	number	yes		min -180, max 180
time	object \| object	no		Omit to depart now; source results may supply only local clock labels.
time.modewhen option 1	"depart_at" \| "arrive_by"	yes
time.atwhen option 1	string	yes		max length 40, pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z\|[+-]\d{2}:\d{2})$ RFC3339 timestamp with an explicit timezone offset.
time.modewhen mode = "last_available"	"last_available"	yes
preference	"best" \| "fewer_transfers" \| "less_walking" \| "wheelchair_accessible"	no	"best"
prefer	"bus" \| "subway" \| "train" \| "tram_and_light_rail"[]	no		min items 1, max items 4, unique items
country	string	no		pattern ^[A-Za-z]{2}$
language	string	no		min length 2, max length 12
num	integer	no	5	min 1, max 10 Alternatives per local page. This does not request more routes than the provider supplies.

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Origin and destination must not be blank.

Examples

Airport to Shinjuku

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/transit.routes/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin":"Narita Airport, Japan","destination":"Shinjuku Station, Tokyo, Japan","num":3}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the TransitRoutesRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of transit.routes
Key	Type	Presence
duration_seconds	integer	when the source has it
distance_m	integer	when the source has it
duration_label	string	when the source has it
distance_label	string	when the source has it
time_window	object	when the source has it
requested_time	string	when the source has it
requested_time_status	string	always
lines	string[]	when the source has it
source	string	always
fetched_at	string	always
realtime_status	string	always

Caveats

Details are served from the record stored at search time without a provider call. When that stored detail is no longer available the call returns 410 session_expired ("the cached record detail is no longer available. Run the search again."); it is never re-fetched.

Follow-ups

Paging: Whole result set held in the session; more is served locally and costs nothing. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (TransitRoutesUpdateParams).
Record actions:
- details: Cached transit legs, stations, operators and available source links.
Detail behaviour: Stored at search time; details is free and never calls the provider. details returns the stored itinerary at no charge.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/transit.routes/execute", {
  body: {
    "origin": "Narita Airport, Japan",
    "destination": "Shinjuku Station, Tokyo, Japan",
    "num": 3
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);