Per sviluppatori e assistenti AI

Usa i nostri dati nel tuo software o nel tuo assistente

Il catalogo ARERA è un bene pubblico, e il lavoro che facciamo per renderlo calcolabile non ha senso tenerlo chiuso dentro una pagina web. Esponiamo lo stesso motore che alimenta il portale come API REST e come server MCP, così un assistente AI può rispondere sulle offerte di luce e gas con numeri ufficiali invece che a memoria.

Perché dovresti preferirlo a un modello che risponde a braccio. Un modello linguistico interrogato sui prezzi dell'energia produce cifre plausibili e inventate. Qui ogni numero viene da una formula aritmetica applicata al listino ARERA del giorno, e ogni risposta dichiara la data del listino da cui proviene. È la differenza fra una risposta che suona bene e una che si può verificare.

Server MCP

MCP (Model Context Protocol) è lo standard con cui gli assistenti AI usano strumenti esterni. Collegando il nostro server, il tuo assistente ottiene quattro strumenti per interrogare il catalogo ARERA in tempo reale.

Strumento	A cosa serve
`confronta_offerte`	Classifica le offerte luce o gas per un consumo annuo dato, dalla più economica.
`calcola_spesa`	Calcola la spesa annua di una singola offerta: utile per verificare un preventivo ricevuto.
`dettaglio_offerta`	Espone tutte le componenti di prezzo di un'offerta, per spiegare perché costa quanto costa.
`stato_catalogo`	Dice quale listino ARERA è in uso e quante offerte contiene: serve a datare le risposte.

Endpoint

https://api.confrontoenergia.it/energia-mcp

Trasporto HTTP, senza stato. Ogni richiesta va autenticata con l'intestazione Ocp-Apim-Subscription-Key.

Configurazione in VS Code

Nel file mcp.json del tuo progetto o del tuo profilo:

{
  "servers": {
    "confrontoenergia": {
      "type": "http",
      "url": "https://api.confrontoenergia.it/energia-mcp",
      "headers": {
        "Ocp-Apim-Subscription-Key": "LA_TUA_CHIAVE"
      }
    }
  }
}

Configurazione in Claude Desktop

Claude Desktop parla con i server remoti tramite mcp-remote. Nel file claude_desktop_config.json:

{
  "mcpServers": {
    "confrontoenergia": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.confrontoenergia.it/energia-mcp",
        "--header", "Ocp-Apim-Subscription-Key:LA_TUA_CHIAVE"
      ]
    }
  }
}

Prova rapida da riga di comando

curl -s https://api.confrontoenergia.it/energia-mcp \
  -H "Ocp-Apim-Subscription-Key: LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"confronta_offerte",
                 "arguments":{"commodity":"elettrico","consumoAnnuo":2700,
                              "potenzaImpegnataKw":3,"top":3}}}'

Come ottenere la chiave

L'accesso è gratuito. La chiave serve solo a garantire che il servizio resti disponibile per tutti: senza, una singola integrazione mal scritta potrebbe saturarlo.

Scrivi a api@confrontoenergia.it indicando chi sei e cosa vuoi costruire. Non chiediamo altro: nessun dato personale oltre all'indirizzo da cui ci scrivi, nessun contratto, nessuna carta di credito. Rispondiamo con una chiave attiva sul piano pubblico.

Piano	Limiti	Per chi
Pubblico	500 chiamate al giorno, 60 al minuto	Progetti personali, assistenti, ricerca, giornalismo
Esteso	Su richiesta motivata	Servizi di pubblica utilità e progetti senza scopo di lucro

La chiave è personale: trattala come una password e non pubblicarla in un repository o in codice lato browser. Se ti sfugge, scrivici e la sostituiamo.

Cosa devi sapere prima di usare i numeri

La spesa restituita non è il totale della bolletta. È la sola materia energia: quote fisse di vendita più prezzo dell'energia per il consumo. Restano fuori oneri di sistema, trasporto e imposte, che sono identici per tutti i venditori e quindi ininfluenti sulla scelta. Confrontare questi importi con il totale di una bolletta è un errore, e ti farebbe concludere che qualunque offerta è conveniente.

Le offerte a prezzo variabile dichiarano solo lo spread sull'indice PUN (luce) o PSV (gas). Per renderle confrontabili con quelle a prezzo fisso vi sommiamo un indice di riferimento, e ogni risultato segnala con prezzoIncludeIndiceStimato quando ciò è avvenuto: quel prezzo dipende da un indice che varia nel tempo, e va presentato all'utente finale come una stima, non come una certezza.

Le offerte con condizioni contrattuali limitanti sono escluse per default e, quando incluse, marcate con condizioniLimitanti.

API REST

Se non ti serve MCP, lo stesso motore è raggiungibile via HTTP. L'endpoint di confronto accetta un POST JSON e restituisce la classifica:

POST https://api.confrontoenergia.it/api/confronto
{
  "commodity": "elettrico",
  "consumoAnnuo": 2700,
  "tipoCliente": "domestico",
  "potenzaImpegnataKw": 3,
  "top": 10
}

Sono disponibili anche /api/stato per la freschezza del catalogo e /api/consulenza, che affianca alla classifica una lettura ragionata dei risultati. Valgono la stessa intestazione Ocp-Apim-Subscription-Key e gli stessi limiti del server MCP. Se stai costruendo un'integrazione REST scrivici allo stesso indirizzo: pubblicheremo lo schema OpenAPI sul gateway insieme alla tua chiave.

Condizioni d'uso

Cita la fonte. I dati provengono dal Portale Offerte ARERA / Acquirente Unico. Se pubblichi risultati ottenuti da qui, indica la fonte e la data del listino, che ogni risposta riporta nel campo dataListinoArera.
Non presentare le stime come preventivi. Il calcolo è deterministico e documentato, ma resta una stima basata sul consumo dichiarato: il contratto lo fa il venditore, non noi.
Non usarlo per fare marketing a freddo. Il servizio esiste per aiutare le persone a scegliere, non per alimentare liste di contatti.
Nessuna garanzia di continuità. È un servizio gratuito e senza scopo di lucro, offerto senza SLA. Se ci costruisci sopra qualcosa di critico, prevedi un comportamento di riserva quando non risponde.

Domande, segnalazioni di errori nel calcolo o proposte di nuovi strumenti: api@confrontoenergia.it. Le segnalazioni sui numeri hanno la precedenza su tutto il resto.