{"openapi":"3.1.0","info":{"title":"PrezziBenzina.Live Public API","version":"1.0.0","description":"API pubblica in sola lettura di PrezziBenzina.Live: distributori convenienti vicino a un punto in Italia, geocoding italiano e stato del servizio — elaborazioni sui dati aperti MIMIT (Osservatorio prezzi carburanti). Nessuna autenticazione, nessun piano, tutto gratuito. Servita anche da /api/openapi.json e /api/v1/openapi.json. Ogni errore segue RFC 9457 (application/problem+json) con codice machine-readable, dettaglio e suggerimenti.","contact":{"name":"PrezziBenzina.Live","url":"https://prezzibenzina.live/contact"},"license":{"name":"Italian Open Data License v2.0 (dati MIMIT, via Osservatorio prezzi)","url":"https://prezzibenzina.live/osservatorio-prezzi"}},"servers":[{"url":"https://prezzibenzina.live","description":"Produzione"}],"tags":[{"name":"stazioni","description":"Confronti carburante vicino a un punto."},{"name":"geocode","description":"Indirizzo o comune italiano → coordinate."},{"name":"meta","description":"Stato del servizio e discovery."}],"externalDocs":{"description":"Guida per sviluppatori ed esempi","url":"https://prezzibenzina.live/developers"},"paths":{"/api/v1/stazioni":{"get":{"tags":["stazioni"],"operationId":"cercaStazioni","summary":"Distributori più convenienti vicino a un punto","description":"Ordina per costo totale del pieno (prezzo + carburante consumato per la deviazione andata e ritorno), non per €/L. Dati MIMIT con aggiornamento giornaliero.","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":35,"maximum":48},"description":"Latitudine del punto di partenza (Italia)."},{"name":"lon","in":"query","required":true,"schema":{"type":"number","minimum":5,"maximum":20},"description":"Longitudine del punto di partenza (Italia)."},{"name":"carburante","in":"query","required":false,"schema":{"type":"string","enum":["Benzina","Gasolio","GPL","Metano"],"default":"Benzina"},"description":"Tipo di carburante. «diesel» è accettato come alias di Gasolio."},{"name":"quantita","in":"query","required":false,"schema":{"type":"number","minimum":5,"maximum":120,"default":50},"description":"Quantità da acquistare: litri, oppure kg per il metano (default 50 L o 15 kg). Alias: litri."},{"name":"consumo","in":"query","required":false,"schema":{"type":"number","minimum":2,"maximum":30,"default":7},"description":"Consumo per 100 km: litri, oppure kg per il metano (default 7 L o 4 kg)."},{"name":"raggio","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":15,"default":12},"description":"Raggio di ricerca in km (max 15)."},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":5},"description":"Numero massimo di distributori restituiti."}],"responses":{"200":{"description":"Confronto calcolato.","content":{"application/json":{"schema":{"type":"object","required":["carburante","quantita","unita","consumo","raggioKm","fuoriRaggio","fonteDistanza","stazioni","calcolatoIl"],"properties":{"carburante":{"type":"string"},"quantita":{"type":"number"},"unita":{"type":"string","enum":["L","kg"]},"consumo":{"type":"number"},"raggioKm":{"type":"number"},"fuoriRaggio":{"type":"boolean","description":"True quando nessun impianto rientra nel raggio e viene mostrato comunque il più vicino."},"fonteDistanza":{"type":"string","enum":["strada","stimata"]},"estrazioneMimit":{"type":["string","null"]},"aggiornamento":{"type":["string","null"]},"calcolatoIl":{"type":"string","format":"date-time"},"fonte":{"type":"string"},"stazioni":{"type":"array","items":{"type":"object","required":["id","bandiera","nome","indirizzo","comune","lat","lon","prezzoUnitario","unita","self","distanzaStradaKm","deviazioneAndataRitornoKm","costoPienoEur","costoViaggioEur","risparmioRealeEur","aggiornato","mapsUrl"],"properties":{"id":{"type":"string","description":"ID impianto MIMIT."},"bandiera":{"type":"string"},"nome":{"type":"string"},"indirizzo":{"type":"string"},"comune":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"prezzoUnitario":{"type":"number","description":"Euro per litro (per kg per il metano)."},"unita":{"type":"string","enum":["L","kg"]},"self":{"type":"boolean"},"distanzaStradaKm":{"type":"number"},"deviazioneAndataRitornoKm":{"type":"number"},"costoPienoEur":{"type":"number"},"costoViaggioEur":{"type":"number"},"risparmioRealeEur":{"type":"number"},"aggiornato":{"type":"string"},"mapsUrl":{"type":"string","format":"uri"}}}}}}}}},"400":{"description":"Parametro mancante o non valido.","content":{"application/problem+json":{"schema":{"type":"object","required":["code","title","status","detail","hints"],"properties":{"type":{"type":"string","format":"uri"},"code":{"type":"string","description":"Codice errore machine-readable, stabile nel tempo.","example":"MISSING_PARAMETER"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"Cosa è andato storto, in dettaglio."},"hints":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Come risolvere: azioni concrete con esempi."},"instance":{"type":"string"},"documentationUrl":{"type":"string","format":"uri"},"openapiUrl":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/geocode":{"get":{"tags":["geocode"],"operationId":"geocodeLuogo","summary":"Indirizzo o comune italiano → coordinate","description":"Geocoding di supporto via OpenStreetMap Nominatim, limitato all'Italia. Da usare prima di /api/v1/stazioni quando si parte da un nome di luogo.","parameters":[{"name":"luogo","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Indirizzo, comune o CAP italiano, es. «Milano» o «Via Roma 1, Torino». Alias: q."}],"responses":{"200":{"description":"Luoghi trovati.","content":{"application/json":{"schema":{"type":"object","required":["luogo","risultati"],"properties":{"luogo":{"type":"string"},"risultati":{"type":"array","items":{"type":"object","required":["nome","lat","lon"],"properties":{"nome":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}}}}}}}}},"400":{"description":"Parametro luogo mancante o troppo corto.","content":{"application/problem+json":{"schema":{"type":"object","required":["code","title","status","detail","hints"],"properties":{"type":{"type":"string","format":"uri"},"code":{"type":"string","description":"Codice errore machine-readable, stabile nel tempo.","example":"MISSING_PARAMETER"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"Cosa è andato storto, in dettaglio."},"hints":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Come risolvere: azioni concrete con esempi."},"instance":{"type":"string"},"documentationUrl":{"type":"string","format":"uri"},"openapiUrl":{"type":"string","format":"uri"}}}}}},"404":{"description":"Nessun luogo trovato in Italia.","content":{"application/problem+json":{"schema":{"type":"object","required":["code","title","status","detail","hints"],"properties":{"type":{"type":"string","format":"uri"},"code":{"type":"string","description":"Codice errore machine-readable, stabile nel tempo.","example":"MISSING_PARAMETER"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"Cosa è andato storto, in dettaglio."},"hints":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Come risolvere: azioni concrete con esempi."},"instance":{"type":"string"},"documentationUrl":{"type":"string","format":"uri"},"openapiUrl":{"type":"string","format":"uri"}}}}}}}}},"/api/v1/health":{"get":{"tags":["meta"],"operationId":"statoServizio","summary":"Stato del servizio","description":"Controllo leggero senza dipendenze upstream. Non tocca il dataset MIMIT.","responses":{"200":{"description":"Servizio attivo.","content":{"application/json":{"schema":{"type":"object","required":["status","version","time","endpoints","openapi"],"properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"time":{"type":"string","format":"date-time"},"endpoints":{"type":"array","items":{"type":"string"}},"openapi":{"type":"string","format":"uri"}}}}}}}}}}}