A Deep Dive into Public Transit Next Departures API v8

In the previous blog post, we explored the functionalities of the Public Transit Station Search API v8, which is part of the comprehensive Public Transit API v8. This powerful suite of REST APIs includes three essential components: the Public Transit Routing API v8, Public Transit Next Departures API v8, and Public Transit Station Search API v8. Building upon our previous discussion, this article will focus on the Public Transit Next Departures API v8 and demonstrate how it can be seamlessly integrated with the Maps API for JavaScript to enhance public transit information within your web applications.

Understanding the Public Transit Station Search API v8

The Public Transit Next Departures API v8 allows developers to retrieve subsequent departures from a specific station. By making a request to the /boards endpoint, you can obtain a list of upcoming departures along with relevant details such as departure time, delay information, and transport type.

Use Cases

This API can be utilized in various scenarios, some of which include:

Obtaining subsequent departures: Retrieve the list of upcoming departures from a particular station. This information can be displayed to users, providing real-time updates on the next available transportation options.
Determining transport lines serving a station: With the API, you can identify which transport lines serve a specific station. This knowledge is valuable for displaying comprehensive transit information and helping users plan their journeys effectively.
Assessing transport delays: The API provides delay information for transports serving a particular station. By integrating this feature, you can notify users about any delays or disruptions that might affect their travel plans.

Making API Requests

To interact with the Public Transit Next Departures API v8, developers can utilize three different types of queries:

Query Departure by IDs: Retrieve departure information for specific departures by providing their unique IDs.

Copied

        GET https://transit.hereapi.com/v8/departures
    ?ids=415712984
Authorization: Bearer

Query Departure by location: Obtain departure details for all departures from a specific station by specifying its location.

Copied

        GET https://transit.hereapi.com/v8/departures
    ?in=41.900138,12.501924;r=500
Authorization: Bearer

API Response

When making a request to the API, the response will contain the following information blocks:

a maximum of 50 departure board elements per station for all nearby stations. The optional maxPerBoard request parameter sets the maximum number of departures for each board element the response should include.
Each departure element in departures within the boards response object includes the following high-level elements:
- place with station/stop information such as name, location, id, type.
- departures with transport information such as departure time, delay, status, operator and so on.
- attributions with required information to be displayed such as disclaimers.

Copied

        {
  "boards": [
    {
      "place": {
        "name": "Roma Termini",
        "type": "station",
        "location": {
          "lat": 41.90054,
          "lng": 12.502168
        },
        "id": "415712984"
      },
      "departures": [
        {
          "time": "2020-04-21T10:28:00+02:00",
          "transport": {
            "mode": "regionalTrain",
            "name": "FL4",
            "category": "Regional Train",
            "color": "#7A2900",
            "textColor": "#FFFFFF",
            "headsign": "Velletri"
          },
          "agency": {
            "id": "aDmtre00",
            "name": "Trenitalia",
            "website": "http://www.trenitalia.com/"
          }
        },
        //... more departure time
        }
      ],
      "attributions": [
        {
          "id": "-link-0",
          "href": "http://creativecommons.org/licenses/by/3.0/it/",
          "text": "Some line names used in this product or service were edited to align with official transportation maps.",
          "type": "disclaimer"
        }
      ]
    }
  ]
}

Integration with the Maps API for Javascript

The class H.service.publicTransit.Service encapsulates the HERE Public Transit API in a service stub, providing methods to access its resources. And the method getDepartures(params,onResult,onError) sends a request to the Public Transit API to get subsequent departures from a given station. The supported parameters are the same as the REST requests above.

Copied

        function pubicTransportNextDepartures(platform, at) {
  var publicTransit = platform.getPublicTransitService(),
      publicTransitParameters = {
        in:'41.90123,12.50091;r=1000',
        return:'transport',
        maxPlaces:50
      };

  publicTransit.getDepartures(
    publicTransitParameters,
    onSuccess,
    onError
  );
}

Sample Application

Below is the sample application showing several major transit in Europe as a request parameter to the Public Transit Next Departure API, and it would show response from the API including the name of the station and one of the subsequent departures of the station. This sample is built using HERE Maps API for Javascript and modified from the Search for a Location based on an Address sample. The source code for this sample application can be found in our HERE Github repo.

Conclusion

In this blog post, we delved into the Public Transit Next Departures API v8, a vital component of the comprehensive Public Transit API v8. We discussed its capabilities for retrieving subsequent departures from a given station, and the significant value it brings to developers aiming to provide up-to-date transit information to their users. Furthermore, we explored how the integration of the Public Transit Next Departures API v8 with the Maps API for JavaScript opens up exciting possibilities for creating immersive and user-friendly web applications.