GTFS Service-Date Report

Query scheduled service at one exact stop_id in one caller-authorized public GTFS Schedule ZIP for one explicit service date. The report retains source identifiers, date coverage, agency timezone, timing qualifiers and boarding constraints. It returns compressed frequency windows rather than expanding thousands of departures. This experimental TRYOUT tests convenience for callers without an installed GTFS query runtime; demand and comparative savings are unknown.

Use from an AI agent through MCP

Add this URL to a client that supports remote HTTP MCP, then authorize with your own Apify account using the Apify MCP setup guide:

https://mcp.apify.com/?tools=l3digital/gtfs-service-date-report

This configuration selects the Actor directly. Availability still depends on Apify account and Actor eligibility. Call l3digital/gtfs-service-date-report with the example input below; the pricing and input restrictions on this page apply.

When using call-actor, its response contains run status and storage IDs. If the run is still active, check that run with get-actor-run. After success, retrieve the report with get-dataset-items using the returned dataset ID (defaultDatasetId in the run API). These retrieval tools load with the Actor. Retrieve the existing result instead of starting another run. Inspect the report status and the coverage or refusal fields described below before using its values.

Input

The default {} runs a deterministic illustrative demo, makes no upstream request and is never eligible for a useful-report event. Report mode requires:

{"mode":"report","feedUrl":"https://example.org/authorized-feed.zip","serviceDate":"2026-01-05","stopId":"S"}

This URL is illustrative. Supply a public URL that you are authorized to use. The URL must serve the ZIP directly, without redirects, authentication or an upstream account. International hostnames are accepted when IDNA encoding is valid; non-ASCII URL path and query characters must be percent-encoded. serviceDate must be a real ISO calendar date. stopId is matched exactly, including whitespace and case. No station-child expansion or weekday fallback occurs. Unknown fields and mismatched demo/report fields are refused before acquisition. The Console form describes these constraints; runtime validates the conditional fields and UTF-8 byte lengths. The hostname must resolve only to public unicast addresses. The connection is pinned to a validated address, with the original hostname retained for HTTPS certificate checks; private, loopback and link-local destinations are refused.

Read the result

One dataset item contains schemaVersion, mode, status, useful, serviceDate, stopId, source, coverage, agencyTimezone, scheduledVisits, frequencyWindows and diagnostics. complete is useful only when the exact stop exists, the date lies in source coverage and the declared subset was processed within bounds. A complete result with zero visits means no scheduled visits were found in this supplied source on that GTFS service date. It does not establish whether vehicles physically run. Unknown stops and coverage gaps are incomplete, never useful zero-service results. Other statuses are demo, unsupported and source_error; each is unuseful.

Coverage uses a valid paired feed_info range when supplied; otherwise it retains the union of weekly validity ranges and explicit exception dates, including gaps. Weekly activation uses the actual date, then additions/removals apply. Calendar-dates-only feeds are supported. Source provenance records the requested URL, completed ZIP SHA-256, actual transferred bytes and member hashes/row counts plus available publisher/version fields. Failed acquisition has no completed ZIP hash.

Service-day offsets preserve times above 24 hours on the requested date. timepoint=0 is approximate, 1 is source exact and omitted/empty is source default exact. These qualifiers never guarantee actual arrival. Agency timezone is preserved; there is no absolute UTC conversion claim. Repeated stop visits retain their sequence. Pickup/drop-off restrictions remain visible and do not promise boardability.

Frequency schedules use the first-stop departure as origin. Every queried visit has separate arrival/departure template offsets and shifted window endpoints. exact_times=1 returns a compressed fixed schedule and an end-exclusive count; 0 or empty returns a headway window with no invented exact count or instants. The template is never also emitted as a fixed departure.

Supported subset and limits

Required tables are agency, stops, routes, trips, stop_times and at least one of calendar or calendar_dates; feed_info and frequencies are optional. Root-level UTF-8 CSV with optional BOM is supported. Missing relevant times, broken joins, conflicting identities/sequences/calendars and invalid timezone context cannot produce useful results. Flexible location/window forms, booking rules, unknown boarding codes and continuous boarding forms outside the source no-continuous form are explicitly unsupported. This is a schedule-query subset, not full GTFS validation, live arrivals, routing, feed discovery or freshness monitoring.

Each run issues one source request without retry or redirect. Bounds are 16 MiB actual transfer, 32 distinct root entries, 64 MiB actual expanded bytes including ignored members, 250,000 data rows, 50,000 trips, 64 columns, 64 KiB per UTF-8 field, 128 KiB per logical row, 1,000 combined visit/window records and 1 MiB serialized output. MiB and KiB are binary units. Exceeding a bound produces an unuseful outcome rather than silently truncating a complete report. Source work runs in a process that is killed and joined at its deadline; run-owned temporary files are cleaned. The total application deadline is 120 seconds, reserving 10 seconds after at most 110 seconds of source work. SDK setup and input time consume that same budget; outer cancellation kills and joins the child before returning. The report budget and child artifact use compact UTF-8 JSON, matching the pinned platform dataset item serializer. The SDK adds a two-byte JSON array wrapper around the single item; that transport framing is outside the per-report 1 MiB limit. Platform settings are 512 MiB and 180 seconds, no standby or restart. These bounds are refusal limits, not a guarantee that every feed within them fits platform memory or finishes before the deadline.

Persistence and pricing

Every controlled terminal result persists once. Only a complete useful report may attempt one configured report-produced event of count 1 afterward. Demo, refusal, incomplete and source-error outputs emit none. Unpriced development runs emit none and log the skip. Configured paid runs missing the event or event capacity fail before source work. Storage and charge failures are not retried; only an observed charged_count=1 establishes accepted charging, logged after persistence. Initial test pricing is $0.05 per complete useful report, including a verified in-coverage zero-service result. Demo, refused, incomplete and source-error results have no report-event charge. Owner QA does not establish customer payment or settlement.

Choose the boarding stop's exact ID. Parent stations and entrances are not expanded to their child stops: an existing parent or entrance ID with no direct visits can produce a complete zero-visit report and incur the $0.05 event.

Development and alternatives

From the repository root, run the four Actor-scoped gates in order:

rexec -- uv run --directory actors/gtfs-service-date-report --locked ruff format --check .
rexec -- uv run --directory actors/gtfs-service-date-report --locked ruff check .
rexec -- uv run --directory actors/gtfs-service-date-report --locked pyright
rexec -- uv run --directory actors/gtfs-service-date-report --locked pytest

Python 3.13, uv, Pydantic v2 and Apify SDK are independently locked. Native GTFS libraries such as https://github.com/mrcagney/gtfs_kit and hosted APIs such as https://www.transit.land/documentation remain strong substitutes. Retained validation covers synthetic schedules, offline faults and seven hosted owner-QA cases. Those small hosted runs measured technical behavior and sample costs; representative agency-feed compatibility, maximum-envelope performance, commercial margin, customer demand and comparative savings remain unmeasured.