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 cinque 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.
`confronta_offerte_dual`	Classifica le offerte dual fuel (luce e gas nello stesso contratto) e le mette a confronto con le migliori luce e gas prese separatamente.
`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

spesaEnergiaAnnua non è il totale della bolletta. È la sola materia energia: quote fisse di vendita più prezzo dell'energia per il consumo. È il criterio con cui è costruita la classifica, perché oneri di sistema, trasporto e imposte sono identici per tutti i venditori e non spostano l'ordine. Se ti serve una cifra confrontabile con una bolletta reale usa il blocco bolletta, presente in ogni risultato, che aggiunge trasporto, oneri, accise e IVA sui valori ARERA in vigore (componentiRegolateDal e fonteComponentiRegolate nella risposta). Per il gas quella stima usa medie nazionali: tariffe di distribuzione e addizionale regionale variano per territorio.

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

potenzaImpegnataKw e residente riguardano il solo elettrico e influenzano la stima in bolletta (quota di rete e franchigia di accisa), non la classifica. Se omessi valgono 3 kW e abitazione di residenza, il caso più diffuso.

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.

Offerte dual fuel (luce + gas)

POST https://api.confrontoenergia.it/api/confronto-dual
{
  "consumoElettricoAnnuo": 2700,
  "consumoGasAnnuo": 1400,
  "tipoCliente": "domestico",
  "potenzaImpegnataKw": 3,
  "residente": true,
  "provincia": "016",
  "top": 10
}

ARERA pubblica le offerte dual fuel senza prezzi propri: ogni offerta dichiara i codici delle due offerte — una elettrica e una gas — che la compongono. Noi le risolviamo nei listini ufficiali e ne sommiamo i costi con lo stesso motore del confronto singolo: nessuno sconto viene ipotizzato. Ogni risultato porta i blocchi luce e gas con il dettaglio delle due componenti, il totale spesaEnergiaTotaleAnnua e soloInCoppia, valorizzato solo quando il venditore dichiara espressamente che le due forniture non sono sottoscrivibili separatamente. La risposta contiene anche separate, cioè la migliore luce e la migliore gas prese singolarmente alle stesse condizioni, e risparmioDualRispettoASeparate: senza quel raffronto la classifica dual non direbbe la cosa che davvero interessa. offerteNonRisolte conta le coppie escluse perché una componente non compare nei listini pubblicati.

Simulazione di scenario

POST https://api.confrontoenergia.it/api/scenari
{
  "commodity": "elettrico",
  "consumoAnnuo": 2700,
  "variazioneConsumoPercento": 10,
  "variazioneIndicePercento": 15,
  "prezzoMateriaPrima": 0.12,
  "spesaEnergiaAttuale": 720
}

Confronta la migliore offerta fissa e variabile allo stesso profilo, calcola il punto di pareggio dell'indice e l'eventuale differenza dalla spesa attuale. Prezzi, scenari e classifiche sono calcolati dal motore deterministico: nessun numero è generato dall'IA.

Copilota e spiegazione bolletta

POST https://api.confrontoenergia.it/api/copilota
{
  "conversazione": [
    { "ruolo": "utente", "testo": "Con 2700 kWh conviene un prezzo fisso?" }
  ]
}

Il Copilota sceglie quali strumenti deterministici interrogare e restituisce anche la provenienza strutturata delle offerte citate (listino, codice, URL e data). La conversazione è limitata per dimensione e la risposta segnala quando il contesto è stato troncato. Per spiegare il testo di una fattura voce per voce è disponibile POST /api/spiega-bolletta con {"testo":"..."}; ogni voce può includere l'evidenza estratta dal testo sorgente.

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.

La lettura ragionata è generata da un'intelligenza artificiale. Il campo fonte della risposta di /api/consulenza vale ai quando il testo è prodotto da un modello linguistico senza revisione umana, e deterministica quando è composto dal motore di calcolo. Numeri, prezzi e ordinamento non passano mai dal modello. Se ripubblichi quel testo, dichiara che è generato da un sistema di IA: l'art. 50 del Regolamento (UE) 2024/1689 (AI Act) lo chiede a chi lo mette davanti al pubblico, e da qui in poi quello sei tu.

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. La menzione della fonte non è cortesia ma condizione d'uso posta dal Portale Offerte, che consente il riuso dei dati aperti per finalità non commerciali. I valori delle componenti regolate derivano da documenti ARERA riutilizzati con licenza CC BY-SA 4.0. I loghi di ARERA e del Portale Offerte non sono riutilizzabili senza autorizzazione: non li usiamo noi e non puoi usarli tu appoggiandoti a questa API.
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.