openapi: 3.0.3
info:
  title: Bus Citoyens — API RDEX+
  version: 2.0.0
  description: "API d'interopérabilité covoiturage au standard FabMob RDEX+.
    Expose en lecture seule les trajets réguliers publiés sur Bus Citoyens, sous
    forme de « Journeys » anonymisés. Aucune donnée personnelle n'est renvoyée :
    la mise en relation se fait via l'URL publique du trajet (`webUrl`). Service
    non marchand — tous les trajets sont gratuits."
  contact:
    name: Support API Bus Citoyens
    email: api@buscitoyens.fr
  license:
    name: Usage non marchand
    url: https://buscitoyens.neurovalys.fr/protection-des-donnees
servers:
  - url: https://buscitoyens.neurovalys.fr/api/rdex/v2
    description: Production
tags:
  - name: Journeys
    description: Recherche de trajets de covoiturage.
security:
  - apiKeyAuth: []
paths:
  /journeys:
    get:
      tags:
        - Journeys
      operationId: searchJourneys
      summary: Rechercher des trajets correspondants
      description: Renvoie les trajets dont les points de départ et d'arrivée tombent
        dans les rayons demandés. Les coordonnées des quatre points sont
        obligatoires.
      parameters:
        - name: departureLat
          in: query
          required: true
          description: Latitude du point de départ.
          schema:
            type: number
          example: 49.8941
        - name: departureLng
          in: query
          required: true
          description: Longitude du point de départ.
          schema:
            type: number
          example: 2.2958
        - name: arrivalLat
          in: query
          required: true
          description: Latitude du point d'arrivée.
          schema:
            type: number
          example: 49.8463
        - name: arrivalLng
          in: query
          required: true
          description: Longitude du point d'arrivée.
          schema:
            type: number
          example: 2.4901
        - name: carpoolerType
          in: query
          required: false
          description: Filtre de rôle. « both » (défaut) ne filtre pas.
          schema:
            type: string
            enum:
              - driver
              - passenger
              - both
            default: both
        - name: frequency
          in: query
          required: false
          description: Filtre de fréquence. Tous les trajets Bus Citoyens sont « regular ».
          schema:
            type: string
            enum:
              - punctual
              - regular
              - both
            default: both
        - name: departureRadius
          in: query
          required: false
          description: Rayon de recherche autour du départ, en km.
          schema:
            type: number
            default: 1
            minimum: 0
            maximum: 50
        - name: arrivalRadius
          in: query
          required: false
          description: Rayon de recherche autour de l'arrivée, en km.
          schema:
            type: number
            default: 1
            minimum: 0
            maximum: 50
        - name: count
          in: query
          required: false
          description: Nombre maximal de trajets renvoyés.
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Trajets correspondants.
          headers:
            X-RateLimit-Limit: &a2
              description: Quota maximal de requêtes sur la fenêtre courante.
              schema:
                type: integer
            X-RateLimit-Remaining: &a3
              description: Requêtes restantes sur la fenêtre courante.
              schema:
                type: integer
            X-RateLimit-Reset: &a4
              description: Timestamp UNIX (secondes) de réinitialisation de la fenêtre.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JourneysResponse"
        "400":
          description: Paramètre obligatoire manquant ou invalide.
          content: &a1
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Clé d'API absente ou invalide.
          content: *a1
        "403":
          description: Clé d'API connue mais révoquée.
          content: *a1
        "429":
          description: Quota dépassé.
          headers:
            Retry-After:
              description: Délai conseillé avant un nouvel essai, en secondes.
              schema:
                type: integer
            X-RateLimit-Limit: *a2
            X-RateLimit-Remaining: *a3
            X-RateLimit-Reset: *a4
          content: *a1
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Clé d'API fournie par Bus Citoyens (header `api_key`).
  schemas:
    Geopoint:
      type: object
      properties:
        latitude:
          type: number
          description: Latitude (degrés décimaux, WGS84).
        longitude:
          type: number
          description: Longitude (degrés décimaux, WGS84).
        city:
          description: Commune.
          type: string
        postalCode:
          description: Code postal.
          type: string
        country:
          description: Code pays ISO (ex. « FR »).
          type: string
      required:
        - latitude
        - longitude
      additionalProperties: false
    WeekSchedule:
      type: object
      properties:
        mondayTime:
          type: string
        mondayTimeDelta:
          type: integer
        tuesdayTime:
          type: string
        tuesdayTimeDelta:
          type: integer
        wednesdayTime:
          type: string
        wednesdayTimeDelta:
          type: integer
        thursdayTime:
          type: string
        thursdayTimeDelta:
          type: integer
        fridayTime:
          type: string
        fridayTimeDelta:
          type: integer
        saturdayTime:
          type: string
        saturdayTimeDelta:
          type: integer
        sundayTime:
          type: string
        sundayTimeDelta:
          type: integer
      additionalProperties: false
    Schedule:
      type: object
      properties:
        departureDate:
          type: integer
          description: Début de validité du trajet (timestamp UNIX UTC, en secondes).
        maxDate:
          description: Fin de validité éventuelle (timestamp UNIX UTC). Absent = trajet
            ouvert.
          type: integer
        regularSchedule:
          type: array
          items:
            $ref: "#/components/schemas/WeekSchedule"
        timeDelta:
          description: Marge temporelle par défaut, en secondes.
          type: integer
      required:
        - departureDate
      additionalProperties: false
    Price:
      type: object
      properties:
        type:
          type: string
          enum:
            - free
            - fixed
            - variable
            - unknown
          description: "Modèle tarifaire. Bus Citoyens est non marchand : toujours « free
            »."
        amount:
          description: Montant (absent quand type = free).
          type: number
        currency:
          description: Devise ISO 4217 (ex. « EUR »).
          type: string
      required:
        - type
      additionalProperties: false
    Carpooler:
      type: object
      properties:
        id:
          type: string
          description: Identifiant opaque pseudonymisé (non réversible).
        alias:
          type: string
          description: Libellé d'affichage générique, sans donnée personnelle.
      required:
        - id
        - alias
      additionalProperties: false
    Journey:
      type: object
      properties:
        id:
          type: string
          description: Identifiant du trajet chez l'opérateur.
        operator:
          type: string
          description: Nom de l'opérateur source.
        operatorUrl:
          description: URL de l'opérateur source.
          type: string
        webUrl:
          description: Page publique du trajet — point d'entrée de la mise en relation.
          type: string
        type:
          type: string
          enum:
            - planned
            - dynamic
            - line
          description: Type de trajet RDEX+. Bus Citoyens n'expose que des trajets
            planifiés (planned).
        carpoolerType:
          type: string
          enum:
            - driver
            - passenger
            - both
          description: "Rôle du covoitureur : conducteur, passager, ou les deux."
        availableSeats:
          description: Places proposées (conducteur / les deux).
          type: integer
        requestedSeats:
          description: Places recherchées (passager / les deux).
          type: integer
        from:
          $ref: "#/components/schemas/Geopoint"
        to:
          $ref: "#/components/schemas/Geopoint"
        distance:
          description: Distance estimée à vol d'oiseau, en mètres (indicatif).
          type: integer
        duration:
          type: integer
          description: Durée estimée du trajet, en secondes (approximation — voir
            documentation).
        frequency:
          type: string
          enum:
            - punctual
            - regular
            - both
          description: Fréquence du trajet. Tous les trajets Bus Citoyens sont réguliers
            (hebdomadaires).
        isRoundTrip:
          anyOf:
            - type: number
              enum:
                - 0
            - type: number
              enum:
                - 1
          description: 1 si un retour est proposé, 0 sinon.
        isStopped:
          anyOf:
            - type: number
              enum:
                - 0
            - type: number
              enum:
                - 1
          description: 1 si le trajet est temporairement complet/suspendu, 0 sinon.
        outward:
          $ref: "#/components/schemas/Schedule"
        return:
          allOf:
            - $ref: "#/components/schemas/Schedule"
        price:
          $ref: "#/components/schemas/Price"
        details:
          description: Commentaire libre court (≤ 140 caractères).
          type: string
        user:
          $ref: "#/components/schemas/Carpooler"
      required:
        - id
        - operator
        - type
        - carpoolerType
        - from
        - to
        - duration
        - frequency
        - isRoundTrip
        - isStopped
        - outward
        - price
        - user
      additionalProperties: false
    JourneysResponse:
      type: object
      properties:
        journeys:
          type: array
          items:
            $ref: "#/components/schemas/Journey"
        nbJourneys:
          type: integer
          description: Nombre de journeys renvoyés.
      required:
        - journeys
        - nbJourneys
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: Code d'erreur RDEX+.
        errorMessage:
          description: Description lisible de l'erreur.
          type: string
      required:
        - errorCode
      additionalProperties: false
