Publications

Owned by Anna Mamontova
Last updated: Dec 27, 2023
8 min read

Description

The "Publication" function is used to publicly share all of your data in GTFS or NeTEx format with your partners.

Authorized user and member of organization Workgroup owner can manage the publications of data, publications are made automatically.

Managing publications

Several publications can be defined in Workgroup. Each of it defining an export and the destinations to give to exported data.

You can see the publications defined in “Settings” - “Publications” section.

It is possible to filter within the export type, and to order by name of publication and its type.

The star wheel of each line allows to see, edit or destroy (with confirmation) the publication.

Authorized user and member of organization Workgroup owner can create and modify a data Publication.

For each Publication you can define :

  • the name of Publication (to better identify its role)

  • weather the Publication is active or not. The deactivated publications are ignored.

  • the type and the settings of export that must be made at each Publication

  • the destinations and their settings that must take in charge the exported data

You can add and delete the destinations.

Export settings

Chouette proposes different kinds of export.

GTFS export:

During the export, a zip is created containing the following .txt files:

  • agencies.txt

  • stops.txt

  • routes.txt

  • trips.txt

  • stop_times.txt

  • calendars.txt

  • shapes.txt

  • transfers.txt

These files conform to the GTFS standard. To find out more about the GTFS export format, see the section https://enroute.atlassian.net/wiki/spaces/PUBLIC/pages/1889861653/Exports#GTFS-Export.

 

When you choose to do a GTFS-type export, you can configure the following information:

  • The periods to export. You can specify whether you take all available period or just a few days.

  • The lines to export. You can decide not to export all the lines, but select them according to the associated companies, the associated line providers or specific lines that you define yourself.

  • Referent stop areas. You can indicate whether or not you prefer the use of reference stop areas for your export. With this option, the GTFS export will use Referent stop areas (if any) instead of custom stop areas.

  • Consideration of Monomodal stop places with a Single Quay. With this option, you can choose to ignore Multimodal Stop Places that contain only one Quay.

  • publish per line

NeTEx Generic export:

NeTEx (Network Exchange) is a reference format for exchanging theoretical public transport supply data, defined at European level.

When exporting a file, a zip file is created containing different XML files.

To learn more about the NeTEx export format, see the page https://enroute.atlassian.net/wiki/spaces/PUBLIC/pages/1889861653/Exports#NeTEx-Export.

When you choose a Generic NeTex export type, you can configure the following information:

  • The periods to export. As for the GTFS export, you can choose which periods to export.

  • The NeTex export profile. The NeTex format presents different profiles that you choose with Chouette.

  • The exported lines. As for the GTFS export, you can choose to export the lines according to the line provider, the company or according to a list of lines that you define.

  • Publish per Line. This action allows you to create, during the export, an XML file for each line.

Ara export:

If you feed Ara from data registered in Chouette, you can select the Ara export type. During the export, a csv file is created containing the different attributes of your export. In the csv file, each line corresponds to the information of an attribute:

  • operator

  • stop_area

  • line

  • vehicle_journey

When you choose an Ara-type export, you can configure the following information:

  • The exported lines. You can choose to export the lines according to the line provider, the company or according to a list of lines that you define.

Publication destination

A Data Publication including a full export can include different types of publication destination. The export is sent to the destination(s) you set.

Destination type API Publication

You can configure that your publication has an API as destination.

During each publication, the Publication API is informed that the data to be received is the data exported by this publication.

For this type of destination, you must choose an existing publication API. To manage the Publication APIs, refer to the chapter below https://enroute.atlassian.net/wiki/spaces/PUBLIC/pages/1890058273/Publications#Managing-the-Publication-APIs.

The same API can be supplied by several Publications. The (current) constraint is that each Publication must use a different export format.

Destination type Email notification

You can choose an email destination for your publication.

You have the possibility to:

  • put the export file in attachment

  • include a link to API

  • choose the recipients of this email

  • write the email text

Destination type Ara SaaS

The Ara SaaS destination type configures your publication as a destination for an Ara repository.

