openapi3.yml

# SPDX-FileCopyrightText: NOI Techpark <digital@noi.bz.it>
#
# SPDX-License-Identifier: CC0-1.0

openapi: 3.0.3
info:
  title: Open Data Hub GTFS API
  description: >
    API to retrieve GTFS files, related metadata, and GTFS-RT realtime feeds.
  termsOfService: https://docs.opendatahub.com/en/latest/licenses.html#apis-terms-of-service
  contact:
    name: Open Data Hub
    url: https://opendatahub.com
    email: help@opendatahub.com
  license:
    name: API License
    url: https://docs.opendatahub.com/en/latest/licenses.html
  version: V1
servers:
  - url: __API_BASE_URL__/v1
paths:
  /dataset:
    get:
      summary: Get all available datasets
      responses:
        200:
          description: List of dataset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/dataset-map"
  /dataset/{datasetId}:
    get:
      summary: Get metadata of specific dataset by ID
      parameters:
        - $ref: "#/components/parameters/datasetId"
      responses:
        200:
          description: List of dataset metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/dataset"
        400:
          description: Invalid dataset ID
  /dataset/{datasetId}/raw:
    get:
      summary: Download the raw GTFS (.zip) file
      parameters:
        - $ref: "#/components/parameters/datasetId"
      responses:
        200:
          description: Raw GTFS file
          x-is-file: true
          content:
            application/zip:
              schema:
                type: string
                format: binary
        400:
          description: Invalid dataset ID
  /realtime:
    get:
      summary: List all datasets with realtime feeds
      responses:
        200:
          description: Map of datasets that have realtime feeds
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/realtime-dataset-map"
  /realtime/{datasetId}/{feedType}:
    get:
      summary: Get a realtime feed
      description: >
        Returns the GTFS-RT feed data. Format is negotiated via Accept header
        (application/json or application/x-protobuf). Defaults to JSON.
      parameters:
        - $ref: "#/components/parameters/datasetId"
        - name: feedType
          in: path
          required: true
          description: Type of GTFS-RT feed
          schema:
            type: string
            enum: [trip-updates, vehicle-positions, service-alerts]
      responses:
        200:
          description: GTFS-RT feed data
          content:
            application/json:
              schema:
                type: object
                description: GTFS-RT feed in JSON format
            application/x-protobuf:
              schema:
                type: string
                format: binary
        404:
          description: Dataset or feed type not found
        406:
          description: Requested format not available for this feed

components:
  parameters:
    datasetId:
      name: datasetId
      in: path
      required: true
      description: Dataset ID, as returned in the /v1/dataset/ call
      schema:
        type: string
  schemas:
    dataset-map:
      type: object
      description: Map of datasets by ID (id, dataset). `skyalps-flight-data` and `sta-time-tables` are example IDs
      properties:
        skyalps-flight-data:
          $ref: "#/components/schemas/dataset"
        sta-time-tables:
          $ref: "#/components/schemas/dataset"
        ummadumm-data:
          $ref: "#/components/schemas/dataset"
    dataset:
      type: object
      description: Metadata of a GTFS dataset
      properties:
        description:
          type: string
          description: A short description of the dataset
        endpoint:
          type: string
          format: uri
          description: URL to download the raw GTFS file
        origin:
          type: string
          description: The provider of the dataset
        license:
          type: string
          description: License under which the dataset is published
        metadata:
          type: object
          description: A free form JSON object that may contain additional metadata
          additionalProperties: true
        realtime:
          $ref: "#/components/schemas/realtime-links"
    realtime-dataset-map:
      type: object
      description: Map of datasets that have realtime feeds
      additionalProperties:
        $ref: "#/components/schemas/realtime-dataset"
    realtime-dataset:
      type: object
      description: Realtime feed metadata for a dataset
      properties:
        dataset_id:
          type: string
          description: The associated dataset ID
        static_dataset:
          type: string
          format: uri
          description: URL to the static GTFS dataset metadata
        static_gtfs:
          type: string
          format: uri
          description: URL to download the static GTFS file
        feeds:
          type: object
          description: Available realtime feed URLs
          properties:
            trip_updates:
              type: string
              format: uri
            vehicle_positions:
              type: string
              format: uri
            service_alerts:
              type: string
              format: uri
    realtime-links:
      type: object
      description: Links to available realtime feeds, present only when the dataset has RT feeds
      properties:
        trip_updates:
          type: string
          format: uri
        vehicle_positions:
          type: string
          format: uri
        service_alerts:
          type: string
          format: uri