Salta al contenuto

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/stazioni

Distributori convenienti vicino a un punto, ordinati per costo del pieno

Parametri: lat*, lon*, carburante, quantita, consumo, raggio, limite

GET /openapi.json

Specifica OpenAPI 3.1 machine-readable (alias: /api/openapi.json, /api/v1/openapi.json)

Nessun parametro

GET /api/v1/geocode

Indirizzo o comune italiano → coordinate (da usare prima di /stazioni)

Parametri: luogo* (min 2 caratteri)

GET /api/v1/health

Stato 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).

Distributori benzina vicino a Milano (JSON)
GET https://prezzibenzina.live/api/v1/stazioni?lat=45.4642&lon=9.19&carburante=Benzina&raggio=12&limite=5
Risposta 400 (esempio)
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"}

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_luogo

Indirizzo, comune o CAP italiano

Parametri: luogo* (min 2 caratteri)

trova_distributori_convenienti

lat 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

Elenco strumenti (JSON-RPC)
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.

Registrazione (estratto)
// 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.

Distributori vicino a coordinate
Prezzo, deviazione e risparmio reale in JSON.
Coordinate da un luogo
Indirizzo, comune o CAP italiano; risponde con latitudine e longitudine.

Specifica in /openapi.json, esempi ed errori in documentazione API.

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.

Risorse collegate