Business

Dienstregeling API additional documentation

9292 Dienstregeling API introduction

The Dienstregeling API can be used to request information about public transport services for any operator in the Netherlands. This can be done on a global level e.g. all services for a single operator, but also on a detailed level, e.g. for a service that departs from a specific stop at a particular time. This API is meant to deliver public transport information to Apps, websites and content providers that offer this information directly or in addition to other travel information to their users.

A description of the data that can be delivered by the Dienstregeling API follows below. In general objects and attributes are only included if they have a value. E.g. when an operator has no notice message for a service or a stop place, the object is omitted from the response, including the list structure in which these messages are bundled. The same principle is used for attributes. E.g. the departure data may include a changed departure platform if the actual platform is different from the planned platform. But usually, this is not the case and then the attribute will be omitted from the response.

Service schedules of public transport operators

For each public transport operator, all its scheduled services can be requested, regardless of the dates on which they are offered. This returns a collection of public transport lines that includes the following data for each line:

  • DataOwnerCode - the standard letter code to identify the operator
  • OperatorID - (optionally) the numerical value of the operator
  • Per line the following data:
    • LinePlanningNumber (identification of the line in the schedule)
    • Public Line Number (as communicated to travelers)
    • Possible directions
    • Possible modalities:
      • Transport type (bus, tram, train, ...)
      • Product formula (Sprinter, Q-liner, Belbus, ...)

 

Scheduled services per line

In a request for a specific service line, the line is identified by a combination of:

  • DataOwnerCode of the operator that performs the service.
  • LinePlanningNumber
For each line, the following data is returned:
  • DataOwnerCode
  • OperatorID
  • LinePlanningNumber
  • Public Line Number
  • A description of the line
  • Color codes of the line in timetable displays
  • Possible directions
  • Possible modalities:
    • Transport type (bus, tram, train, ...)
    • Product formula (Sprinter, Q-liner, Belbus, ...)
  • The days on which the service is offered
  • All possible routes and for each route:
    • The direction
    • The geographical route by road or railway track
    • The sequence of stop places that are passed. For each stop place:
      • Identifications of the stop place
      • Name and place of the stop
      • Accessibility for physically impaired persons
      • The geographical coordinates of the stop (in WGS84 or RDM projections)
  • Notices of operators about planned and unplanned changes or disruptions

 

Data for each scheduled service (journey)

One or more services can be specified in a request by a combination of:

  • DataOwnerCode of the operator that offers the service
  • LinePlanningNumber
  • Direction (optional)
  • Date on which the service is offered
In general, a number of services are returned for a line on the specified date. The response will include the line data that is described above and for each service:
  • JourneyNumber (identification of the trip of the vehicle)
  • Direction
  • Status (planned, on time, early, delayed, ...)
  • Start and end time of the service
  • Planned and changed destination
  • Accessibility of the vehicle for physically impaired persons
  • Notice messages of the operator about the journey or line, e.g. planned suspensions of the service or contact data for service requests
  • The route by road or railway track
  • The current position of the vehicle (when available)
  • The sequence of stops and per stop:
    • Identifications of the stop
    • Name and place of the stop
    • Accessibility of the stop for physically impaired persons
    • The geographical coordinates of the stop (in WGS84 or RDM projections)
    • Notice messages of the operator about the stop (e.g. a temporary relocation of the stop)
    • Planned arrival and departure times
    • Expected arrival and departure time (when deviant for the timetable)
    • Planned destination (this may change at a stop)
    • Changed destination (e.g. when disruptions occur)
    • Occupancy-indications when boarding. This is coded as:
      0 - Unknown
      1 - Empty
      2 - Quiet
      3 - Average
      4 - Crowded
      5 - Full
    • Planned departure platform
    • Changed departure platform
    • Status (planned, delayed, early, canceled, ...)
    • Boarding and alight possibilities
When information of only one service (journey of a vehicle) is needed, this can be requested by supplying one of two additional parameters in the request:
  1. The identification of the service (JourneyNmber). This item can be obtained from other APIs, like the Vertrektijden API that includes this item in the set of departure data.
    OR
  2. A combination of the identification of a stop place and a departure time. These items can be obtained from other APIs, where the Dienstregeling API can used to collect more detailed information about a selected service, e.g. to display the upcoming stops, the route of the service or its progression.

 

Language and projections

Every request may contain a language preference (Dutch or English). Translatable words will follow this preference. Names of stop places, operators and municipalities are not translated to preserve recognition of names during the journey. The request may also specify the projection of the coordinates that are included in the response. This can be WGS84 (latitude/longitude) or RDM (RijksDriehoekMeting, X/Y).

Errors and warnings

An ErrorMessage may be included in the response if an error or warning occurs during the processing of a request. An error message is usually accompanied with a textual indication of the problem, e.g. that an identification is unknown. The HTTP-status of the response is usually OK (200), even when errors occur that can be expected, e.g. when no data can be found. Other HTTP-statuses can occur with more technical and unexpected errors, like parameter or protocol errors.

Object

Content and meaning

ErrorMessage

This object is included in the response when an error occurs and includes an explanation of the cause of the error.

Terms of service

Usage of the 9292 Vertrektijden API is prohibited without the approval of 9292.

 

9292 Logo

It is mandatory to show the 9292 Logo. Only the logo is required, not the text.
9292 will give approval on the location of the logo before you transfer to the production environment. This is done to safeguard the usage of the 9292 logo. The logo can be found at the following URL:

 

Release notes

Software version

Comment

01-10-2021 v1.0.0

  • First public release of the 9292 Dienstregeling API for requests for a specific service (journey)

22-10-2021 v1.1.0

  • Implementation of the EndPoints for multiple services and public transport lines

14-02-2022 v1.2.0

  • Implementation of current vehicle positions

 

API Security

The API can only be accessed through HTTPS and an authentication token must be included in every request. This token is supplied by 9292 specifically for the use in this API. The same token can be used interactively in the Swagger-page. A temporary token can be requested for purposes of experimenting or to gain some experience with real data.

Header Key

Value

Authorization

...the token supplied by 9292...

Accept

Application/JSON

Content-Type

charset=utf-8