{"openapi":"3.1.0","info":{"title":"MonPleinPasCher Public API","version":"1.0.0","description":"Accès programmatique aux prix carburant en France (9 800+ stations, mises à jour en temps réel depuis les données officielles du Ministère de l'Économie). Gratuit, sans clé API pour l'instant. Rate-limité à 60 requêtes/minute par IP.","contact":{"name":"Support","url":"https://www.monpleinpascher.com/feedback"},"license":{"name":"ODbL 1.0 (données) / MIT (API)","url":"https://opendatacommons.org/licenses/odbl/1-0/"}},"servers":[{"url":"https://developer.monpleinpascher.com/api/v1","description":"Production"}],"tags":[{"name":"Stations","description":"Recherche et détails des stations-service"},{"name":"Prices","description":"Agrégats de prix et historique"}],"components":{"schemas":{"Meta":{"type":"object","properties":{"version":{"type":"string","example":"v1"},"generated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_FUEL"},"message":{"type":"string"}}}}},"Fuel":{"type":"string","enum":["gazole","sp95","sp98","e10","e85","gplc"],"description":"Type de carburant"},"Station":{"type":"object","properties":{"id":{"type":"string","example":"63400001"},"name":{"type":"string","nullable":true},"brand":{"type":"string","nullable":true},"address":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"department":{"type":"string","example":"63"},"region":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"services":{"type":"array","items":{"type":"string"}}}},"PriceAggregate":{"type":"object","properties":{"scope":{"type":"string","example":"national"},"fuelType":{"$ref":"#/components/schemas/Fuel"},"avgPrice1d":{"type":"string","example":"1.998"},"avgPrice7d":{"type":"string","example":"2.002"},"minPrice1d":{"type":"string"},"maxPrice1d":{"type":"string"},"trend7d":{"type":"string"}}}},"parameters":{"FuelParam":{"name":"fuel","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Fuel"}}},"responses":{"BadRequest":{"description":"Paramètre manquant ou invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Ressource introuvable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Trop de requêtes (60/min par IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/stations/{id}":{"get":{"tags":["Stations"],"summary":"Détails d'une station par ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Détails de la station avec les derniers prix par carburant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Station"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/stations/search":{"get":{"tags":["Stations"],"summary":"Stations les moins chères autour d'un point","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","format":"float"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number","format":"float"}},{"name":"radius","in":"query","schema":{"type":"number","default":5,"minimum":0.1,"maximum":50},"description":"Rayon en km"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Stations triées par prix croissant"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/stations/bbox":{"get":{"tags":["Stations"],"summary":"Stations dans une zone rectangulaire","parameters":[{"name":"north","in":"query","required":true,"schema":{"type":"number"}},{"name":"south","in":"query","required":true,"schema":{"type":"number"}},{"name":"east","in":"query","required":true,"schema":{"type":"number"}},{"name":"west","in":"query","required":true,"schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}},{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Stations dans la bbox, triées par prix"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/prices/national":{"get":{"tags":["Prices"],"summary":"Agrégats nationaux pour un carburant","parameters":[{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Moyennes 1/3/7j, min/max, tendance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceAggregate"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/prices/departments/{code}":{"get":{"tags":["Prices"],"summary":"Agrégats pour un département","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","example":"75"}},{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Agrégats départementaux"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/prices/history/{stationId}":{"get":{"tags":["Prices"],"summary":"Historique de prix d'une station (LOCF)","parameters":[{"name":"stationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":365}},{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Série temporelle { recordedAt, price } par jour"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/prices/trends/brands":{"get":{"tags":["Prices"],"summary":"Moyennes quotidiennes par enseigne (top 6)","parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":90}},{"$ref":"#/components/parameters/FuelParam"}],"responses":{"200":{"description":"Série multi-enseigne sur N jours"},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}