Business

Vertrektijden API additional documentation

9292 Vertrektijden API introduction

The Vertrektijden API can deliver service information for public transport stops in the Netherlands. When specified, the API can also deliver information about flexible public transport, in addition to the regular public transport services. The API is targeted for use in Apps, in websites or by content providers that want to provide this information in a flexible way to their users.

In a typical use case, users look for public transport stops in their vicinity, in some geographical area or by specifying some keywords. After selecting one or more stops that are of interest, more detailed information is requested about the public transport services that depart from these stops in the near future. This request is periodically repeated to refresh any data that may need to be updated as services may have arrived or departed at the stop(s). Typically, this is done every minute for as long as the data is displayed to the user.

When searching for stops or departure information, an extensive set of parameters can be used to narrow down the result to the most relevant data or the receive the data in the preferred format. This page lists a global description of these parameters and results. Please go to the Swaggerdocumentation at https://vertrektijden-api.9292.nl for more exact definitions.

The Swagger documentation has 3 sections:

  1. Examples. These are working examples of requests the return data without any prior knowledge of parameters or formats. The most relevant parameters can be changed interactively to see how they effect the results, but they are not comprehensive. The purpose is educational, but not operational. The other endpoints are intended for operational use.
  2. StopPlaces. This can be used to search for the public transport stops (the first 3 endpoints) or to retrieve stop information again for stops that have been retrieved before, but whose data might need to be refreshed (the last endpoint).
  3. StopVisits. By using the identification of stops that have been found or selected before, departure information can be retrieved through this endpoint. This is typically the most frequently used request, e.g. every minute for as long as the data is displayed to users.

 

In general, objects and attributes are only returned in the response if they has value. E.g. if there a no notice texts for a service, these objects will be omitted from the response, including the structure in which they are listed. Similarly, attributes without value are also ommitted. E.g. departure information may include a changed departure platform, but in most cases, it will not have been changed and in those cases the attribute will be omitted from the response.

Parameters in requests for stops

Parameter

Meaning

Projection

Specifies the projection of the coordinates that are included in the request and the returned coordinates in the response. Possible values are: WGS84 or RD. Default is WGS84.

...Latitude

For WGS84-projections: the latitude coordinate. For RD-projections: the Y-coordinate.

...Longitude

For WGS84-projections: the longitude coordinate. For RD-projections: the X-coordinate.

Radius

When requesting stops in a circular area: the redius of the circle in meters

Query

When requesting stops with keywords: a list of keywords separated by spaces

Language

Determines the language of a number of translatable words in the response. Possible values are: NL or EN. Default is NL.

FlexOV

Specifies whether flexible public transport should be included in the response. Default value is: false.

StopType

The type of stop that must be returned. Possible values are: Cluster, Physical, Quay or StopPlace. Default is Cluster.

IncludeParentStop

Includes for physical stops the associated cluster stop. For quay stops the associated StopPlace is included. Default is false.

IncludePhysicalStops

Includes the identifications of related physical stops. For physical stops, the identifications of associated quay-stops will be included. For quay stops, the identifications of associated physical stops will be included. Default is false.

Details

When stops are requested to display a map of public transport stops, this parameter can be used to reduce the details per stop. When false a minimal set of details are returned that suffice to draw a map, This allows a larger set of stops to be included in the response. Default is true meaning: all details

Response after a request for public transport stops

