Documentazione API carburanti MISE
Il MISE ha una piattaforma dove è possibile ricercare informazioni sui carburanti. Chiaramente hanno anche una API pubblica, che però non è da loro documentata, quindi lo faccio io.Questo è un set di endpoint REST ai quali bisogna parlare in JSON.
Endpoint fuels
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/fuels
Metodo: GET
Qui si possono ottenere informazioni su quale codice corrisponde a quale carburante e in che modo viene erogato. Vedi endpoint zona, area, percorso e impianto.Endpoint services
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/services
Metodo: GET
Qui si possono ottenere informazioni su quale ID corrisponde a quale servizio disponibile presso il distributore. Vedi endpoint zona, area, percorso e impianto.Endpoint region
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/region
Metodo: GET
Qui si possono ottenere informazioni su quale ID corrisponde a quale regione. Vedi endpoint zona.Endpoint province
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/province
Metodo: GET
Parametro: regionId
Attenzione: l'ID della provincia è relativo ad ogni regione, e bisogna passare l'ID della regione come parametro URL nella richiesta GET stessa. Ad esempio, per poter ottenere la lista delle province della Campania, bisogna fare un GET a
https://carburanti.mise.gov.it/ospzSearch/province?regionId=8.
Struttura delle risposte
Risposta di esempio:
{
"results": [
{
"id": "AV",
"description": "Avellino"
},
{
"id": "BN",
"description": "Benevento"
},
{
"id": "CE",
"description": "Caserta"
},
{
"id": "NA",
"description": "Napoli"
},
{
"id": "SA",
"description": "Salerno"
}
]
}
Endpoint town
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/town
Metodo: GET
Parametro: province
Attenzione: l'ID della provincia è relativo ad ogni regione, e bisogna passare l'ID della regione come parametro URL nella richiesta GET stessa. Ad esempio, per poter ottenere la lista dei comuni della provincia di Livorno, bisogna fare un GET a
https://carburanti.mise.gov.it/ospzSearch/town?province=LI.
Struttura delle risposte
Risposta di esempio:
{
"results": [
{
"id": "Bibbona",
"description": "Bibbona"
},
{
"id": "Campiglia Marittima",
"description": "Campiglia Marittima"
},
(righe omesse per brevità)
{
"id": "Sassetta",
"description": "Sassetta"
},
{
"id": "Suvereto",
"description": "Suvereto"
}
]
}
Endpoint allogos
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/allogos
Metodo: GET
Qui si possono ottenere le icone di ogni distributore (es. Agip Eni, Q8, etc...)Struttura delle risposte
Risposta di esempio:
{
"loghi": [
{
"bandieraId": 0,
"bandiera": "Bandiera non selezionata",
"isEliminabile": null,
"carburantiList": null,
"logoMarkerList": []
},
{
"bandieraId": 1,
"bandiera": "Agip Eni",
"isEliminabile": null,
"carburantiList": null,
"logoMarkerList": [
{
"tipoFile": "th5",
"estensione": "png",
"content": (omesso per brevità)
},
{
"tipoFile": "th4",
"estensione": "png",
"content": (omesso per brevità)
},
(omesso per brevità)
{
"tipoFile": "logo",
"estensione": "png",
"content": (omesso per brevità)
}
]
},
(omesso per brevità)
}
loghi
Lista di tutte le icone delle catene di distributori.
loghi.bandieraId
ID univoco della catena di distributori.
loghi.bandiera
Nome della catena di distributori.
loghi.isEliminabile
Uso sconosciuto. Sembra essere sempre null.
loghi.carburantiList
Sembra essere sempre null.
loghi.logoMarkerList
Contiene una lista di tutte le icone associate a tale distributore.
loghi.logoMarkerList.tipoFile
Uso sconosciuto.
loghi.logoMarkerList.estensione
Specifica il formato e l'estensione dell'immagine.
loghi.logoMarkerList.content
Immagine codificata in base64.
Endpoint brands
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/brands
Metodo: GET
Qui si possono ottenere informazioni su quale codice corrisponde a quale catena di distributori.Endpoint zona
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/zona
Metodo: POST
A questo endpoint si fanno richieste relative ad una zona geografica ristretta (eg. "in un raggio di 5km da casa mia"). Nello specifico, la zona richiesta deve essere più piccola di 100 km2.Struttura delle richieste
Questa è una richiesta di esempio:
{
"points": [
{
"lat": 42.24038103133198,
"lng": 13.690108122548217
}
],
"fuelType": "1-x",
"priceOrder": "desc",
"radius": 5
}
points
Contiene un set di coordinate cartesiane. È possibile inviare un solo set di coordinate cartesiane
(per richiedere informazioni relative a una specifica posizione entro un certo raggio) ma anche inviare più set di
coordinate (in modo per richiedere informazioni relative ad un'area ben specifica). Ad esempio, qui richiedo le
informazioni di una zona quadrata:
"points": [
{
"lat": 45.55790865045476,
"lng": 11.986617250297979
},
{
"lat": 45.49826018466653,
"lng": 11.986617250297979
},
{
"lat": 45.509809985541054,
"lng": 12.071761293266729
},
{
"lat": 45.56367772582762,
"lng": 12.060774965141729
}
]
Questo parametro è obbligatorio.
fuelType
Specifica per quale tipo di carburante si cerca, e se si intende nello specifico self-service o
servito.
Per ottenere informazioni su quale codice corrisponde a quale carburante, basta fare una richiesta GET all'endpoint fuels.
Alcune cose da sapere:
- Con
-1si richiede il self-service - Con
-0si richiede il servito - Con
-xsi indica che è indifferente se è servito o self-service.
"fuelType": "1-0"
si richiede un distributore con benzina e servito, mentre con
"fuelType": "2-x"
si richiedono tutti i distributori che forniscono gasolio.
Questo parametro non è obbligatorio.
priceOrder
Serve a specificare se i risultati si vogliono in ordine ascendente o discendente. Si invia
desc per discendente e asc per ascendente.Questo parametro non è obbligatorio.
radius
Specifica il raggio della richiesta (ad es. 5km da questa posizione). Si invia il numero di
chilometri desiderato.Questo parametro è obbligatorio.
service
Serve a filtrare i distributori che offrono specifici servizi. Si invia l'ID del servizio richiesto
prendendolo dall'endpoint services.Questo parametro non è obbligatorio.
Struttura delle risposte
Usa lo stesso formato che usa l'endpoint area (vedi qui).Endpoint area
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/area
Metodo: POST
A questo endpoint si fanno richieste relative ad una zona geografica abbastanza ampia (anche a livello regionale, volendo).Struttura delle richieste
Questa è una richiesta di esempio:
{
"region": 9,
"province": "VT",
"town": "Barbarano Romano",
"fuelType": null,
"service": null
}
region
Il codice della regione, secondo il formato ottenuto dall'endpoint region.Questo parametro è obbligatorio.
province
Il codice della provincia, secondo il formato ottenuto dall'endpoint province.Questo parametro è obbligatorio.
town
Il codice del comune, secondo il formato ottenuto dall'endpoint town.Questo parametro è obbligatorio.
fuelType
Tipo di carburante, usa il formato dell'endpoint zona.Questo parametro è obbligatorio, ma può essere null.
service
Tipo di servizio disponibile, usa il formato dell'endpoint zona.Questo parametro è obbligatorio, ma può essere null.
Struttura delle risposte
Risposta di esempio:
{
"success": true,
"center": {
"lat": 42.249528737541915,
"lng": 12.061564028263092
},
"results": [
{
"id": 12125,
"name": "ENERPETROLI - PV BARBARANO ROMANO - VT",
"fuels": [
{
"id": 123047708,
"price": 2.149,
"name": "Benzina",
"fuelId": 1,
"isSelf": true
},
{
"id": 123047707,
"price": 2.319,
"name": "Gasolio",
"fuelId": 2,
"isSelf": true
}
],
"location": {
"lat": 42.249528737541915,
"lng": 12.061564028263092
},
"insertDate": "2026-09-21T15:35:08+02:00",
"address": "STRADA PROVINCIALE BARBARANESE KM. 2,6 SNC 01010 - BARBARANO ROMANO VT",
"brand": "Enerpetroli",
"distance": null
}
]
}
success
Ritorna se la query ha avuto successo.
center
Set di coordinate cartesiane che corrispondono alla locazione geografica della zona in cui è stata effettuata la
richiesta.
results
Contiene tutti i risultati.
results.id
ID univoco del distributore.
results.name
Nome del distributore.
results.fuels
Informazioni sui servizi di carburante forniti dal distributore.
results.fuels.id
ID univoco del servizio di carburante offerto dal distributore.
results.fuels.price
Prezzo al litro del carburante, espresso in euro con tre numeri decimali.
results.fuels.name
Nome del carburante erogato.
results.fuels.fuelId
ID del carburante, espresso nel formato che usa l'endpoint fuels.
results.fuels.isSelf
true se è self-service, false altrimenti.
results.location
Set di coordinate cartesiane dove si trova il distributore.
results.insertDate
Data e ora dell'ultimo aggiornamento dei prezzi, espresso in formato ISO 8601.
results.address
Indirizzo del distributore.
results.brand
Catena del distributore (serve per es. distributore indipendente in franchise con Agip Eni).
results.distance
Distanza fra la posizione del distributore e la località specificata nella ricerca, espressa in chilometri.
Endpoint route
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/route
Metodo: POST
A questo endpoint si fanno richieste relative a un percorso.Struttura delle richieste
Richiesta di esempio:
{
"fuelType": "2-x",
"service": null,
"points": [
{
"lat": 44.12631,
"lng": 12.47243
},
{
"lat": 44.12642,
"lng": 12.47234
},
(omesso per brevità)
{
"lat": 44.1074,
"lng": 12.50849
},
{
"lat": 44.10708,
"lng": 12.50888
}
]
}
Il formato è simile a quello dell'endpoint area.
Struttura delle risposte
Il formato è lo stesso di quello dell'endpoint area.Endpoint highway
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/highway
Metodo: POST
A questo endpoint si fanno richieste relative a una tratta autostradale.Struttura delle richieste
Richiesta di esempio:
{
"highwayId": "A10-23",
"fuelType": "4-x"
"priceOrder": "desc",
"service": "2"
}
highwayId
Il codice che identifica l'autostrada e la tratta. Se la tratta non viene specificata, viene inviato solo il nome
dell'autostrada (es. A10 nel caso di esempio).Questo parametro è obbligatorio.
fuelType
Tipo di carburante, usa il formato dell'endpoint zona.Questo parametro è obbligatorio.
priceOrder
Serve a specificare se i risultati si vogliono in ordine ascendente o discendente. Si invia
desc per discendente e asc per ascendente.Questo parametro non è obbligatorio.
service
Tipo di servizio disponibile, usa il formato dell'endpoint zona.Questo parametro non è obbligatorio.
Struttura delle risposte
Il formato è lo stesso di quello dell'endpoint area.Endpoint servicearea
Indirizzo: https://carburanti.mise.gov.it/ospzSearch/servicearea
Metodo: POST
A questo endpoint si fanno richieste relative a uno specifico "impianto" (AKA distributore).Struttura delle richieste
Richiesta di esempio:
{
"brand": "125",
"region": 14,
"province": null,
"fuelType": "1-1",
"priceOrder": "desc",
"service": "2"
}
brand
Il codice della catena, secondo il formato dell'endpoint brands.Questo parametro è obbligatorio.
region
Il codice della regione, secondo il formato dell'endpoint region.Questo parametro è obbligatorio.
province
Il codice della provincia, secondo il formato dell'endpoint province.Questo parametro è obbligatorio, ma può essere null.
fuelType
Tipo di carburante, usa il formato dell'endpoint zona.Questo parametro non è obbligatorio.
priceOrder
Serve a specificare se i risultati si vogliono in ordine ascendente o discendente. Si invia
desc per discendente e asc per ascendente.Questo parametro non è obbligatorio.
service
Tipo di servizio disponibile, usa il formato dell'endpoint zona.Questo parametro non è obbligatorio.