Business

Locaties API additional documentation

9292 Locaties API introduction

Planning with bicycles and mopeds in a public transport travelling advice is a standard feature of the 9292 Reisadvies API. By assigning the ‘FirstMile’ and or ‘LastMile’ parameter with the values ‘PrivateBicycle’ or ‘PrivateElectricBicycle’ you can provide the traveler with the appropriate public transport travel advice in which he or she can use their own bicycle or electric bicycle to and from a bicycle transfer point located near a train station or a bus/metro/tram stop. To use a moped in the transport travel advice use the value ‘PrivateMoped’.

The 9292 Reisadvies API also supports the use of rental bicycles and mopeds. Assigning the value ‘PublicBicycle’, ‘PublicElectricBicycle’ or ‘PublicMoped’ to the ‘LastMile’ parameter will return a transport travel advice with an extra transition-leg to the appropriate rental location.

The planner is not looking at opening times or bicycles that are actually available at that time, but returns the most optimal travel advice to a cluster we have marked as suitable to transfer with a bike (for example because a location of a provider of rental bikes is within range of the cluster).

Information on the actual number of available bikes is available in real time (with a delay of maximum a few minutes based on the data of the source) in the 9292 Locaties API. This API offers information on the rental locations per arrival or departure location and the details of this location (for example the number of available assets and opening times).

This short manual introduces how you can use the interface of the 9292 Locaties API to enhance the public transport travel advice data with rental locaties on your website or other products. This is an addition to the online open api (Swagger) documentation, which can be found at https://locaties-api.9292.nl. Here you can also try out requests (when you have a 9292 Reisadvies API token).

The basis of the 9292 Locaties API is JSON. Knowledge of WebAPI and JSON technologies as a developer is necessary to use this API.

Terms of service

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

 

9292 Logo

Is it mandatory to show the 9292 logo when using the information on a different page than a travel advice. Only the logo is required, no 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

Remarks

22-09-2021 v2.1.3

  • First public release of the 9292 Locaties API

 

API Security

The 9292 Reisadvies API is secured and can only be used when you have been given a Token or a so-called APIKey by 9292. This ‘Token’ consists of symbols and letters, which is provided through a license agreement. This license agreements allows our customers to make requests to our server.
This ‘Token’ should be kept secret and not shared with any other party. In case of misuse 9292 can deactivate your account.

Access token

You will receive a Token via e-mail from the 9292 Servicedesk. The Token is your identification code which gives you access to the acceptance environment of the 9292 Reisadvies API. Once you have completed your implementation and your service has been tested by 9292, you may switch to the production environment. The 9292 Servicedesk will send you a new Token for the production environment.
After transferring to the production environment, the acceptance environment will remained accessible for two weeks.

The Token must be included in the header of each request. Here is an example of a request header:

Header Key

Value

Authorization

Token <MY_TOKEN>

Accept

Application/JSON

Content-Type

charset=utf-8

Please note:

The 9292 Locaties API only supports HTTPS requests.

okens are sent to identify a particular customer and thus the tapping of the HTTP stream can be abused.

 

Facilities

The Locatie API 2.0 has 2 endpoints; Facilities and Facility. Both can be used to requestr information about rental locations and assets, with the difference that 'Facilities' can be used to request multiple locaties that are close to a specific station or stop and 'Facility' can be used to (re-)request information on a specific location on the basis of a 'FacilityId' that is available with every facility when a list of facilities has been requested.

Facilities can be requested on the basis of a Location Id connected to the leg that refers to PublicBicycle/PublicMoped/PublicElectricBicycle modalities in the travel advice. For example 'station-den-haag-centraal' used for station Den Haag Centraal in below excerpt of a 9292 Reisadvies API request.

Format

Example

JSON

 {
...
 "Location": {
    "QuayCode""",
    "VisuallyAccessible""Unknown",
    "DisabledAccessible""Unknown",
    "Id""station-den-haag-centraal",
    "StationAbbreviation""gvc"
    "DisplayName""Den Haag Centraal"
    "Place"{
        etc...

The JSON request that should be sent in the body of a request to the /Facilities/ endpoint looks like this:

Format

Example

JSON

 {
    "clusterId""station-den-haag-centraal",
    "getAssets" false,
    "modality"[
         "PublicBicycle"
     ],
    "modalityClass"[
         "Rental"
     ],
    "getServiceArea"false,
    "date""2021-08-30T08:48:00",
    "language""Dutch"
 }

The field names have the following meanings:

Fieldname

Type

Description

ClusterId

String

Id of the location in the leg of a Reisadvies API advice.

GetAssets

True/false

Return the individual asset locaties (only when used in a 'free floating' asset system).

Modality

Array van modaliteiten

Return a specific type of asset like PublicBicycle, PublicMoped, PublicElectricBicycle. Multiple types can be requested or all types are returned if the modality field is empty.

ModalityClass

Array of modality types

Return location type (only ‘Rental’ is available).

GetServiceArea

True/false

Return service area's belonging to the location. This will return a list of coordinates that form the area.

Date

Date

Date of the travel advice, used to show if a location is open or closed.

Language

Dutch/English

Content can be shown in English or Dutch (if available).

The response will look like the following (see further technical documentation at https://locaties-api.9292.nl for the full object and all fields):

Format

Example

JSON

 {
    "facilityId""HTM-Fiets-24fa4849-2a83-40e1-8a6b-6852f937aeaa",
    "externalFacilityId""24fa4849-2a83-40e1-8a6b-6852f937aeaa",
    "name""Fietsenstalling CS (Nieuw)",
    "typeOfFacility""Virtualstation",
    "region"null,
    "staffed"false,
    "openingHourSummary""Nu open: 00:00 - 23:59",
    "openNow"true,
    "Provider" {
            "brand""HTM Fiets",
            "operator"null,
            "url""https://www.htm.nl/klantenservice",
            "phoneNumber""0900-4862453",
            "email""deelfiets@htm.nl",
            "conditions""Lees de informatie op htm.nl/htm-fiets",
            "conditionsUrl""https://www.htm.nl/htm-fiets",
            etc...

Based on above response the facility can be directly called via the /Facility/ endpoint, by using the FacilityId "HTM-Fiets-24fa4849-2a83-40e1-8a6b-6852f937aeaa" in the request.

Numbers shown in 'NumberOfAssets' and 'NumberOfAssetsAvailable' are updated with real time information in an interval of 1 or 2 minutes. The same is the case for the current location of assets when request is sent with 'GetAssets' true.

Locations are returned in a specific order:

  • First on the basis of being up-to-date and the number of available assets > 0,
    • then by Brand and Name of the location
  • then based on not being up-to-date and the number of available assets > 0,
    • then by Brand and Name of the location
  • then based on being up-to-date with 0 assets,
    • then by Brand and Name of the location

If Dutch or English information can be returned is dependent on this information begin available with the data supplioers. In some cases the tag '(Dutch only)' will be placed in front of the text, if only Dutch text is available and English text is requested.