Skip to content

GBFSFeed

GBFSFeed

GBFSFeed(gbfs_url: str | None = None, *, language: str | None = None, system_id: str = 'system', timeout: int = 30, get_json: JsonGetter | None = None)

A friendly handle on one GBFS system: discover once, fetch tidy frames.

Parameters:

Name Type Description Default
gbfs_url str

URL of the system's gbfs.json auto-discovery file.

None
language str

Preferred language key for multi-language (GBFS 2.x) feeds.

None
system_id str

Stamped on every returned frame (defaults to "system").

'system'
timeout int
30
get_json callable

url -> dict override (dependency injection for tests / caching).

None
See Also

fetch_feed_json : Fetch a single GBFS document. audit_feed : Audit a fetched feed end to end. build_availability_panel : Build a panel from fetched snapshots.

Source code in src/gbfs_toolkit/io/fetch.py
def __init__(
    self,
    gbfs_url: str | None = None,
    *,
    language: str | None = None,
    system_id: str = "system",
    timeout: int = 30,
    get_json: JsonGetter | None = None,
) -> None:
    self.gbfs_url = gbfs_url
    self.system_id = system_id
    self.timeout = timeout
    self._language = language
    self._get_json: JsonGetter = get_json or (lambda url: _get_json(url, timeout=timeout))
    self._feeds: dict[str, str] | None = None
    self._version: str | None = None
    self._doc: dict | None = None
    self._sysinfo: dict | None = None
    self._raw_cache: dict[str, Any] = {}

language property writable

language: str | None

Preferred feed language (GBFS 2.x). Setting it re-discovers the feeds.

feeds property

feeds: dict[str, str]

Mapping {feed_name: url} discovered from gbfs.json (cached).

version property

version: str

The GBFS spec version advertised by the feed (cached).

ttl property

ttl: int | None

Advertised refresh interval (seconds) from gbfs.json; feeds the staleness audit.

last_updated property

last_updated: Timestamp

When the discovery document was last updated (tz-aware UTC), or NaT.

timezone property

timezone: str | None

IANA timezone (e.g. "Europe/Paris") from system_information, for local time.

from_url classmethod

from_url(gbfs_url: str, **kwargs: Any) -> GBFSFeed

Build a feed from its gbfs.json URL.

Source code in src/gbfs_toolkit/io/fetch.py
@classmethod
def from_url(cls, gbfs_url: str, **kwargs: Any) -> GBFSFeed:
    """Build a feed from its ``gbfs.json`` URL."""
    return cls(gbfs_url, **kwargs)

from_system_id classmethod

from_system_id(system_id: str, *, catalog: DataFrame | None = None, **kwargs: Any) -> GBFSFeed

Build a feed by resolving system_id through the MobilityData catalogue.

Source code in src/gbfs_toolkit/io/fetch.py
@classmethod
def from_system_id(
    cls, system_id: str, *, catalog: pd.DataFrame | None = None, **kwargs: Any
) -> GBFSFeed:
    """Build a feed by resolving ``system_id`` through the MobilityData catalogue."""
    from gbfs_toolkit.io.catalog import resolve, systems_catalog

    cat = catalog if catalog is not None else systems_catalog()
    info = resolve(system_id, cat)
    return cls(info["auto_discovery_url"], system_id=info["system_id"], **kwargs)

has

has(*names: str) -> bool

True if any of names is an available feed.

Source code in src/gbfs_toolkit/io/fetch.py
def has(self, *names: str) -> bool:
    """True if any of ``names`` is an available feed."""
    return any(n in self.feeds for n in names)

station_information

station_information() -> DataFrame

Canonical static station inventory.

Source code in src/gbfs_toolkit/io/fetch.py
def station_information(self) -> pd.DataFrame:
    """Canonical static station inventory."""
    return to_canonical_station_info(
        self._raw(_STATION_INFO), system_id=self.system_id, gbfs_version=self.version
    )

station_status

station_status() -> DataFrame

Canonical timestamped availability snapshot.

Source code in src/gbfs_toolkit/io/fetch.py
def station_status(self) -> pd.DataFrame:
    """Canonical timestamped availability snapshot."""
    return to_canonical_station_status(
        self._raw(_STATION_STATUS), system_id=self.system_id, gbfs_version=self.version
    )

