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": "eedb1c4d22e14d52add459d43bd2ba07"
      }
    }
  }
}

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:eedb1c4d22e14d52add459d43bd2ba07"
      ]
    }
  }
}

Prova rapida da riga di comando

curl -s https://api.confrontoenergia.it/energia-mcp \
  -H "Ocp-Apim-Subscription-Key: eedb1c4d22e14d52add459d43bd2ba07" \
  -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}}}'

La chiave di accesso

L'accesso è gratuito e senza registrazione: la chiave del piano pubblico è qui sotto, copiala e usala. Non serve scrivere a nessuno, non serve dire chi sei.

Ocp-Apim-Subscription-Key: eedb1c4d22e14d52add459d43bd2ba07

Puoi pubblicarla nel tuo codice senza timore: i limiti sono contati per indirizzo IP, non per chiave. Chi la condivide non consuma il tuo tetto giornaliero e tu non consumi il suo. La chiave serve solo a distinguere il traffico delle integrazioni da quello del sito, non a identificarti.

Piano	Limiti	Per chi
Pubblico	50 chiamate al giorno per indirizzo IP, con un tetto di 20 al minuto	Progetti personali, assistenti, ricerca, giornalismo
Esteso	Su richiesta motivata, con chiave dedicata e limiti più alti	Servizi di pubblica utilità e progetti senza scopo di lucro

Oltre i limiti il gateway risponde 429 Too Many Requests: non è un guasto, basta riprovare più tardi. Se 50 chiamate al giorno non ti bastano scrivi a api@confrontoenergia.it raccontando cosa stai costruendo: il tetto esiste per tenere in piedi il servizio, non per contarti addosso.

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,
  "provincia": "016",
  "top": 10
}

regione e provincia sono facoltativi e accettano il codice ISTAT (2 e 3 cifre): servono a escludere le offerte che il venditore non attiva in quella zona. L'elenco dei codici è su GET /api/zone. Non chiediamo l'indirizzo: il dettaglio massimo è la provincia. Ogni risultato porta un blocco dettaglio con durata del prezzo, indice, validità, ambito territoriale, vincoli di consumo/potenza e sconti dichiarati.

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, la stessa chiave pubblica e gli stessi limiti del server MCP. Se stai costruendo un'integrazione REST scrivici: pubblicheremo lo schema OpenAPI sul gateway.

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.