Audit a feed¶
First contact with an unknown feed: see what is in it, and decide what can be trusted. Most operator feeds have something wrong — a block of stations at (0, 0), a placeholder capacity copied across the whole network, car-share parking dressed up as bike-share. Catch the damage before it leaks into a model.
Requirements
Extras: [fetch]. Input: a gbfs.json discovery URL. The static audit also
runs offline on the bundled sample: info, _ = gb.load_example().
What the script does:
- Resolves the discovery document once and prints the feed's health summary.
- Runs the A1–A7 static audit with
audit_staticand reports the flagged stations. - Adds the live-availability checks (D1–D3) with
audit_dynamic. - Keeps only the trustworthy stations for downstream analysis.
Run it:
Full source (the single source of truth, linted and runnable):
"""First contact with an unknown feed: what's in it, and what can I trust?
python 01_audit_a_feed.py https://example.com/gbfs.json --system-id mycity
Most operator feeds have *something* wrong with them — a block of stations at (0, 0),
a placeholder capacity copied across the whole network, car-share parking dressed up as
bike-share. The point here is to see the damage before it leaks into a model.
"""
import argparse
import gbfs_toolkit as gb
def main():
ap = argparse.ArgumentParser()
ap.add_argument("gbfs_url")
ap.add_argument("--system-id", default="system")
args = ap.parse_args()
feed = gb.GBFSFeed.from_url(args.gbfs_url, system_id=args.system_id)
print(feed.summary(), end="\n\n")
stations = feed.station_information()
verdict = gb.audit_static(stations)
flagged = verdict[verdict["flagged"]]
print(f"{len(flagged)} of {len(verdict)} stations flagged\n")
if not flagged.empty:
# which problems, and how often
print(flagged["reason"].value_counts().to_string(), end="\n\n")
# keep the analysable subset; this is what everything downstream should use
clean = stations[~verdict["flagged"].to_numpy()].reset_index(drop=True)
print(f"{len(clean)} stations kept for analysis")
# if the feed is live, the dynamic checks catch negative counts / staleness too
if feed.has("station_status"):
dyn = gb.audit_dynamic(feed.availability(), ttl_seconds=feed.ttl)
print(
f"{int(dyn['flagged'].sum())} stations with live-data problems "
f"({', '.join(sorted(set(dyn[dyn.flagged]['reason']))) or 'none'})"
)
if __name__ == "__main__":
main()