Timetable data API
- Vincent Paturet
- Mansoor Sajjad
Entur provides an API for uploading and downloading NeTEx timetable datasets. These endpoints have restricted access and require a service account (OAuth2) provided by Entur.
Getting access to the API
Please contact Entur at kollektivdata@entur.org to get access to the API.
You will be granted dedicated OAuth2 credentials ("client-id" and "client-secret") that will allow you to access the service.
Entur authentication and authorization service
The endpoints are protected by an OAuth2 authorization layer. Once you receive OAuth2 credentials, you will be able to request access tokens from Entur authorization server using the following parameters:
Env | OAuth2 token URI | OAuth2 audience / Base URI |
|---|---|---|
Dev |
|
|
Staging |
|
|
Prod |
|
|
Dataset upload endpoint
This endpoint allows for uploading a NeTEx dataset into Entur import and validation pipeline.
It provides the same feature as a manual upload from the Operator Portal application.
The examples below use parameters for the production environment, use the table above to adapt them for the development and staging environments.
Endpoint URI | https://api.entur.io/timetable-admin/v1/timetable/upload/{codespace} |
Parameter | {codespace}: lowercase codespace attributed to the data provider. Examples: rut, sky, vyg, … |
Payload | An HTTP multipart body containing the NeTEx zip archive |
Response | Empty |
Response code | "200": OK - the dataset has been received successfully (this is only a technical acknowledgement, before applying any validation rule. The dataset may be rejected further down in the validation pipeline) |
Dataset download endpoint
This endpoints gives access to private NeTEx datasets not available on Entur open data portal.
These datasets include, in addition to the data available on the open data portal, the following private data:
NeTEx Block data
DeadRuns
Lines and Service Journeys with restricted publication
Endpoint URI | <https://api.entur.io/timetable-admin/v1/timetable/download_netex_blocks/{codespace} |
Parameter | {codespace}: lowercase codespace attributed to the data provider. Examples: rut, sky, vyg, … |
Response | The NeTEx zip archive as the HTTP body response |
Response code | "200": OK - the dataset has been dowloaded successfully |
Download Raw data endpoint
This endpoint provides access to the most recent validated Netex Raw datasets.
Endpoint URI | <https://api.dev.entur.io/timetable-data/{codespace} |
Parameter | {codespace}: lowercase codespace attributed to the data provider. Examples: rut, vyg, … |
Response | The NeTEx zip archive as the HTTP body response |
Response code | "200": OK - the dataset has been dowloaded successfully |
Guidelines
Uploading and downloading a dataset through the HTTP endpoints is a 2-step process:
step #1: Request an authorization token from Entur's OAuth2 server.
step #2: Download or upload the dataset to the HTTP endpoint, using the token received in step #1 to authenticate the request.
Technical details:
The actual code used to perform the 2 steps depends on the client operating system and programming language. For illustration purpose you will find below a simple example using the Linux command line tool "curl":
Step #1: Request an authorization token from Entur's OAuth2 server:
Given the credentials provided by Entur ("client-id" and "client-secret"), send the following request to Entur's OAuth2 server:
curl --url 'https://partner.entur.org/oauth/token' --header 'content-type: application/x-www-form-urlencoded' --data 'grant_type=client_credentials' --data 'client_id=my-client-id' --data 'client_secret=my-client-secret' --data 'audience=https://api.dev.entur.io'The server replies with a JSON document containing the authentication token under the "access_token" key:
{"access_token":"my-oauth2-token","expires_in":86400,"token_type":"Bearer"}
Step #2: Upload the dataset to the HTTP endpoint:
Using the token received in step #1, send the following request to the HTTP-endpoint in order to upload a dataset:
curl -v -F file=@my-netex-dataset.zip --header 'authorization: Bearer my-oauth2-token' https://api.entur.io/timetable-admin/v1/timetable/upload/{codespace}where {codespace} is the data provider codespace in lowercase (example: rut, sky, vyg, …)