Skip to content

511-sf-bay-transit.md

Latest commit

 

History

History
202 lines (165 loc) · 7.78 KB

511-sf-bay-transit.md

File metadata and controls

202 lines (165 loc) · 7.78 KB
Raw

511 SF Bay Open Data — Transit API Reference

Curated from 511 Data Exchange Specification — Transit, v1.35 (Nov 16, 2022), Metropolitan Transportation Commission. This is a working subset covering the endpoints this app uses — see the full PDF for the complete spec (Operator/Line/Stop/StopPlace/Pattern/Timetable, GTFS & GTFS-RT, SIRI data structures).

Conventions

  • Base URL: http://api.511.org/transit
  • Method: HTTP GET (Open511 uses GET rather than the SIRI-standard POST).
  • Auth: every request needs api_key=<your key> (mandatory). A missing/invalid key returns 401 Unauthorized.
  • Format: format=json (or xml). Default is JSON when omitted.
  • Operator / agency code for SF Muni is SF. (Other examples in the spec: AC AC Transit, BA BART, GG Golden Gate, SF Muni.)
  • ⚠ Responses are UTF-8 with a BOM. The JSON body begins with a byte-order mark ( / EF BB BF). Strip it before json.Unmarshal, or parsing fails. (Confirmed on every live endpoint.)
  • ⚠ Responses are gzip-compressed. Use a client that sends Accept-Encoding: gzip and decompresses transparently (Go's net/http does this by default; curl needs --compressed).
  • ⚠ Spec vs. reality (verified against the live API, June 2026):
    • StopMonitoring returns ServiceDelivery at the top level — there is no Siri wrapper, despite the spec's §B.1.10 example. (Accept both to be safe.)
    • MonitoredVehicleJourney.LineRef is the short route code ("N", "14R"); PublishedLineName is the descriptive name ("JUDAH", "MARINA EXPRESS"). Use LineRef for route-code/badge matching.
    • Stop Location.Longitude/Latitude are JSON strings, not numbers.
    • lines objects also include FromDate/ToDate; stops ScheduledStopPoint objects include Extensions, Url, and StopType.
    • Captured sample responses live in internal/transit/testdata/live_*.json.
  • Rate limit: 60 requests per 3600 seconds per API key, shared across all endpoints. Polling once per 60s sits exactly at the limit — keep the combined request rate (incl. setup calls) below it.
  • Common errors: 401 invalid key, 404 resource not found, 500 server error.

Operators — GET /operators

List transit operators in the jurisdiction.

Parameter Req Description
api_key ✔ API key
operator_id Filter to one operator code
format json (default) / xml

Example: http://api.511.org/transit/operators?api_key=KEY&format=json

Each operator: Id, Name, ShortName, Monitored (real-time enabled?), PrimaryMode, Locale.TimeZone, contact details.

Lines (routes) — GET /lines

List the routes for an operator. Used at first-run to build the line picker (cached).

Parameter Req Description
api_key ✔ API key
operator_id ✔ Operator code, e.g. SF
line_id Filter to a single line
format json (default) / xml

Example: http://api.511.org/transit/lines?api_key=KEY&operator_id=SF

Line fields: Id (unique route id), Name, TransportMode, PublicCode (public route identifier, e.g. N, 14R), SiriLineRef, OperatorRef, Monitored (real-time available?).

Stops — GET /stops

List the stops served by an operator. Filter by line_id to get only that route's stops (used after a line is picked). Cached.

Parameter Req Description
api_key ✔ API key
operator_id ✔ Operator code, e.g. SF
line_id Restrict to stops on a line
direction_id, pattern_id Further filters
include_stop_areas Also return stop groupings
format json (default) / xml

Example: http://api.511.org/transit/stops?api_key=KEY&operator_id=SF&line_id=N

Returned as NeTEx ServiceFrame.scheduledStopPoints[]. Each ScheduledStopPoint: id (this is the stop code used by StopMonitoring), Name, StopType, Location{ Longitude, Latitude }, optional Extensions.PlatformCode / ParentStation.

Real-time predictions at a stop — GET /StopMonitoring

SIRI Stop Monitoring: current and forthcoming arrivals/departures at a stop. This is the endpoint the app polls (once per 60s).

Parameter Req Description
api_key ✔ API key
agency ✔ Agency/operator code, e.g. SF
stopcode Numeric stop code. If omitted, returns all stops (slow)
format json (default) / xml

Example: http://api.511.org/transit/StopMonitoring?api_key=KEY&agency=SF&stopcode=15553&format=json

Response shape (JSON, SIRI)

Siri
└─ ServiceDelivery
   ├─ ResponseTimestamp
   ├─ ProducerRef
   └─ StopMonitoringDelivery
      └─ MonitoredStopVisit[]              # array (single object if only one)
         ├─ RecordedAtTime
         ├─ MonitoringRef                  # the stop code
         └─ MonitoredVehicleJourney
            ├─ LineRef                     # route id
            ├─ DirectionRef                # e.g. "E" / "W" / "IB" / "OB"
            ├─ PublishedLineName           # public route name -> badge lookup
            ├─ OperatorRef
            ├─ OriginName
            ├─ DestinationName             # headsign
            ├─ Monitored
            └─ MonitoredCall
               ├─ StopPointRef
               ├─ StopPointName
               ├─ AimedArrivalTime         # scheduled (RFC3339)
               ├─ ExpectedArrivalTime      # predicted (RFC3339)  <-- countdown source
               ├─ AimedDepartureTime
               └─ ExpectedDepartureTime

Minutes to arrival = ExpectedArrivalTime − now (fall back to ExpectedDepartureTime, then the Aimed* equivalents, if a field is absent). Timestamps are RFC3339 with a numeric offset, e.g. 2022-03-22T15:55:51-07:00.

Note: MonitoredStopVisit may be a single object rather than an array when only one visit is returned — decode defensively.

Example (abridged, from spec §B.1.10)

{
  "Siri": {
    "ServiceDelivery": {
      "ResponseTimestamp": "2004-12-17T09:30:46-05:00",
      "ProducerRef": "BA",
      "Status": true,
      "StopMonitoringDelivery": {
        "version": 1.4,
        "ResponseTimestamp": "2004-12-17T09:30:47-05:00",
        "Status": true,
        "MonitoredStopVisit": {
          "RecordedAtTime": "2004-12-17T09:25:46-05:00",
          "MonitoringRef": "EMBR",
          "MonitoredVehicleJourney": {
            "LineRef": "Warm Springs/South Fremont - Daly City",
            "DirectionRef": "E",
            "PublishedLineName": "Warm Springs/South Fremont - Daly City",
            "OperatorRef": "BA",
            "DestinationName": "Warm Springs/South Fremont",
            "Monitored": true,
            "MonitoredCall": {
              "StopPointRef": "EMBR",
              "StopPointName": "Embarcadero BART Station",
              "AimedArrivalTime": "2004-12-17T09:40:46-05:00",
              "ExpectedArrivalTime": "2004-12-17T09:40:46-05:00",
              "AimedDepartureTime": "2004-12-17T09:42:47-05:00",
              "ExpectedDepartureTime": "2004-12-17T09:40:47-05:00"
            }
          }
        }
      }
    }
  }
}

Real-time vehicle monitoring — GET /VehicleMonitoring

Not used by this app, included for completeness.

Parameter Req Description
api_key ✔ API key
agency ✔ Agency code
vehicleID Filter to one vehicle
format json (default) / xml

Returns Siri.ServiceDelivery.VehicleMonitoringDelivery.VehicleActivity[] with MonitoredVehicleJourney (incl. VehicleLocation{Longitude,Latitude}, Bearing, Occupancy, MonitoredCall, OnwardCalls).