transitio.fetch

Contents

transitio.fetch#

transitio.fetch(aoi, when=None, *, modes=None, repair=False, crop=True, refresh_token=None, cache_dir=None, directory=None, country_code=None, **budgets)#

Fetch everything cafein needs for an AOI in one call.

Resolves and crops the OSM extract, discovers all GTFS feeds overlapping the AOI, downloads each feed, validates it, optionally repairs and spatially crops it, and builds a merged report per feed. With an API token, downloads come from catalogued dataset versions (checksum-verified, with the hosted canonical-validator report); without one, the unversioned latest hosted zip is fetched — a moving target with no upstream checksum, documented in its provenance sidecar as such. Every overlapping feed is processed, in a deterministic order with official feeds first; one broken feed never aborts the others — it lands in skipped with its reason.

Parameters:

  • aoi (geometry, GeoDataFrame/GeoSeries, tuple or str) – Area of interest (place names are geocoded via Nominatim once, and the resulting geometry drives every stage).

  • when (str or datetime.date, optional) – Service day the feeds must cover, YYYY-MM-DD. Dataset-version selection needs an API token; with or without one, feeds whose computed service window (the outer bounds of actual calendar activity, not the published range) does not include the day are skipped. Exact-day activity is not checked yet.

  • modes (str or list of str, optional) – Keep only feeds serving at least one of tram, subway, rail, bus, ferry — decided from the delivered (post-crop) feed’s routes.txt, since the catalog carries no mode metadata. Unknown mode names raise ValueError.

  • repair (bool, default False) – Repair each feed (gtfstidy contract) before use; conservative default leaves feeds untouched.

  • crop (bool, default True) – Spatially crop each feed to the AOI’s bounding box.

  • refresh_token – Passed to the catalog and OSM layers.

  • cache_dir – Passed to the catalog and OSM layers.

  • directory – Passed to the catalog and OSM layers.

  • country_code – Passed to the catalog and OSM layers.

  • **budgets – The validate_feed keyword arguments.

Returns:

osm_pbf, validated feeds (paths), merged reports and repair repairs (fix logs, empty without repair=True) per kept feed, and skipped (feed id, reason) pairs. Reports merge the local validation of the delivered feed with the hosted report of the published dataset, so after cropping or repair the hosted side describes the pre-transform original.

Return type:

FetchResult

Contents