To do this, you must enter the URL of the desired destination Referential and the Identification Token.

Destination type Google Cloud Storage

Users can choose the Google Cloud Storage type of destination for your publication.

You must enter the project, the bucket and the secret key for your Google Cloud Storage space. The published file will then be automatically sent to the bucket.

 

Destination type SFTP

The user can choose SFTP destination for your publication.

For this type of destination, you must enter :

  • Host with server URL

  • Port

  • Directory where the published file will be sent

  • server's secret key

Consulting a publication

Authorized user and member of organization Workgroup owner can see the publications defined with its details.

The details of Publication gather :

  • “Information” block with Publication name and the date of its creation and modification.

  • “Export Settings” block with export type made at each Publication and the settings of this export

  • “Destination” block, for each destination the type of destination and the settings of the destination

Under that information the list of the last reports of this Publication is displayed.

For each Publication the list includes :

  • the name of published offer with a link to the publication report

  • final state of this Publication

  • the date of beginning and end of that Publication

The star wheel propose the action “See”.

No information concerning the passwords or private tokens is available or accessible on this page.

Publication report

For each Publication Chouette creates a report. It consists of :

“Information” block with :

  • name and the link to published offer

  • final state of Publication

  • date of beginning and end of this Publication

A summary of export operation made at the moment of Publication with :

  • export name with a link to see the details of export operation

  • export type

  • date of beginning and end of this export

A summary of Destinations that have taken in charge the published data, for each Destination with :

  • destination name

  • destination type

  • state of submission to this Destination

  • date of beginning and end of submission to this Destination

Managing the Publication APIs

Authorized user and member of organization Workgroup owner can see the Publication APIs that are defined in Workgroup.

In case you have the necessary permissions you can manage the Publication APIs.

Several Publication APIs can be defined in Workgroup. Each one can be the destination of several data Publications. This flexibility allows to spread the Workgroup offer in several formats, several modalities (duration of offer, etc) by managing the access at each API level.

You can see the APIs of Publication that were defined.

The star wheel of each line allows to see, edit and destroy (with confirmation) the Publication API.

Managing the publications is accessible by menu “Settings” > “Publications” > “Publication APIs”.

Authorized user and member of organization Workgroup owner can create and modify a Publication API.

You can define :

  • name that will be present in Chouette and outside

  • short name (or nicename) according to the name used in URL of API. For example, short name “acmee” will result the URLs like /api/v1/datas/acmee.gtfs.zip.

Public URL is updated according to the short name, as you fill in this field.

When you click on “Validate” Chouette creates a Publication API, and direct you to the information page of this API.

Authorized user and member of organization Workgroup owner can see the settings of Publication API.

The details of Publication API include :

  1. Information with :

  • name

  • short name

  • public URL

  • dates of creation and last modification

  1. Associated publications, each one with :

  • name with link to the last publication report (that filled this API)

  • export type

  1. Access token, each one with :

  • name

  • token

  • dates of creation and last modification

Authorized user can create, modify or destroy every access token.

Access tokens can be communicated to third persons to give them access to all published data with help of API. As soon as the token is deleted, the access is impossible. You can communicate the different tokens to each third person and manage the access rights.

Access to the public page of your Publication API

As soon as you create a publishing API (public or private), you can send your data consumers a public page describing all the resources you make available to them.

Data access of the Publication API

For each Publication using a full export and having a Publication API as destination, it gives access to the data of the export by making the exported file available on a URL of the form: /api/v1/datas/<name short>.<format>.zip

For example, for an API with the short name "test", we can access the data via a URL of the type /api/v1/datas/test.gtfs.zip

When a Publication makes data available, the data on API is updated, but the URL remains unchanged.

Public

In the case of a public publication API, any consumer can access the published data.

Private

In the case of a private publication API, it is accessible only if the consultation request uses one of the keys associated with the Publication API. The key token must be included in an HTTP header of the form Authorization: Token token=<token>.

The authorized user can create a Publish API access key on the page of Publication API.

You can define a name for the access key specifying for example the associated consumer. The token or access key is generated automatically by Chouette.