API e MCP per sviluppatori
PrezziBenzina.Live espone i confronti carburante come API REST pubblica e come server MCP: gli stessi dati aperti MIMIT, in sola lettura. La REST API non richiede autenticazione; il server MCP usa l’accesso gestito da Sites. Qui trovi endpoint, parametri, errori ed esempi.
API REST pubblica
Quattro endpoint GET in JSON, CORS aperto, nessun token. La specifica completa è in /openapi.json.
GET /api/v1/stazioniDistributori convenienti vicino a un punto, ordinati per costo del pieno
Parametri: lat*, lon*, carburante, quantita, consumo, raggio, limite
GET /openapi.jsonSpecifica OpenAPI 3.1 machine-readable (alias: /api/openapi.json, /api/v1/openapi.json)
Nessun parametro
GET /api/v1/geocodeIndirizzo o comune italiano → coordinate (da usare prima di /stazioni)
Parametri: luogo* (min 2 caratteri)
GET /api/v1/healthStato del servizio e versione API
Nessun parametro
I parametri con l'asterisco sono obbligatori. Limiti: lat 35–48, lon 5–20, raggio max 15 km, limite max 20 risultati. Valori predefiniti: carburante Benzina, quantità 50 L (15 kg metano), raggio 12 km, limite 5. Dettaglio machine-readable in /openapi.json (alias: /api/openapi.json).
GET https://prezzibenzina.live/api/v1/stazioni?lat=45.4642&lon=9.19&carburante=Benzina&raggio=12&limite=5
Content-Type: application/problem+json
{"title":"Parametri obbligatori mancanti","status":400,"code":"MISSING_PARAMETER",
"detail":"Mancano: lat, lon. Servono latitudine e longitudine.",
"hints":["Esempio: /api/v1/stazioni?lat=45.4642&lon=9.19&carburante=Benzina.",
"Non hai le coordinate? Prima chiama /api/v1/geocode?luogo=Milano."],
"instance":"/api/v1/stazioni?carburante=Benzina",
"documentationUrl":"https://prezzibenzina.live/developers","openapiUrl":"https://prezzibenzina.live/openapi.json"}Server MCP
Gli stessi confronti come strumenti per assistenti e agenti, con lo stesso manifest del sito.
Endpoint e autenticazione
- Endpoint: POST https://prezzibenzina.live/mcp (trasporto Streamable HTTP, JSON-RPC 2.0).
- Autenticazione: gestita da Sites tramite OAuth. Collega il Site al tuo client MCP o usa il suo plugin in ChatGPT o Codex. Gli strumenti lavorano in sola lettura su dataset pubblici.
- Accesso senza account: la REST API su /api/v1 espone gli stessi dati senza token né registrazione.
Strumenti disponibili
Stessi strumenti e stessi limiti del manifest MCP del sito.
cerca_luogoIndirizzo, comune o CAP italiano
Parametri: luogo* (min 2 caratteri)
trova_distributori_convenientilat 35–48, lon 6–19, raggio max 15 km
Parametri: lat*, lon*, carburante, quantita, consumo, raggio, limite
Valori predefiniti: carburante Benzina, quantità 50 L (15 kg metano), raggio 12 km, limite 5 risultati. Dettaglio machine-readable nella server-card MCP.
Esempio di chiamata
POST https://prezzibenzina.live/mcp
Content-Type: application/json
Authorization: Bearer <token OAuth di Sites>
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}WebMCP nel browser
La homepage espone gli stessi confronti come tool in-page per gli agenti nel browser: due tool imperativi, cerca_luogo e trova_distributori_convenienti. I due form dichiarativi sono in questa pagina.
// document.modelContext prima, navigator.modelContext solo come fallback
const mc = document.modelContext ?? navigator.modelContext;
await mc.registerTool({
name: "trova_distributori_convenienti",
description: "Distributori convenienti vicino a coordinate (dati MIMIT).",
inputSchema: { type: "object",
properties: { lat: { type: "number" }, lon: { type: "number" } },
required: ["lat", "lon"], additionalProperties: false },
annotations: { readOnlyHint: true },
execute: async ({ lat, lon }) => (await fetch(
`/api/v1/stazioni?lat=${lat}&lon=${lon}`).then((r) => r.json())),
});In più, la sezione Ricerca rapida via API qui sotto usa form dichiarativi (toolname, tooldescription, toolautosubmit) che funzionano anche senza JavaScript.
Ricerca rapida via API
Gli stessi confronti in JSON, senza geolocalizzazione.
Limiti dei dati
- Prezzi italiani da comunicazioni giornaliere dei gestori: non è tempo reale.
- Le pagine esistono solo dove ci sono abbastanza prezzi reali: un 404 indica che i dati non bastano per un confronto.
- Per uso da agenti e citazioni corrette, il riferimento è /llms.txt.