Migrate to Public Transit Next Departures v8

This document highlights the most important changes necessary to migrate to the new version (v8). Public Transit Next Departures v3 offers the possibility to query next departures by the following:

  • Station IDs with multiboard/by_stn_ids + stnIds parameter
  • Station Geo Coordinates with multiboard/by_geocoord + center parameter

Public Transit Next Departures v8 differentiates the queries by means of the request parameters ids and in:

  • multiboard/by_stn_ids.json?stnIds (v3) is replaced by departures?ids (v8)
  • multiboard/by_geocoord.json?center (v3) is replaced by departures?in (v8)

Note

The missing API versions from v3 to v8 are due to internal version alignment.

Request

This section describes changes in the request.

Parameters Added

This migration does not introduce new parameters.

Parameters Changed

The following parameters are changed in this migration.

Base URL, Version, Resource

Parameter Public Transit Next Departures v3 Public Transit Next Departures v8
Base URL string, https://transit.ls.hereapi.com string, https://transit.hereapi.com
Version string, /v3 string, /v8
Resource string /multiboard/<name> string, /departures

stnIds vs ids

This migration renames stnIds parameter (v3) to be ids (v8).

stnIds ids
Format string string
Behavior Specifies a comma separated list of station IDs. Specifies a comma-separated list of station IDs. A maximum of 50 station identifiers are allowed in a single query.

center vs in

This migration renames center parameter (v3) to in (v8).

center in
Format Double,Double string
Behavior Specifies the latitude and the longitude of the center point of your search separated by a comma. Specifies the center point and the optional radius of your search. Format {lat},{lng}[;r={radius}], where radius=500 meters by default.

time vs time

This migration modifies mandatory time parameter (v3) to optional (v8). If time is not specified, current time at departure place will be used. All Time values in the response are returned in the timezone of each location.

max vs maxPerBoard

This migration renames max parameter (v3) to maxPerBoard (v8).

max maxPerBoard
Format integer integer
Behavior By default, it is set to 50. The minimum value is 1 and the maximum value is 100. By default, it is set to 5. The minimum value is 1 and the maximum value is 50.

maxStn vs maxPlaces

This migration renames maxStn parameter (v3) to maxPlaces (v8).

maxStn maxPlaces
Format integer integer
Behavior By default, it is set to 50. The minimum value is 1 and the maximum value is 50. By default, it is set to 5. The minimum value is 1 and the maximum value is 50.

Note

This change is valid only when next departures are queried by station geo-coordinates.

Parameters Removed

This migration does not remove parameters.

Response

This section describes changes in the response.

Parameters Added

This migration introduces the following parameters in (v8) response:

  • notices: To response object
  • type: The place type
  • agency: Similar to Operators parameter (v3)
  • waypoint
  • status: Status of the departure
  • delay: The accumulated delay in seconds from the scheduled time of the event
  • platform: Platform name or number for the departure
  • location, originalLocation: Contains former x and y parameters (v3) in Stn object
  • transport: Similar to Transport in Dep parameter (v3). For more information, see Transport Concept

Parameters Changed

This migration introduces the following changes to parameters in response (v8):

  • renames the MultiNextDeparture parameter (v3) to boards (v8)
  • renames the Stn and Dep parameters (v3) to place and departures (v8)
  • changes the integer mode parameter (v3) to string (v8)
  • renames the x, and y parameters (v3) to lng, and lat (v8)
  • renames the Attributions parameter (v3) to attributions (v8)

Parameters Removed

This migration removes the following parameters in (v8) response:

  • Res
  • serviceUrl
  • MultiNextDepartures
  • NextDepartures
  • Operators
  • journey_ctx
  • duration
  • distance

Codes

The following table describes the response codes changed in this migration.

v3 error code v8 error code Status code Description
GW100 E602000 400 Bad request Wrong parameter type or parameter missing
I4 N/A 401 Unauthorized for wrong credential, 403 Forbidden for access not allowed N/A
GW0001 N/A 200 OK Returns empty departures list and notice object
GW0002 E602100, E602101, E602102 504 Gateway Timeout, 503 Service Unavailable, 502 Bad Gateway Backend failed to provide a response
GW0006 E602103 500 Internal Server Error Unexpected error
GW0007 N/A 200 OK No support for this API in this area
K9360 E602104 400 Bad request Invalid Period

Examples

The following request examples in JSON format search stations by Geo Coordinates:

Note

Public Transit Next Departures v3 example uses a HERE API Key to authenticate the request. HERE Token Credentials authentication is only possible in Public Transit Next Departures v8. For information on other possible authentication options, see the Identity & Access Management Guide.

results matching ""

    No results matching ""