The response contains a number of objects that are described briefly here. For more details, please go to the Swaggerdocumentation (href="https://vertrektijden-api.9292.nl" target="_blank">https://vertrektijden-api.9292.nl).

Object

Content and meaning

Stop

Contains all identifying data of a stop and an indication of the availability of public transport services on this stop for the current day. All other stop related objects are included in this object.

Coordinates

The geographical coordinates of the stop. The parameter in the request determines the projection of the returned coordinates. Only the coordinates of the requested projection are included.

StopAttribute

These attributes indicate the accessibility of physically impaired persons.

Line

General and identifying data about the line of the service if there is at least one service for the current day.

Disruption

These text messages of operators describe both planned and unplanned disruptions of the regular scheduled services. An operator may send an unscheduled message at any moment, so this can change during the day.

Parameters for requesting departure information

Parameter

Meaning

StartTime

Start of the period for which departure data is requested. The value NOW can be used instead of a date/timestamp. The StartTime can be any moment between the start of the current day and a few days in the future. Default is NOW. When the date/time format cannot be interpreted, the value NOW is assumed.

PreviewInterval

The duration of the period for which departure data is requested. The value is in minutes. The maximum value is 1440 (24 hours). Default is 60.

MaximumStopVisits

The maximum number of departures that can be included in the response. When the maximum has been reached and the list will be truncated, a warning will be included in the response. (See ErrorMessage).

StopCodes

A list of identifications of the stops. The stop codes are different for different types of stops, even if they identify the same physical stop.

StopType

The type of stop. Possible values are: Cluster, Physical, Quay en StopPlace. Default is Cluster.

LinePlanningNumber

This is the identification of a line as it is used in the schedules of public transport services. The identification is included in stop and departure data and can be used to narrow down the requested data to specific lines. Multiple LinePlanningNumbers can be used to filter the returned results.

OperatorName

This can be used to restrict the returned departures to specific operators. Multiple names can be used.

TransportType

This can be used to restrict the results to specific transport types. Multiple types are possible.

Projection

Specifies the projection of the coordinates that are included in the request and the returned coordinates in the response. Possible values are: WGS84 or RD. Default is WGS84.

Language

Determines the language of a number of translatable words in the response. Possible values are: NL or EN. Default is NL.

FlexOV

Specifies whether flexible public transport services should be included in the response. Default value is: false.

PassageType

Specifies whether departure information or arrival information is requested, or both. Default is departure information.

Results after requesting departures

The response contains the following objects, including a few items from the request and the total number of departures. For more details, please see the Swaggerdocumentation (href="https://vertrektijden-api.9292.nl" target="_blank">https://vertrektijden-api.9292.nl).

Object

Content and meaning

VisitStop

Contains the identifying data of the stop.

Coordinates

The stop coordinates. Zie above.

StopAttribute

The accessibility of the stop for physically impaired persons.

Visit

This represents the visit of a public transport service to the stop and contains data that are relevant for the whole service.

DepartureGroup

This object contains data that is specific for the departure or arrival at this stop. E.g. scheduled and expected departure times, departure platform, occupancy-indication, changes to the scheduled departures. The occupancy-indication is coded as a digit with the following interpretation:
0 - Unknown
1 - Empty
2 - Quiet
3 - Average
4 - Crowded
5 - Full

ArrivalGroup

Similar to the DepartureGroup. This object contains data that is relevant for the arrival of a public transport service. There is no occupancy-indication in an ArrivalGroup.

Notice

This are text messages of operators that are included in the service schedules. E.g. contact data to request a service at a particular stop or changes for a planned period of time, e.g. school holidays.

JourneyAttribute

These attributes indicate the accessibility of physically impaired persons of the vehicle. This can be different from the accessibility of the stop.

Disruption

These text messages of operators describe both planned and unplanned disruptions of the regular scheduled services. An operator may send an unscheduled message at any moment, so this may change at any time.

Errors en warnings

When errors or warnings occur during the processing of a request, one or more messages may be included in the response. ErrorMessages can be returned along regular data. E.g. when multiple stop identifications are included in a request and only one of them can not be found, an ErrorMessage is included to indicate the unknown identification, but the data for the other stops is returned in the normal way. As a result, for most requests a HTTP status code OK (200) is returned, even if no data is found. Only more technical error situations like incorrect parameter values or format errors may result in other HTTP status codes. Anything that went wrong will be included in the ErrorMessages, but the Vertrektijden API will deliver data when it can, even if it is partial or less then requested.

Object

Content and meaning

ErrorMessage

This object is included when errors or warnings occur during the processing of a request, e.g. when unknown stops are requested or when the list of results is limited by the specified maximum in the request.

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

21-06-2021 v1.2.0

  • First public release of the 9292 Vertrektijden API

23-08-2021 v1.3.0

  • Extension with transfer information
  • Links between Quays en Physical stops can be requested

23-11-2021 v1.4.0

  • Further extension of transfer services
  • Improvement of Swaggerdocumentation

21-12-2021 v1.5.0

  • Integration of the Vertrekwijzer in the Vertrektijden API
  • Redirections of HTTP to HTTPS for Vertrekwijzer-requests

21-01-2022 v1.6.0

  • Further extension of transfer services
  • New layout for the web version of the Vertrekwijzer

03-03-2022 v1.7.0

  • Extension of the Vertrekwijzer with occupancy-indications
  • Data-version of the Vertrekwijzer can deliver data in JSON format

29-08-2022 v1.8.0

  • Support for multiple date/time formats for departure/arrival times

 

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