Skip to content

to_canonical_alerts

to_canonical_alerts

to_canonical_alerts(raw: dict, *, system_id: str) -> DataFrame

Parse system_alerts.json into a canonical alerts frame.

Service disruptions (strikes, closures, weather) that explain anomalies in the data. Each alert's first time window is used for start/end (tz-aware UTC, NaT if open-ended). Returns ALERT_COLUMNS.

See Also

GBFSFeed : The feed that calls these parsers.

Source code in src/gbfs_toolkit/io/normalize.py
def to_canonical_alerts(raw: dict, *, system_id: str) -> pd.DataFrame:
    """Parse ``system_alerts.json`` into a canonical alerts frame.

    Service disruptions (strikes, closures, weather) that explain anomalies in the data.
    Each alert's first time window is used for ``start``/``end`` (tz-aware UTC, NaT if
    open-ended). Returns `ALERT_COLUMNS`.

    See Also
    --------
    [`GBFSFeed`][gbfs_toolkit.GBFSFeed] : The feed that calls these parsers.
    """
    data = raw.get("data", raw)
    alerts = _records(data, "alerts")
    rows = []
    for a in alerts:
        times = a.get("times") or []
        first = times[0] if times and isinstance(times[0], dict) else {}
        rows.append(
            {
                "system_id": system_id,
                "alert_id": str(a.get("alert_id")),
                "type": a.get("type"),
                "summary": _name(a.get("summary")),
                "description": _name(a.get("description")),
                "start": _utc(first.get("start")),
                "end": _utc(first.get("end")),
                "last_updated": _utc(a.get("last_updated")),
            }
        )
    df = pd.DataFrame(rows, columns=ALERT_COLUMNS)
    for col in ("start", "end", "last_updated"):
        df[col] = pd.to_datetime(df[col], utc=True)
    return df