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 e senza autenticazione. Qui trovi endpoint, parametri, errori ed esempi.
Accesso pubblicosola letturadati giornalieri MIMIT
API REST pubblica
Quattro endpoint GET in JSON, CORS aperto, nessun token. La specifica completa è in /openapi.json.
| Endpoint | Cosa fa | Parametri |
|---|---|---|
| GET /api/v1/stazioni | Distributori convenienti vicino a un punto, ordinati per costo del pieno | lat*, lon*, carburante, quantita, consumo, raggio, limite |
| GET /openapi.json | Specifica OpenAPI 3.1 machine-readable (alias: /api/openapi.json, /api/v1/openapi.json) | — |
| GET /api/v1/geocode | Indirizzo o comune italiano → coordinate (da usare prima di /stazioni) | luogo* (min 2 caratteri) |
| GET /api/v1/health | Stato del servizio e versione API | — |
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).
Esempio REST
GET https://prezzibenzina.live/api/v1/stazioni?lat=45.4642&lon=9.19&carburante=Benzina&raggio=12&limite=5
Errori in JSON
Nessuna pagina HTML sugli endpoint /api/*: ogni errore segue RFC 9457 con codice, dettaglio e suggerimenti.
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"}Endpoint e autenticazione
- Endpoint: POST https://prezzibenzina.live/mcp (trasporto Streamable HTTP, JSON-RPC 2.0).
- Autenticazione: nessuna. Gli strumenti sono in sola lettura e lavorano su dataset pubblici.
- Chiavi e sandbox: non esistono piani, chiavi o ambienti di test: tutto ciò che è esposto è pubblico e gratuito.
Strumenti disponibili
Stessi strumenti e stessi limiti del manifest MCP del sito.
| Strumento | Parametri | Note |
|---|---|---|
| cerca_luogo | luogo* (min 2 caratteri) | Indirizzo, comune o CAP italiano |
| trova_distributori_convenienti | lat*, lon*, carburante, quantita, consumo, raggio, limite | lat 35–48, lon 6–19, raggio max 15 km |
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
{"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 più due form dichiarativi.
// 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” in homepage usa form dichiarativi (toolname, tooldescription, toolautosubmit) che funzionano anche senza JavaScript.
Limiti onesti dei dati
- Prezzi italiani da comunicazioni giornaliere dei gestori: non è tempo reale.
- Le pagine esistono solo con abbastanza prezzi reali: una 404 è «dati scarsi».
- Per uso da agenti e citazioni corrette, la riferimento è /llms.txt.