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.