openapi: 3.2.0 info: title: Public Transit API v8 Station Search API version: 8.0.1 description: 'Public Transit is a set of three REST APIs that provides public transit routing information and public transit stations information available within an area or for a given station.' termsOfService: https://legal.here.com/en-gb/terms license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://transit.hereapi.com/v8 description: All Public Transit services, namely Routing, Next Departures, and Station Search. security: - Bearer: [] - ApiKey: [] tags: - name: Station Search paths: /stations: get: operationId: Public Transit API v8 getStations summary: Stations tags: - Station Search description: 'Lists public transit stations. Discovers stations using structured or topological queries. The service accepts three types of queries as shown in the table below: | Query | Parameter | Description | |-------|-----------|-------------| | Stations by IDs | `ids` | Takes a comma-separated list of station/stop identifiers. | | Stations by location | `in` | Takes a pair of coordinates to define the center and a radius to define the extent of a circular area where to search for departures. | | Stations by name and location | `name` and `in` | Takes the station name or part of the name to search for. It is composed of one or more space-separated words and does not support stopwords. | Select a query from `one of` the options above to visualize the request parameters.' parameters: - $ref: '#/components/parameters/stationOptions' - $ref: '#/components/parameters/accessibility' - $ref: '#/components/parameters/placesReturn' - $ref: '#/components/parameters/xRequestId' responses: '200': description: API response in case of success content: application/json: schema: $ref: '#/components/schemas/StationsInfoResponse' headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '400': $ref: '#/components/responses/400ErrorResponseWithRequestID' '401': $ref: '#/components/responses/401ErrorResponseWithRequestID' '403': $ref: '#/components/responses/403ErrorResponseWithRequestID' '500': $ref: '#/components/responses/500ErrorResponseWithRequestID' '502': $ref: '#/components/responses/502ErrorResponseWithRequestID' '503': $ref: '#/components/responses/503ErrorResponseWithRequestID' '504': $ref: '#/components/responses/504ErrorResponseWithRequestID' components: responses: 403ErrorResponseWithRequestID: description: API response in case of forbidden access. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponseSchema' examples: errorResponseExample: $ref: '#/components/examples/403errorResponseExample' 400ErrorResponseWithRequestID: description: API response in case of bad request. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/400errorResponseExample' 500ErrorResponseWithRequestID: description: API response in case of internal server error. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/500errorResponseExample' 401ErrorResponseWithRequestID: description: API response in case of unauthorized access. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/SimpleErrorResponseSchema' examples: errorResponseExample: $ref: '#/components/examples/401errorResponseExample' 502ErrorResponseWithRequestID: description: API response in case of bad gateway. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/502errorResponseExample' 503ErrorResponseWithRequestID: description: API response in case of service unavailable. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/503errorResponseExample' 504ErrorResponseWithRequestID: description: API response in case of gateway timeout. headers: X-Correlation-Id: $ref: '#/components/headers/X-Correlation-Id' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/504errorResponseExample' schemas: AccessPointPlace: description: Access point to a venue/station properties: name: description: Location name type: string example: S Potsdamer Platz Bhf/Voßstr. type: description: 'Place type. Each place type can have extra attributes. **NOTE:** The list of possible place types could be extended in the future. The client application is expected to handle such a case gracefully. ' type: string location: description: 'The position of this location This position was used in route calculation. It may be different to the original position provided in the request. ' allOf: - $ref: '#/components/schemas/Location' waypoint: description: If present, this place corresponds to the waypoint in the request with the same index. type: integer wheelchairAccessible: description: 'Information about accessibility for people with a disability and who use a wheelchair. * `unknown` - Accessibility information is not available. * `yes` - Access point is wheelchair accessible. * `limited` - Accessibility is limited or assistance is required. * `no` - No accessible path from the access point to platforms. ' allOf: - $ref: '#/components/schemas/WheelchairAccessibility' required: - type - location example: type: place location: lat: 52.531677 lng: 13.381777 StationsInfoResponse: description: Station info response. properties: notices: description: 'Contains a list of issues related to this response. Follows a list of possible notice codes: * `unknownStations`: The response is incomplete as one or more of the given station IDs were not found. * `noStationsFound`: No stations information is available given current input parameters ' type: array items: $ref: '#/components/schemas/Notice' stations: description: A list of stations. type: array items: $ref: '#/components/schemas/StationInfo' required: - stations StationInfo: description: It contains transit service information for this station. properties: notices: description: 'Contains a list of issues related to this station. Follows a list of possible notice codes: * `noDepartureInfo`: Departure information is unavailable or inaccurate for this station/stop. ' type: array items: $ref: '#/components/schemas/Notice' place: description: Information about a station or stop. allOf: - $ref: '#/components/schemas/StationSearchPlace' transports: description: A list of transit services. type: array items: $ref: '#/components/schemas/TransitTransport' accessPoints: description: A list of access points type: array items: $ref: '#/components/schemas/AccessPointPlace' required: - place WheelchairAccessibility: description: 'Defines accessibility for people with a disability and who use a wheelchair. * `unknown` - Information is not available. * `yes` - Full unrestricted accessibility. * `limited` - Accessibility is limited, not everywhere or require assistance. * `no` - No accessibility. ' type: string enum: - unknown - 'yes' - limited - 'no' default: unknown example: unknown ErrorResponse: type: object description: Response in case of error properties: title: type: string description: Human-readable error description example: Input data failed validation status: type: integer description: HTTP status code example: 400 code: type: string description: 'Error code. All error codes start with "`E60`". ' example: E600101 cause: type: string description: Human-readable explanation for the error example: The input data in question does not comply with validation rules action: type: string description: Human-readable description of the action that can be taken to correct the error example: Request a valid id correlationId: type: string description: Auto-generated id that univocally identifies the request example: 4199533b-6290-41db-8d79-edf4f4019a74 required: - title - status - code - cause - action - correlationId TransitMode: title: Modes description: "Extensible enum: `highSpeedTrain` `intercityTrain` `interRegionalTrain` `regionalTrain` `cityTrain` `bus` `ferry` `subway` `lightRail` `privateBus` `inclined` `aerial` `busRapid` `monorail` `flight` `...` \nTransit mode of transport in the route response\n" example: intercityTrain type: string x-extensible-enum: - highSpeedTrain - intercityTrain - interRegionalTrain - regionalTrain - cityTrain - bus - ferry - subway - lightRail - privateBus - inclined - aerial - busRapid - monorail - flight Notice: type: object description: A notice contains important notifications. properties: title: type: string description: Human-readable notice description. example: No route found code: type: string description: Notice code. example: noRouteFound severity: $ref: '#/components/schemas/NoticeSeverity' required: - code PlacesReturn: type: array description: Enables transport information in the response. items: type: string enum: - transport - accessPoints NoticeSeverity: description: 'Describes the impact a notice has on the resource to which the notice is attached. * critical - The notice must not be ignored, even if the type of notice is not known to the user. Any associated resource (e.g., route section) must not be used without further evaluation. * info - The notice is for informative purposes, but does not affect usability of the route. ' type: string enum: - critical - info PlacesByLocation: title: Query stations by Location type: object properties: in: $ref: '#/components/schemas/InCircle' maxPlaces: description: The maximum number of stations/stops included in the response. type: integer minimum: 1 maximum: 50 default: 5 modesInPlace: description: "Format: `mode1,mode2,...`\n\nFilter the list of stations returned in the response depending on the Transit modes available.\n\nStations where at least one of the specified modes exists will get returned.\nBy default, all supported transit modes are permitted.\n\nSupported modes: `highSpeedTrain` `intercityTrain` `interRegionalTrain` `regionalTrain` `cityTrain`\n`bus` `ferry` `subway` `lightRail` `privateBus` `inclined` `aerial` `busRapid` `monorail`\n`flight`\n\nThis parameter also support an exclusion list: It's sufficient to specify each mode to exclude by prefixing it with `-`.\nMixing of inclusive and exclusive transit modes is not allowed.\n\nexamples:\n * `subway,bus`. Returns only stations having subways and busses.\n * `-subway,-bus`. Returns all stations except the one having just subways or busses.\n" type: string required: - in StationOptions: type: object oneOf: - $ref: '#/components/schemas/PlacesByIds' - $ref: '#/components/schemas/PlacesByLocation' - $ref: '#/components/schemas/PlacesByName' StationSearchPlace: description: A station properties: name: description: Location name type: string example: S Potsdamer Platz Bhf/Voßstr. type: description: 'Place type. Each place type can have extra attributes. **NOTE:** The list of possible place types could be extended in the future. The client application is expected to handle such a case gracefully. ' type: string location: description: 'The position of this location This position was used in route calculation. It may be different to the original position provided in the request. ' allOf: - $ref: '#/components/schemas/Location' id: description: 'Identifier of this station. **NOTE**: The given ID is only valid within the context of the response it is in. ' type: string example: '110543003' platform: description: Platform name or number for the departure. type: string example: '1' code: description: Short text or a number that identifies the place for riders. type: string example: '74370' wheelchairAccessible: description: 'Information about accessibility for people with a disability and who use a wheelchair. * `unknown` - Accessibility information is not available. * `yes` - There exists some accessible path from outside the station to the specific stop/platform. * `limited` - Accessibility is limited or assistance is required. * `no` - There exists no accessible path from outside the station to the specific stop/platform. ' allOf: - $ref: '#/components/schemas/WheelchairAccessibility' required: - type - location example: type: place location: lat: 52.531677 lng: 13.381777 SourceFeedMapping: description: 'Mapping of the internal data returned in the respone to the data from the source feed. A `type` will only be returned if the source feed data has a match. Each `type` might be returned more than once in the response as the source feed may have multiple matches. Currently possible values for `type` are: * `agencyId`: ID of the agency that provides the data which is defined in the source feed. * `routeId`: ID of the route that is provided in source feed. * `tripId`: ID of the trip that is provided in source feed. * `feedVersion`: Version of the feed that is defined in source feed. ' type: object properties: type: type: string description: "Extensible enum: `agencyId` `routeId` `tripId` `feedVersion` `...` \nType of source feed data.\n" x-extensible-enum: - agencyId - routeId - tripId - feedVersion example: tripId sourceValue: type: string description: Source value for the data defined in the `type`. example: 1234-567 Color: type: string pattern: '#[0-9A-Fa-f]{6}' example: '#FF0000' PlacesByName: title: Query stations by Name and Location type: object properties: name: description: 'The station name or part of the name to search for. It is composed of one or more space separated words. ' type: string method: description: 'Specifies if the match is `fuzzy` or `strict`. The default value is fuzzy. `fuzzy` - search for a station with the name similar to one of the names requested `strict` - search for a station with the name exactly matching one of the names requested or containing it as a part For example, if the station name in the request is "maurer", then if the method is `fuzzy` the response contains "AMBOY AVE AT MAURER RD" and "LAUREL HILL BL/48 ST". If the method is `strict` the response contains "AMBOY AVE AT MAURER RD" but not "LAUREL HILL BL/48 ST". ' type: string enum: - fuzzy - strict maxPlaces: type: integer maximum: 25 description: The maximum number of stations/stops included in the response. minimum: 1 default: 5 in: $ref: '#/components/schemas/InCircle' modesInPlace: description: "Format: `mode1,mode2,...`\n\nFilter the list of stations returned in the response depending on the Transit modes available.\n\nStations where at least one of the specified modes exists will get returned.\nBy default, all supported transit modes are permitted.\n\nSupported modes: `highSpeedTrain` `intercityTrain` `interRegionalTrain` `regionalTrain` `cityTrain`\n`bus` `ferry` `subway` `lightRail` `privateBus` `inclined` `aerial` `busRapid` `monorail`\n`flight`\n\nThis parameter also support an exclusion list: It's sufficient to specify each mode to exclude by prefixing it with `-`.\nMixing of inclusive and exclusive transit modes is not allowed.\n\nexamples:\n * `subway,bus`. Returns only stations having subways and busses.\n * `-subway,-bus`. Returns all stations except the one having just subways or busses.\n" type: string required: - name - in Location: description: Location on the Earth properties: lat: description: Location of a point on the Earth north or south of the equator in decimal degrees. type: number format: double example: 52.531677 lng: description: Location of a place on the Earth east or west of the prime meridian in decimal degrees. type: number format: double example: 13.381777 example: lat: 52.531677 lng: 13.381777 required: - lat - lng SimpleErrorResponseSchema: type: object properties: error: type: string description: Human-readable error error_description: type: string description: Human-readable error description TransitTransport: description: Transit transport information. properties: mode: $ref: '#/components/schemas/TransitMode' name: description: Transit line name type: string example: U2 headsign: description: Transit line headsign. type: string example: Cottbus, Hauptbahnhof category: description: Human readable transport category (such as Bus, Gondola, Tram, Train, ...). type: string example: Railway Service color: description: Color of the transport polyline and background for the transport name. allOf: - $ref: '#/components/schemas/Color' textColor: description: Color of the transport name. allOf: - $ref: '#/components/schemas/Color' shortName: description: Short name of a transit line. type: string example: U2 longName: description: Long name of a transit line. type: string example: Pankow - Ruhleben wheelchairAccessible: description: 'Information about accessibility for people with a disability and who use a wheelchair. * `unknown` - Accessibility information is not available. * `yes` - Vehicle can accommodate at least one rider in a wheelchair. * `limited` - Accessibility is limited or assistance is required. * `no` - No riders in wheelchairs can be accommodated. ' allOf: - $ref: '#/components/schemas/WheelchairAccessibility' sourceFeedMapping: description: 'List of source feeds that shows the original feed data. The item keys can be repeated if the original data has multiple mappings for the same ID. For this instance, only `routeId` and `tripId` are valid values for `type`. No other values will be returned in this scope. ' type: array items: $ref: '#/components/schemas/SourceFeedMapping' required: - mode PlacesByIds: title: Query stations by IDs type: object properties: ids: description: 'Specifies a comma separated list of station IDs. A maximum of 50 station identifiers are allowed in a single query ' type: string maxLength: 1000 required: - ids InCircle: description: 'Specifies the center point and the optional radius of your search. Format `{lat},{lng}[;r={radius}]`, where `radius=500` meters by default. ' type: string pattern: '[-+]?\d*\.?\d+,[-+]?\d*\.?\d+(;r=\d+)?' example: 24.5,16.8;r=500 examples: 503errorResponseExample: value: title: 'failed with reason: service unavailable' status: 503 code: E600001 cause: Service Unavailable action: '' correlationId: '' 504errorResponseExample: value: title: 'failed with reason: gateway timeout' status: 504 code: E600000 cause: Gateway Timeout action: '' correlationId: '' 500errorResponseExample: value: title: 'failed with reason: internal server error' status: 500 code: E600103 cause: Internal Server Error action: '' correlationId: '' 401errorResponseExample: value: error: Unauthorized error_description: No credentials found 403errorResponseExample: value: error: Forbidden error_description: These credentials do not authorize access. 502errorResponseExample: value: title: 'failed with reason: bad gateway' status: 502 code: E600002 cause: Bad Gateway action: '' correlationId: '' 400errorResponseExample: value: title: 'failed with reason: missing field `destination`' status: 400 code: E600000 cause: Bad request action: '' correlationId: '' parameters: stationOptions: name: stationOptions in: query description: Station filter required: false style: form explode: true schema: $ref: '#/components/schemas/StationOptions' placesReturn: name: return description: "Defines which place attributes are included.\n\n * `transport` - List of transports.\n * `accessPoints` - List of access points.\n" in: query schema: $ref: '#/components/schemas/PlacesReturn' style: form explode: false xRequestId: name: X-Request-ID in: header description: User-provided token that can be used to trace a request or a group of requests sent to the service. schema: type: string accessibility: name: accessibility description: "Defines accessibility requirements for routes.\n\n * `wheelchair` - Select only wheelchair accessible vehicles and stations.\n" in: query schema: type: array uniqueItems: true items: type: string enum: - wheelchair style: form explode: false headers: X-Request-Id: description: User-provided token that can be used to trace a request or a group of requests sent to the service. schema: type: string example: 8230d7ad-3f1c-4191-a8dd-f3c42026da89 X-Correlation-Id: description: Auto-generated id that univocally identifies the request. schema: type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 securitySchemes: ApiKey: type: apiKey in: query name: apiKey description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see [Identity and Access Management Developer Guide](https://docs.here.com/identity-and-access-management/docs/readme). ' Bearer: type: http scheme: bearer bearerFormat: JWT description: 'A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information on how to get a bearer token, see the [Identity and Access Management Developer Guide](https://docs.here.com/identity-and-access-management/docs/readme). '