{
  "openapi": "3.1.0",
  "info": {
    "title": "CarbuZen - API Prix des Carburants en Temps Réel en France",
    "version": "1.0.0",
    "description": "API officielle et spécification d'accès aux données de prix des carburants (Gazole, SP95-E10, SP98, Superéthanol E85, SP95, GPLc) et des ruptures de stock en France pour les 10 000 stations-service répertoriées. Données ouvertes de la DGEC (Ministère de l'Économie et de la Transition Écologique), actualisées toutes les 10 minutes.",
    "contact": {
      "name": "CarbuZen",
      "url": "https://carbuzen.fr"
    },
    "license": {
      "name": "Licence Ouverte 2.0 (Etalab)",
      "url": "https://www.etalab.gouv.fr/licence-ouverte-open-licence/"
    }
  },
  "servers": [
    {
      "url": "https://carbuzen.fr",
      "description": "Serveur de production CarbuZen (API & passerelle IA)"
    },
    {
      "url": "https://data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/prix-des-carburants-en-france-flux-instantane-v2",
      "description": "Serveur public officiel du Ministère de l'Économie (flux instantané brut DGEC)"
    }
  ],
  "paths": {
    "/records": {
      "get": {
        "summary": "Recherche et filtrage des stations-service et de leurs prix en direct",
        "description": "Interroge le flux instantané officiel des stations-service en France. Permet de filtrer par commune, code postal, carburant disponible ou coordonnées géographiques.",
        "operationId": "getGasStationsRecords",
        "parameters": [
          {
            "name": "where",
            "in": "query",
            "required": false,
            "description": "Clause de filtrage SQL-like. Exemples: \"ville like 'NOM_COMMUNE'\", \"cp like '00%'\", \"carburants_disponibles like 'Gazole'\"",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Champs à retourner (séparés par des virgules). Exemple: \"id,adresse,ville,cp,geom,prix,rupture,horaires,services_service\"",
            "schema": {
              "type": "string",
              "default": "id,adresse,ville,cp,geom,prix,rupture,horaires,services_service"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Nombre maximum d'enregistrements retournés (maximum 100 par page)",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Index de pagination",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "order_by",
            "in": "query",
            "required": false,
            "description": "Champ de tri des enregistrements",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des stations-service correspondant aux critères",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Recherche temps réel des stations les moins chères pour Agents IA",
        "description": "Interroge instantanément les prix des carburants certifiés par l'État pour une commune ou un code postal. Renvoie les stations les moins chères triées par prix, prêtes à être citées en texte ou traitées en JSON par les LLMs et agents autonomes.",
        "operationId": "searchCheapestFuel",
        "parameters": [
          {
            "name": "carburant",
            "in": "query",
            "required": false,
            "description": "Type de carburant recherché",
            "schema": {
              "type": "string",
              "enum": [
                "gazole",
                "e10",
                "sp98",
                "e85",
                "sp95",
                "gplc"
              ],
              "default": "gazole"
            }
          },
          {
            "name": "ville",
            "in": "query",
            "required": false,
            "description": "Nom de la commune en France métropolitaine",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cp",
            "in": "query",
            "required": false,
            "description": "Code postal à 5 chiffres ou préfixe départemental",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Nombre de stations à retourner (1 à 20, défaut 5)",
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 20
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Format de sortie souhaité : json ou markdown (ou via header Accept: text/markdown)",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste ordonnée des stations les moins chères avec prix et état des stocks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "query": {
                      "type": "object"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "integer",
                            "example": 1
                          },
                          "id": {
                            "type": "string",
                            "example": "00000001"
                          },
                          "brand": {
                            "type": "string",
                            "example": "Enseigne"
                          },
                          "address": {
                            "type": "string",
                            "example": "Avenue Principale"
                          },
                          "postal_code": {
                            "type": "string",
                            "example": "00000"
                          },
                          "city": {
                            "type": "string",
                            "example": "Commune"
                          },
                          "price": {
                            "type": "number",
                            "example": 1.649
                          },
                          "fuel": {
                            "type": "string",
                            "example": "Gazole (Diesel)"
                          },
                          "status": {
                            "type": "string",
                            "example": "in_stock"
                          },
                          "updated_at": {
                            "type": "string",
                            "example": "2026-10-26T00:01:00+00:00"
                          },
                          "url": {
                            "type": "string",
                            "example": "https://carbuzen.fr/#/gazole?id=00000001"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "Tableau récapitulatif formaté en Markdown pour affichage direct à l'utilisateur"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RecordsResponse": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "integer",
            "description": "Nombre total de stations correspondant à la requête"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StationRecord"
            }
          }
        }
      },
      "StationRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifiant national unique du point de vente"
          },
          "adresse": {
            "type": "string",
            "description": "Adresse postale de la station"
          },
          "ville": {
            "type": "string",
            "description": "Nom de la commune"
          },
          "cp": {
            "type": "string",
            "description": "Code postal à 5 chiffres"
          },
          "geom": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number",
                "description": "Latitude WGS84"
              },
              "lon": {
                "type": "number",
                "description": "Longitude WGS84"
              }
            }
          },
          "prix": {
            "type": "string",
            "description": "Chaîne JSON contenant le tableau des prix déclarés (@nom, @valeur, @maj)"
          },
          "rupture": {
            "type": "string",
            "description": "Chaîne JSON contenant les éventuelles ruptures déclarées (@nom, @type, @debut)"
          },
          "services_service": {
            "type": "string",
            "description": "Services proposés par la station (automate 24-24, gonflage, lavage, etc.)"
          }
        }
      }
    }
  }
}