openapi: 3.1.0
info:
  title: Heideschnecke RB38 API
  version: "1.0.0"
  description: >
    Lese-only API über die selbst erfasste Pünktlichkeits-Historie und Live-Abfahrten
    der RB38 (Buchholz (Nordheide) – Hannover Hbf). Inoffizielles, privates Projekt –
    keine Verbindung zur Deutschen Bahn oder start Niedersachsen.
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Die Heideschnecke
    url: https://heideschnecke.de
servers:
  - url: https://heideschnecke.de/api/v1
    description: Produktion
components:
  schemas:
    Envelope:
      type: object
      required: [generatedAt, license, attribution, source]
      properties:
        generatedAt: { type: string, format: date-time }
        license: { type: string, example: CC-BY-4.0 }
        attribution: { type: string }
        source: { type: string }
    Meta:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            line: { type: string, example: RB38 }
            version: { type: string, example: v1 }
            collectingSince: { type: [string, "null"], format: date }
            counts:
              type: object
              properties:
                observations: { type: integer }
                trips: { type: integer }
                cancelled: { type: integer }
    Station:
      type: object
      properties:
        eva: { type: string }
        name: { type: string }
        slug: { type: string }
        pos: { type: integer }
    Departure:
      type: object
      properties:
        trip_id: { type: string }
        direction: { type: string, enum: [nach_hannover, nach_buchholz] }
        station_slug: { type: string }
        planned_dep: { type: [string, "null"], format: date-time }
        rt_dep: { type: [string, "null"], format: date-time }
        dep_delay: { type: [integer, "null"] }
        cancelled: { type: boolean }
        reason_codes: { type: array, items: { type: string } }
        reason_text: { type: [string, "null"] }
    Observation:
      type: object
      properties:
        trip_id: { type: string }
        trip_date: { type: string, format: date }
        direction: { type: string, enum: [nach_hannover, nach_buchholz] }
        station_slug: { type: string }
        route_idx: { type: integer }
        planned_dep: { type: [string, "null"], format: date-time }
        planned_arr: { type: [string, "null"], format: date-time }
        dep_delay: { type: [integer, "null"] }
        arr_delay: { type: [integer, "null"] }
        cancelled: { type: boolean }
        reason_codes: { type: array, items: { type: string } }
        reason_text: { type: [string, "null"] }
    WorstDelay:
      type: object
      properties:
        date: { type: string, format: date }
        direction: { type: string }
        startTime: { type: [string, "null"], format: date-time }
        worstStation: { type: string }
        delay: { type: integer }
        reason: { type: [string, "null"] }
    Stats:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          properties:
            stats:
              type: object
              properties:
                total: { type: integer }
                onTime: { type: integer }
                onTimePct: { type: number }
                cancelled: { type: integer }
                cancelledPct: { type: number }
                avgDelay: { type: number }
                maxDelay: { type: integer }
                worstDelays: { type: array, items: { $ref: '#/components/schemas/WorstDelay' } }
                reasons:
                  type: array
                  items:
                    type: object
                    properties:
                      key: { type: string }
                      count: { type: integer }
                      pct: { type: number }
paths:
  /meta:
    get:
      summary: Linien-Metadaten, Quelle, Lizenz, Zählerstände
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Meta' }
  /stations:
    get:
      summary: Stationsliste der RB38 (in Streckenreihenfolge)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      stations: { type: array, items: { $ref: '#/components/schemas/Station' } }
  /departures:
    get:
      summary: Live-Abfahrten der nächsten ~5 Stunden (alle Halte)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      departures: { type: array, items: { $ref: '#/components/schemas/Departure' } }
  /observations:
    get:
      summary: Gesamte erfasste Historie (Bulk-Download)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - type: object
                    properties:
                      count: { type: integer }
                      observations: { type: array, items: { $ref: '#/components/schemas/Observation' } }
  /stats:
    get:
      summary: Aggregierte Pünktlichkeit, Top-Verspätungen, Gründe-Ranking
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Stats' }