Publications
Description
The "Publication" feature is used to publicly share all of your data in GTFS or NeTEx format with your partners.
Authorized users and members of the organization that owns the Workgroup can manage the publication of data that are made automatically.
Managing publications
Several publications can be defined in the Workgroup. Each one defines an export and the destinations to which the exported information will be sent.
You can see the publications defined in the “Publications” section of the Workgoup.
You can filter by export type, and order by name of publication and export type.
The star wheel of each line allows you to see, edit or destroy the publication.
Authorized users and members of the Workgroup can create and modify a data Publication.
For each Publication you can define :
the name of Publication (to better identify its role)
activate or deactivate the publication (enabled). The deactivated publications are ignored.
the daily publication activation or deactivation
the type and the settings of export that must be made at each Publication
the destinations and their settings
You can add and delete the destinations.
Export settings
Chouette offers different kinds of exports.
GTFS export
During the export, a zip is created containing the following .txt files:
agencies.txtstops.txtroutes.txttrips.txtstop_times.txtcalendars.txtshapes.txttransfers.txt
These files conform to the https://enroute.atlassian.net/wiki/spaces/PUBLIC/pages/1318125617 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 periods, just a few days, or a static time period.
The lines to export. You can decide not to export all the lines, but to 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 referent stop areas for your export. With this option, the GTFS export will use Referent stop areas (if any) instead of particular stop areas.
Prefer referent companies. You can indicate whether or not you prefer to use referent companies for your export. With this option, the GTFS export will use referent companies (if any) instead of particular companies.
Prefer referent lines.
Ignore Parent Stop Places. Stop Places will be exported without their parents.
Ignore extended route types.
Use Stop Sequence from 1.
When you specify an exported period, the calendars are not cut off, in order to preserve the initial calendars. Consumer systems will therefore find the “same” calendars when the publication period moves forward in time.
NeTEx Generic export
NeTEx (Network Timetable Exchange) is a reference format for exchanging schedule public transport service data. This format is defined at European level.
When a file is exported, 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 with 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.
Prefer Referent Lines. With this option, you can choose to export referent lines instead of particular lines.
Ignore Referent Stop Areas. With this option, you can choose to ignore referent stop areas in your NeTEx export.
When you specify an exported period, the calendars are not cut off, in order to preserve the initial calendars. Consumer systems will therefore find the “same” calendars when the publication period moves forward in time.
Ara export
If you feed Ara from data recorded 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:
operatorstop_arealinevehicle_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 up.
Publication API Destination type
You can configure your publication with an API as a 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.
Email notification Destination type
You can choose an email destination for your publication.
You can:
put the export file as an attachment
include a link to an API
choose the recipients of this email
write the email text
Ara SaaS Destination type
The Ara SaaS destination type configures your publication to an Ara repository.
To do this, you must enter the URL of the desired Ara destination Referential and the Identification Token.
Google Cloud Storage Destination type
Users can choose the Google Cloud Storage type of destination for their publication.
You must enter the project, the bucket and the secret key for your Google Cloud Storage space. The published file will be automatically sent to the bucket.
SFTP Destination type
The user can choose the SFTP destination for their publication.
For this type of destination, you must enter :
the Host with the server URL
the Port
the Directory where the published file will be sent
the server's secret key
Consulting a publication
An activated publication launches automatically after each aggregation. When you click on the name of a publication, you see the following information:
an “Information” block with Publication name and the date of its creation and modification.
an “Export Settings” block with the type of export made at each Publication and the settings of this export
a “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 with the links to the sources of the publication.
You can manually launch a publication using the “Publish now” button. An export will be created with the data from your Workgroup's latest aggregated offer.
No information concerning the passwords or private tokens is available or accessible on this page.
For each publication source, Chouette creates a report. The list of imports features :
The name of the published offer, with a link to the publication report
The final status of this publication
The creation and end dates of this publication
Publication report
Each publication report can be accessed by clicking on the name of the source, or on “View” via the cogwheel icon. On this page, you will find details of the publication.
An “Information” block with :
final status of publication
publication name
the name of the offer that has been used to create the publication and a link
A “Processing” block with :
Date of creation of the publication
Date of beginning of the Publication
Date of end of the Publication
Publication duration
An “Export” block with :
export name with a link to see the details of export operation
export type
the status of the transmission to the destination
the export parameters
A transmission report to the destinations linked to this publication :
Transmission type
Name of the destination
Transmission status
Error message
Transmission start
Transmission end
Duration of the operation
Managing Publication APIs
Authorized users and members of the organization owning the Workgroup can see the Publication APIs that are defined in the Workgroup.
In case you have the necessary permissions, you can manage the Publication APIs.
Several Publication APIs can be defined in the Workgroup. Each one can be the destination of several data Publications. This flexibility allows the Workgroup offer to be published in several formats, several settings (duration of offer, etc) by managing the access at each API level.
You can see the APIs of Publication that are currently defined.
Managing the publications is accessible in the menu menu “Workgroup” > “Publication APIs”.
Authorized users and members of the organization that owns the Workgroup can create and edit a Publication API.
You can define :
a name that will be present in Chouette and outside
short name (or nickname) 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.
Prefering referent documents allows you to retrieve documents from referent models if available.
The public URL updates based on the short name, as you fill in this field.
When you click on “Submit” Chouette creates a Publication API, and directs you to the information page of this API.
Authorized users and members of the organization that owns the Workgroup can see the settings of a Publication API.
The details of Publication API include :
Information with :
name
short name
public URL
dates of creation and last modification
Related publications, each one with :
name with link to the last publication report (that filled this API)
export type
Access tokens, each one with :
name
token
dates of creation and last modification
Authorized users can create, edit or destroy every access token.
Access tokens can be communicated to third persons to give them access to all data published by API. As soon as the token is deleted, the access is impossible. This allows you to assign different keys to each third party and carefully manage access rights and revocation.
By default, when the API has just been created, there is no access key yet. Therefore, there is no table, but a help text: “This API does not yet have an access key.”
When creating an API, you can check the “Public API” option to disable authentication when accessing a Publication API. In this case, data published via the API can be downloaded freely.
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.
Acces to the Publication API’s data
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", you 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 the 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>.
Authorized users can create a Publication API access key on the page of a 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.
Retrieving data from an API using requests
The description and use of the publication API is available in many languages via our Postman documentation.
Postman allows you to use all the requests provided. If you want to create your own space, click on the “Run in Postman” button at the top right.
To configure Postman requests, you need to retrieve the necessary identifiers from the Chouette interface or from the initial import file.