External GTFS synchronizations¶
A network whose GTFS is produced elsewhere — by a regional aggregator, a scheduling tool — does not have to import it by hand. An external synchronization fetches the file from a URL every day, then imports and publishes it when it changed since the day before.
One synchronization, one file, one time¶
A synchronization holds the URL of the file and the time to fetch it at. Each synchronization has its own daily run: two synchronized networks do not necessarily run at the same time. Pick a time after the source generates its file, so as not to fetch the previous day's.
| Endpoint | Role |
|---|---|
GET /api/v4/groups/<group_id>/gtfs/external-synchronizations |
Lists the group's synchronizations and the outcome of their last run |
POST /api/v4/groups/<group_id>/gtfs/external-synchronizations |
Creates a synchronization |
PATCH /api/v4/groups/<group_id>/gtfs/external-synchronizations/<synchronization_id> |
Changes its URL, time or timezone, or suspends it |
These routes require the admin role on the group.
The settings¶
url: the HTTP(S) URL of the file. Its host must resolve to public addresses only: a local, private or internal address is refused with422 GTFS_EXTERNAL_SYNCHRONIZATION_URL_REJECTED.time: the local time to fetch it at, as"HH:MM",00:00by default. A time with an offset (01:00+01:00) is refused: the timezone is what follows daylight saving time.timezone: the IANA timezone of that time ("Europe/Paris"). Without it, the group's timezone, the one of the published GTFS: the synchronization follows it when a publication changes it. Setting it back tonullreturns to the group's timezone.enabled:falsesuspends the synchronization without deleting it.
The outcome of the last run¶
Each synchronization keeps, read-only, what its last run did:
last_status:imported(a new file imported and published),unchanged(the same file as last time, nothing imported) orfailed;last_error: why it failed, empty after a success;last_checksumandlast_gtfs_id: the MD5 checksum of the last file published and the GTFS it created;last_attempt_at: when that run happened.
An unreachable file is retried several times before the run fails. A file imported but whose publication fails does not count as published: the next night imports it again.
Reporting a run¶
The Prefect flow Synchronize external transit files runs one synchronization per run, scheduled by the API at the synchronization's time, and reports its outcome through an internal route reserved to the super-admin.
| Endpoint | Role |
|---|---|
POST /api/v4/groups/<group_id>/gtfs/external-synchronizations/<synchronization_id>/results |
Records the outcome of a run |
The pysae_admin import-gtfs-external-synchronizations and pysae_admin reconcile-gtfs-external-synchronization-schedules subcommands take over the synchronizations of the former Prefect block and realign the deployment's schedules on the synchronizations. Until the takeover, the former daily run, started without parameters, still processes the former block; the reconciliation deletes its schedule. Run both subcommands in the same session, so that no network is processed twice in one night.