Skip to content

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 with 422 GTFS_EXTERNAL_SYNCHRONIZATION_URL_REJECTED.
  • time: the local time to fetch it at, as "HH:MM", 00:00 by 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 to null returns to the group's timezone.
  • enabled: false suspends 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) or failed;
  • last_error: why it failed, empty after a success;
  • last_checksum and last_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.