vehicles

vehicles() -> DataFrame

Canonical free-floating vehicle positions (vehicle_status/free_bike_status).

Source code in src/gbfs_toolkit/io/fetch.py
def vehicles(self) -> pd.DataFrame:
    """Canonical free-floating vehicle positions (``vehicle_status``/``free_bike_status``)."""
    return to_canonical_vehicles(
        self._raw(_VEHICLES), system_id=self.system_id, gbfs_version=self.version
    )

vehicle_types

vehicle_types() -> DataFrame

Canonical vehicle_types catalogue (form factor / propulsion / range).

Source code in src/gbfs_toolkit/io/fetch.py
def vehicle_types(self) -> pd.DataFrame:
    """Canonical ``vehicle_types`` catalogue (form factor / propulsion / range)."""
    return to_canonical_vehicle_types(self._raw(_VEHICLE_TYPES), system_id=self.system_id)

geofencing_zones

geofencing_zones() -> Any

Operator-defined service-area polygons as a GeoDataFrame ([geo] extra).

Raises KeyError if the system publishes no geofencing_zones feed; check has first. See to_canonical_geofencing.

Source code in src/gbfs_toolkit/io/fetch.py
def geofencing_zones(self) -> Any:
    """Operator-defined service-area polygons as a ``GeoDataFrame`` (``[geo]`` extra).

    Raises ``KeyError`` if the system publishes no ``geofencing_zones`` feed; check
    `has` first. See [`to_canonical_geofencing`][gbfs_toolkit.to_canonical_geofencing].
    """
    from gbfs_toolkit.spatial.geofencing import to_canonical_geofencing

    return to_canonical_geofencing(
        self._raw(_GEOFENCING), system_id=self.system_id, gbfs_version=self.version
    )

system_regions

system_regions() -> DataFrame

Canonical region_id → name lookup (raises if the feed has no system_regions).

Source code in src/gbfs_toolkit/io/fetch.py
def system_regions(self) -> pd.DataFrame:
    """Canonical ``region_id → name`` lookup (raises if the feed has no ``system_regions``)."""
    from gbfs_toolkit.io.normalize import to_canonical_system_regions

    return to_canonical_system_regions(self._raw(_SYSTEM_REGIONS), system_id=self.system_id)

alerts

alerts() -> DataFrame

Canonical service alerts (raises if the feed has no system_alerts).

Source code in src/gbfs_toolkit/io/fetch.py
def alerts(self) -> pd.DataFrame:
    """Canonical service alerts (raises if the feed has no ``system_alerts``)."""
    from gbfs_toolkit.io.normalize import to_canonical_alerts

    return to_canonical_alerts(self._raw(_ALERTS), system_id=self.system_id)

system_information

system_information() -> dict

System metadata (name, timezone, language, operator), cached.

Source code in src/gbfs_toolkit/io/fetch.py
def system_information(self) -> dict:
    """System metadata (name, **timezone**, language, operator), cached."""
    if self._sysinfo is None:
        self._sysinfo = to_canonical_system_information(
            self._raw(_SYSTEM_INFO), system_id=self.system_id
        )
    return dict(self._sysinfo)

availability

availability() -> DataFrame

The daily one-liner: live status joined with station info.

Thin convenience over join_availability; returns bikes/docks and name, coordinates, capacity and station type in one tidy frame (outer join with a presence indicator). For offline frames (e.g. from a Parquet lake), call join_availability(info, status) directly.

Source code in src/gbfs_toolkit/io/fetch.py
def availability(self) -> pd.DataFrame:
    """**The daily one-liner**: live status joined with station info.

    Thin convenience over [`join_availability`][gbfs_toolkit.join_availability]; returns bikes/docks
    *and* name, coordinates, capacity and station type in one tidy frame (outer join with a
    ``presence`` indicator). For offline frames (e.g. from a Parquet lake), call
    ``join_availability(info, status)`` directly.
    """
    from gbfs_toolkit.analytics.frames import join_availability

    return join_availability(self.station_information(), self.station_status())

to_local_time

to_local_time(df: DataFrame, columns: tuple[str, ...] = ('fetched_at',)) -> DataFrame

Convert UTC timestamp columns to the system's local timezone (diurnal analysis).

Source code in src/gbfs_toolkit/io/fetch.py
def to_local_time(
    self, df: pd.DataFrame, columns: tuple[str, ...] = ("fetched_at",)
) -> pd.DataFrame:
    """Convert UTC timestamp columns to the system's local timezone (diurnal analysis)."""
    tz = self.timezone
    if not tz:
        return df
    out = df.copy()
    for col in columns:
        if col in out:
            out[col] = pd.to_datetime(out[col], utc=True).dt.tz_convert(tz)
    return out

audit

audit() -> DataFrame

Unified semantic audit: static (A1–A7) on the inventory and dynamic (D1–D3) on live availability, stacked with an audit_type column.

Thin convenience over audit_frames (dynamic staleness uses the feed's advertised ttl). For offline frames, call audit_frames(info, status).

Source code in src/gbfs_toolkit/io/fetch.py
def audit(self) -> pd.DataFrame:
    """Unified semantic audit: **static** (A1–A7) on the inventory **and** **dynamic**
    (D1–D3) on live availability, stacked with an ``audit_type`` column.

    Thin convenience over [`audit_frames`][gbfs_toolkit.audit_frames] (dynamic staleness uses the
    feed's advertised ``ttl``). For offline frames, call ``audit_frames(info, status)``.
    """
    status = self.station_status() if self.has(*_STATION_STATUS) else None
    return audit_frames(
        self.station_information(),
        status,
        ttl_seconds=self.ttl if status is not None else None,
        system_id=self.system_id,
    )

reconcile_fleet

reconcile_fleet() -> Series

One authoritative fleet tally across the docked and free-floating feeds.

Pulls station_status and/or vehicle_status (whichever exist) and reconciles them, excluding vehicles parked at stations from the deployed total so the two feeds don't double-count. See reconcile_fleet_state.

Source code in src/gbfs_toolkit/io/fetch.py
def reconcile_fleet(self) -> pd.Series:
    """One authoritative fleet tally across the docked and free-floating feeds.

    Pulls ``station_status`` and/or ``vehicle_status`` (whichever exist) and reconciles
    them, excluding vehicles parked at stations from the deployed total so the two feeds
    don't double-count. See [`reconcile_fleet_state`][gbfs_toolkit.reconcile_fleet_state].
    """
    from gbfs_toolkit.analytics.fleet import reconcile_fleet_state

    status = self.station_status() if self.has(*_STATION_STATUS) else None
    vehicles = self.vehicles() if self.has(*_VEHICLES) else None
    return reconcile_fleet_state(status, vehicles)

snapshot

snapshot() -> dict[str, DataFrame]

All available tidy frames at once: information, status (+ vehicles).

Source code in src/gbfs_toolkit/io/fetch.py
def snapshot(self) -> dict[str, pd.DataFrame]:
    """All available tidy frames at once: ``information``, ``status`` (+ ``vehicles``)."""
    out = {"information": self.station_information(), "status": self.station_status()}
    if self.has(*_VEHICLES):
        out["vehicles"] = self.vehicles()
    return out

summary

summary() -> Series

A one-glance health card: counts, staleness, version; ideal in a notebook.

Source code in src/gbfs_toolkit/io/fetch.py
def summary(self) -> pd.Series:
    """A one-glance health card: counts, staleness, version; ideal in a notebook."""
    data: dict[str, Any] = {
        "system_id": self.system_id,
        "gbfs_version": self.version,
        "feeds": ", ".join(sorted(self.feeds)),
    }
    if self.has(*_STATION_INFO):
        data["total_stations"] = int(len(self.station_information()))
    if self.has(*_STATION_STATUS):
        status = self.station_status()
        data["total_bikes_available"] = int(
            pd.to_numeric(status["num_bikes_available"], errors="coerce").fillna(0).sum()
        )
        lag = status["fetched_at"] - status["last_reported"]
        data["feed_staleness_min"] = round(float(lag.dt.total_seconds().median() / 60), 1)
    if self.has(*_VEHICLES):
        data["total_vehicles"] = int(len(self.vehicles()))
    return pd.Series(data)