Riferimento tecnicov1openapi.json ↗

Documentazione API

Tutto quello che serve per integrare i dati di Energy Index: autenticazione, limiti, formati, codici di errore e il contratto di ogni endpoint.

Introduzione

L'API Energy Index e' un'API REST in sola lettura (salvo gli alert) che espone i prezzi all'ingrosso dell'energia in Italia e gli indici derivati calcolati da Energy Index. Tutte le risposte sono JSON in UTF-8; alcuni endpoint supportano anche CSV.

Open · gratis

Nessuna chiave

Illimitata (uso ragionevole) · 60 richieste/minuto per IP

Developer · gratis

API key gratuita

10.000 richieste/mese · 120 richieste/minuto

API · 99 €

API key

100.000 richieste/mese · 600 richieste/minuto

Gli endpoint contrassegnati In arrivo hanno il contratto pubblicato in anteprima ma non rispondono ancora. Path e campi possono cambiare prima del rilascio; gli endpoint Live sono stabili.

Avvio rapido

La prima chiamata non richiede registrazione:

terminale

curl https://energyindex.it/api/v1/pun/today

Con una chiave (piani Developer e superiori), passala nell'header Authorization:

terminale

export EIDX_API_KEY="eidx_live_••••••••"

curl "https://energyindex.it/api/v1/pun/zones?date=2026-09-26" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Autenticazione

Gli endpoint del piano Open sono pubblici. Tutti gli altri richiedono una API key, che ha il formato eidx_live_ seguito da 32 caratteri. La chiave va inviata in ogni richiesta:

Metodo	Esempio	Quando usarlo
`Authorization`	`Bearer eidx_live_…`	Sempre, e' il metodo consigliato.
`?key=`	`…/series?format=csv&key=eidx_live_…`	Solo per CSV in strumenti che non permettono header (IMPORTDATA, Power Query).

La chiave e' personale: non inserirla nel codice JavaScript di pagine pubbliche. Per mostrare dati in un sito usa gli endpoint Open, oppure chiama l'API dal tuo server. Se una chiave e' stata esposta, scrivi a pro@energyindex.pro e la revochiamo.

Una chiave usata su un endpoint di un piano superiore riceve 403 tier_required, con il piano necessario nel campo required_tier.

Base URL e versioni

base URL

https://energyindex.it/api/v1

La versione e' nel path. Dentro /v1 aggiungiamo solo campi e endpoint nuovi, mai modifiche incompatibili.
Il tuo codice deve ignorare i campi che non conosce.
Un endpoint deprecato continua a funzionare per almeno 12 mesi e risponde con gli header Deprecation e Sunset (RFC 8594).
Solo HTTPS. Le richieste a energyindex.pro e www. vengono reindirizzate al dominio canonico: usa sempre energyindex.it per evitare il redirect.

Formati, unita' e date

Aspetto	Convenzione
Formato	JSON UTF-8. Con format=csv: separatore ';', decimali con la virgola, intestazione nella prima riga.
Prezzi energia e gas	value in €/kWh (5 decimali) per la lettura in bolletta, value_native in €/MWh come pubblicato da GME.
Brent e CO2	$/bbl e €/tCO2, solo nel campo value.
Giorni di mercato	YYYY-MM-DD nel fuso Europe/Rome.
Timestamp	ISO 8601. observed_at in UTC (Z); gli orari del PUN orario con offset Europe/Rome (+01:00 / +02:00).
Cambio ora	Nei giorni di passaggio ora legale/solare il PUN orario ha 23 o 25 ore.
Numeri	Numeri JSON, mai stringhe. Nessun valore mancante e' restituito come 0.

Limiti di utilizzo

Piano	Richieste/minuto	Richieste/mese	Storico
Open · gratis	60 richieste/minuto per IP	Illimitata (uso ragionevole)	Ultimi 30 giorni
Developer · gratis	120 richieste/minuto	10.000 richieste/mese	Fino a 2 anni
API · 99 €	600 richieste/minuto	100.000 richieste/mese	Storico completo
Pro	1.200 richieste/minuto	500.000 richieste/mese	Storico completo
Trading	3.000 richieste/minuto	2.000.000 richieste/mese	Storico completo
Enterprise	Su misura	Su misura	Storico completo + export bulk

Ogni risposta include lo stato dei limiti:

header di risposta

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1790502000
X-Quota-Remaining: 94210

Oltre il limite la risposta e' 429 rate_limited con l'header Retry-Afterin secondi. Riprova dopo quel tempo con un backoff esponenziale. I dati cambiano al massimo qualche volta al giorno: se interroghi lo stesso endpoint piu' di una volta ogni 15 minuti, stai solo consumando quota.

Errori

Gli errori usano i codici HTTP standard e un corpo JSON sempre uguale:

403 Forbidden

{
  "error": "tier_required",
  "message": "Questo endpoint richiede il piano API o superiore.",
  "required_tier": "api",
  "docs": "https://energyindex.it/it/api/docs#limiti"
}

HTTP	error	Significato
`400`	`invalid_parameter`	Parametro mancante o non valido. Il campo param indica quale.
`401`	`missing_key / invalid_key`	Chiave assente, errata o revocata.
`403`	`tier_required`	L'endpoint o l'intervallo richiesto non e' incluso nel tuo piano.
`404`	`not_found`	Endpoint o risorsa inesistente.
`429`	`rate_limited / quota_exceeded`	Limite al minuto o quota mensile superati.
`500`	`internal_error`	Errore nostro. Riprova; se persiste, scrivici con l'header X-Request-Id.
`503`	`no_data`	La fonte non ha ancora pubblicato il dato (es. PUN richiesto prima dell'esito del MGP).

Cache e CORS

Le risposte sono servite da CDN con Cache-Control: public, max-age=900, stale-while-revalidate=3600: un nuovo valore compare al massimo 15 minuti dopo la pubblicazione della fonte.
Gli endpoint Open hanno Access-Control-Allow-Origin: * e rispondono a OPTIONS: si possono chiamare direttamente da JavaScript nel browser.
Gli endpoint con chiave vanno chiamati lato server: il browser esporrebbe la chiave.

Webhook

Con POST /alerts registri una soglia; quando l'indice la attraversa, inviamo una POST al tuo URL:

payload inviato al tuo webhook_url

{
  "type": "alert.triggered",
  "alert_id": "alr_8Kq2mZ",
  "asset": "PSV",
  "condition": "above",
  "threshold": 45,
  "value": 46.2,
  "unit": "€/MWh",
  "date": "2026-09-26",
  "triggered_at": "2026-09-26T16:04:11Z"
}

Ogni chiamata ha l'header X-EIDX-Signature: HMAC-SHA256 del corpo grezzo con il signing_secretdell'alert. Verificalo prima di fidarti del contenuto:

verifica.js

import crypto from "node:crypto";

export function isValid(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Rispondi con un 2xx entro 10 secondi. In caso di errore ritentiamo 5 volte in 24 ore con backoff esponenziale; dopo 20 fallimenti consecutivi l'alert viene sospeso e ti avvisiamo via email.

Attribuzione e licenza

Nei piani Open e Developer i dati sono utilizzabili gratuitamente, anche a fini commerciali, a condizione di mostrare accanto al dato la fonte con un link a energyindex.it. Ogni risposta contiene il testo pronto nel campo attribution.

<p>Fonte: <a href="https://energyindex.it" target="_blank" rel="noopener">Energy Index</a></p>

Dal piano API l'attribuzione e' facoltativa; Enterprise include l'uso white-label.
I dati di origine restano soggetti alle condizioni delle rispettive fonti (GME, ARERA, ICE Endex, EIA, EEX). Energy Index li ridistribuisce a scopo informativo.
Non e' consentito rivendere l'API tale e quale come servizio concorrente.
I forecast sono stime statistiche, non consulenza finanziaria o raccomandazioni di investimento.

Changelog

2026-09-27
Pubblicati documentazione, piani e contratti in anteprima di tutti gli endpoint. Spec OpenAPI 3.1.
2026-06-28
Lancio v1: /pun/today, /psv/today, /today.

Endpoint

Prezzi di mercato

PUN nazionale e zonale, PSV, TTF, Brent, CO2: valori del giorno e serie storiche.

GET/today

LiveOpen · gratisjsonCache: 15 minuti

Snapshot di tutti gli indici

Restituisce l'ultimo valore disponibile di ogni indice. Pensato per dashboard e widget che mostrano una fotografia del mercato senza fare cinque richieste. Gli indici senza dato disponibile vengono omessi, non restituiti come null.

Richiesta

curl "https://energyindex.it/api/v1/today"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "values": {
    "PUN": {
      "date": "2026-09-26",
      "value": 0.11873,
      "unit": "€/kWh",
      "value_native": 118.73,
      "unit_native": "€/MWh",
      "asset": "PUN",
      "source": "GME"
    },
    "PSV": {
      "date": "2026-09-26",
      "value": 0.03902,
      "unit": "€/kWh",
      "value_native": 39.02,
      "unit_native": "€/MWh",
      "asset": "PSV",
      "source": "GME"
    },
    "TTF": {
      "date": "2026-09-26",
      "value": 0.03511,
      "unit": "€/kWh",
      "value_native": 35.11,
      "unit_native": "€/MWh",
      "asset": "TTF",
      "source": "ICE Endex"
    },
    "Brent": {
      "date": "2026-09-26",
      "value": 71.42,
      "unit": "$/bbl",
      "asset": "Brent",
      "source": "EIA"
    },
    "CO2": {
      "date": "2026-09-26",
      "value": 68.9,
      "unit": "€/tCO2",
      "asset": "CO2",
      "source": "EEX"
    }
  },
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)",
  "source_page": "https://energyindex.it/it",
  "docs": "https://energyindex.it/api/v1"
}

Campi della risposta

Campo	Tipo	Descrizione
`date`	string (YYYY-MM-DD)	Giorno di mercato del PUN (indice principale).
`values`	object	Mappa sigla → oggetto con lo stesso schema di /pun/today.
`attribution`	string	Testo di attribuzione da mostrare.
`source_page`	string	Pagina Energy Index da linkare.

GET/pun/today

LiveOpen · gratisjsonCache: 15 minuti

PUN di oggi

Ultimo PUN pubblicato dal GME dopo la chiusura del Mercato del Giorno Prima, di norma entro il primo pomeriggio. Il valore e' fornito sia in €/kWh, comodo per ragionare in bolletta, sia nell'unita' nativa €/MWh.

Richiesta

curl "https://energyindex.it/api/v1/pun/today"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "observed_at": "2026-09-26T10:30:00.000Z",
  "value": 0.11873,
  "unit": "€/kWh",
  "value_native": 118.73,
  "unit_native": "€/MWh",
  "asset": "PUN",
  "asset_name": "Prezzo Unico Nazionale energia elettrica Italia",
  "source": "GME",
  "source_url": "https://www.mercatoelettrico.org",
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)",
  "page": "https://energyindex.it/it/indice/pun"
}

Campi della risposta

Campo	Tipo	Descrizione
`date`	string (YYYY-MM-DD)	Giorno di mercato dell'osservazione.
`observed_at`	string (ISO 8601)	Timestamp UTC dell'osservazione.
`value`	number	Valore in unita' consumer (€/kWh per energia e gas, $/bbl per Brent, €/tCO2 per CO2).
`unit`	string	Unita' del campo value.
`value_native`	number?	Valore nell'unita' nativa della fonte (€/MWh). Assente se coincide con value.
`unit_native`	string?	Unita' nativa. Assente se coincide con unit.
`asset`	string	Sigla dell'indice (PUN, PSV, TTF, Brent, CO2).
`asset_name`	string	Nome esteso dell'indice.
`source`	string	Fonte ufficiale del dato (GME, ICE Endex, EIA, EEX).
`source_url`	string	URL della fonte ufficiale.
`attribution`	string	Testo di attribuzione da mostrare accanto al dato.
`page`	string	Pagina di dettaglio su energyindex.it da linkare.

GET/psv/today

LiveOpen · gratisjsonCache: 15 minuti

PSV di oggi

Ultimo PSV giornaliero pubblicato dal GME, in €/kWh e nell'unita' nativa €/MWh. Riferimento delle offerte gas a prezzo variabile.

Richiesta

curl "https://energyindex.it/api/v1/psv/today"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "observed_at": "2026-09-26T16:00:00.000Z",
  "value": 0.03902,
  "unit": "€/kWh",
  "value_native": 39.02,
  "unit_native": "€/MWh",
  "asset": "PSV",
  "asset_name": "Punto di Scambio Virtuale gas naturale Italia",
  "source": "GME",
  "source_url": "https://www.mercatoelettrico.org",
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)",
  "page": "https://energyindex.it/it/indice/psv"
}

Campi della risposta

Campo	Tipo	Descrizione
`date`	string (YYYY-MM-DD)	Giorno di mercato dell'osservazione.
`observed_at`	string (ISO 8601)	Timestamp UTC dell'osservazione.
`value`	number	Valore in unita' consumer (€/kWh per energia e gas, $/bbl per Brent, €/tCO2 per CO2).
`unit`	string	Unita' del campo value.
`value_native`	number?	Valore nell'unita' nativa della fonte (€/MWh). Assente se coincide con value.
`unit_native`	string?	Unita' nativa. Assente se coincide con unit.
`asset`	string	Sigla dell'indice (PUN, PSV, TTF, Brent, CO2).
`asset_name`	string	Nome esteso dell'indice.
`source`	string	Fonte ufficiale del dato (GME, ICE Endex, EIA, EEX).
`source_url`	string	URL della fonte ufficiale.
`attribution`	string	Testo di attribuzione da mostrare accanto al dato.
`page`	string	Pagina di dettaglio su energyindex.it da linkare.

GET/{asset}/today

In arrivoOpen · gratisjsonCache: 15 minuti

TTF, Brent e CO2 di oggi

Estende il pattern /{asset}/today agli indici di contesto: TTF (gas europeo), Brent (petrolio) e CO2 (quote EU ETS). Oggi questi valori sono gia' disponibili dentro /today.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	path	string	Indice richiesto.`ttfbrentco2`

Richiesta

curl "https://energyindex.it/api/v1/ttf/today"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "observed_at": "2026-09-26T17:30:00.000Z",
  "value": 0.03511,
  "unit": "€/kWh",
  "value_native": 35.11,
  "unit_native": "€/MWh",
  "asset": "TTF",
  "asset_name": "Title Transfer Facility gas Europa",
  "source": "ICE Endex",
  "source_url": "https://www.theice.com",
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)",
  "page": "https://energyindex.it/it/indice/ttf"
}

Campi della risposta

Campo	Tipo	Descrizione
`date`	string (YYYY-MM-DD)	Giorno di mercato dell'osservazione.
`observed_at`	string (ISO 8601)	Timestamp UTC dell'osservazione.
`value`	number	Valore in unita' consumer (€/kWh per energia e gas, $/bbl per Brent, €/tCO2 per CO2).
`unit`	string	Unita' del campo value.
`value_native`	number?	Valore nell'unita' nativa della fonte (€/MWh). Assente se coincide con value.
`unit_native`	string?	Unita' nativa. Assente se coincide con unit.
`asset`	string	Sigla dell'indice (PUN, PSV, TTF, Brent, CO2).
`asset_name`	string	Nome esteso dell'indice.
`source`	string	Fonte ufficiale del dato (GME, ICE Endex, EIA, EEX).
`source_url`	string	URL della fonte ufficiale.
`attribution`	string	Testo di attribuzione da mostrare accanto al dato.
`page`	string	Pagina di dettaglio su energyindex.it da linkare.

GET/prices/{asset}/series

In arrivoOpen · gratisjsoncsvCache: 1 ora

Serie storica giornaliera

Serie giornaliera di un indice tra due date. La profondita' storica dipende dal piano. Con format=csv la risposta e' un file CSV con separatore ';' e decimali con la virgola, pronto per Excel in italiano e per IMPORTDATA di Google Sheets.

Open · gratis

Ultimi 30 giorni, solo JSON

Developer · gratis

Fino a 2 anni, JSON e CSV

API · 99 €

Storico completo

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	path	string	Indice richiesto.`punpsvttfbrentco2`
`from`	query	string	Data iniziale inclusa (YYYY-MM-DD). Default: 30 giorni fa.
`to`	query	string	Data finale inclusa (YYYY-MM-DD). Default: oggi.
`unit`	query	string	Unita' dei valori.`kwhmwh`Default: `mwh`
`format`	query	string	Formato della risposta.`jsoncsv`Default: `json`

Richiesta

curl "https://energyindex.it/api/v1/prices/pun/series?from=2026-09-20&to=2026-09-26"

Risposta 200

application/json

{
  "asset": "PUN",
  "unit": "€/MWh",
  "from": "2026-09-20",
  "to": "2026-09-26",
  "count": 7,
  "points": [
    {
      "date": "2026-09-20",
      "value": 112.4
    },
    {
      "date": "2026-09-21",
      "value": 104.87
    },
    {
      "date": "2026-09-22",
      "value": 121.06
    },
    {
      "date": "2026-09-23",
      "value": 124.31
    },
    {
      "date": "2026-09-24",
      "value": 119.52
    },
    {
      "date": "2026-09-25",
      "value": 116.9
    },
    {
      "date": "2026-09-26",
      "value": 118.73
    }
  ],
  "stats": {
    "min": 104.87,
    "max": 124.31,
    "avg": 116.98
  },
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)"
}

Campi della risposta

Campo	Tipo	Descrizione
`asset`	string	Sigla dell'indice.
`unit`	string	Unita' dei valori in points.
`from / to`	string	Intervallo effettivamente restituito, dopo i limiti del piano.
`count`	integer	Numero di punti.
`points[]`	array	Coppie { date, value } in ordine cronologico.
`stats`	object	Minimo, massimo e media dell'intervallo.

GET/pun/zones

In arrivoDeveloper · gratisjsoncsvCache: 1 ora

PUN per zona di mercato

Prezzi zonali del Mercato del Giorno Prima per Nord, Centro-Nord, Centro-Sud, Sud, Sicilia e Sardegna, piu' il PUN nazionale, con lo spread di ogni zona rispetto al nazionale.

Parametri

Nome	In	Tipo	Descrizione
`date`	query	string	Giorno di mercato (YYYY-MM-DD). Default: ultimo disponibile.

Richiesta

curl "https://energyindex.it/api/v1/pun/zones?date=2026-09-26" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "unit": "€/MWh",
  "national": 118.73,
  "zones": [
    {
      "code": "nord",
      "name": "Nord",
      "value": 117.95,
      "spread_vs_pun": -0.78
    },
    {
      "code": "cnor",
      "name": "Centro-Nord",
      "value": 119.4,
      "spread_vs_pun": 0.67
    },
    {
      "code": "csud",
      "name": "Centro-Sud",
      "value": 119.88,
      "spread_vs_pun": 1.15
    },
    {
      "code": "sud",
      "name": "Sud",
      "value": 116.2,
      "spread_vs_pun": -2.53
    },
    {
      "code": "sici",
      "name": "Sicilia",
      "value": 127.64,
      "spread_vs_pun": 8.91
    },
    {
      "code": "sard",
      "name": "Sardegna",
      "value": 119.88,
      "spread_vs_pun": 1.15
    }
  ],
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)"
}

Campi della risposta

Campo	Tipo	Descrizione
`national`	number	PUN nazionale del giorno (€/MWh).
`zones[].code`	string	Codice zona: nord, cnor, csud, sud, sici, sard.
`zones[].value`	number	Prezzo zonale medio giornaliero (€/MWh).
`zones[].spread_vs_pun`	number	Differenza zona − PUN nazionale (€/MWh).

GET/pun/hourly

In arrivoAPI · 99 €jsoncsvCache: 1 ora

PUN orario per zona

Prezzi orari del MGP per il PUN nazionale o per una singola zona. E' la base per spostare i consumi nelle ore piu' economiche, calcolare profili F1/F2/F3 o ricostruire il costo di un profilo di carico reale.

Parametri

Nome	In	Tipo	Descrizione
`zone`	query	string	Zona di mercato.`nazionalenordcnorcsudsudsicisard`Default: `nazionale`
`date`	query	string	Giorno di mercato (YYYY-MM-DD). In alternativa usare from/to (max 31 giorni).
`from`	query	string	Data iniziale (YYYY-MM-DD).
`to`	query	string	Data finale (YYYY-MM-DD).

Richiesta

curl "https://energyindex.it/api/v1/pun/hourly?zone=nord&date=2026-09-27" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "zone": "nord",
  "date": "2026-09-27",
  "unit": "€/MWh",
  "timezone": "Europe/Rome",
  "hours": [
    {
      "hour": 1,
      "starts_at": "2026-09-27T00:00:00+02:00",
      "value": 104.1,
      "band": "F3"
    },
    {
      "hour": 2,
      "starts_at": "2026-09-27T01:00:00+02:00",
      "value": 98.62,
      "band": "F3"
    },
    {
      "hour": 14,
      "starts_at": "2026-09-27T13:00:00+02:00",
      "value": 71.3,
      "band": "F3"
    },
    {
      "hour": 20,
      "starts_at": "2026-09-27T19:00:00+02:00",
      "value": 168.45,
      "band": "F3"
    }
  ],
  "cheapest_hours": [
    13,
    14,
    15
  ],
  "stats": {
    "min": 71.3,
    "max": 168.45,
    "avg": 117.95
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`hours[].hour`	integer	Ora di mercato 1–24 (1–23 o 1–25 nei cambi d'ora).
`hours[].starts_at`	string (ISO 8601)	Inizio dell'ora con offset Europe/Rome.
`hours[].value`	number	Prezzo orario (€/MWh).
`hours[].band`	string	Fascia ARERA: F1, F2 o F3.
`cheapest_hours`	integer[]	Le tre ore meno care del giorno.

Endpoint

Energy Index e mercato libero

Gli indici proprietari costruiti sulle offerte del Portale Offerte ARERA.

GET/energy-index

In arrivoOpen · gratisjsonCache: 6 ore

Energy Index delle offerte

I quattro indici proprietari Energy Index (Fisse Luce, Variabili Luce, Fisse Gas, Variabili Gas) calcolati sulle offerte pubblicate sul Portale Offerte ARERA. Aggregati di mercato: nessun dato di singolo fornitore.

Parametri

Nome	In	Tipo	Descrizione
`commodity`	query	string	Filtra per commodity.`lucegas`

Richiesta

curl "https://energyindex.it/api/v1/energy-index?commodity=luce"

Risposta 200

application/json

{
  "updated_at": "2026-09-26",
  "indices": [
    {
      "slug": "mercato-libero-luce-fissa",
      "name": "Energy Index · Fisse Luce",
      "unit": "€/kWh",
      "mean": 0.1342,
      "median": 0.129,
      "min": 0.0989,
      "max": 0.1995,
      "offers": 212
    },
    {
      "slug": "mercato-libero-luce-variabile",
      "name": "Energy Index · Variabili Luce",
      "unit": "€/kWh",
      "mean": 0.1407,
      "median": 0.1376,
      "min": 0.1201,
      "max": 0.1788,
      "offers": 248,
      "spread_vs_reference": 0.0219
    }
  ],
  "source": "ARERA — Portale Offerte",
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)"
}

Campi della risposta

Campo	Tipo	Descrizione
`indices[].slug`	string	Identificativo stabile dell'indice.
`indices[].mean / median`	number	Media e mediana del prezzo materia prima delle offerte attive.
`indices[].min / max`	number	Estremi del range di mercato.
`indices[].offers`	integer	Numero di offerte considerate.
`indices[].spread_vs_reference`	number?	Solo variabili: spread medio sopra PUN o PSV.

GET/mercato-libero/stats

In arrivoAPI · 99 €jsoncsvCache: 6 ore

Statistiche mercato libero

Statistiche dettagliate sulle offerte attive del mercato libero: percentili di prezzo, quota fissa mensile, spread applicati sopra PUN/PSV e distribuzione per tipologia di cliente. Base per benchmark di listino e analisi competitive.

Parametri

Nome	In	Tipo	Descrizione
`commodity`obbl.	query	string	Commodity.`lucegas`
`price_type`	query	string	Tipologia di prezzo.`fissovariabile`
`customer`	query	string	Tipologia di cliente.`domesticobusiness`Default: `domestico`

Richiesta

curl "https://energyindex.it/api/v1/mercato-libero/stats?commodity=luce&price_type=variabile" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "commodity": "luce",
  "price_type": "variabile",
  "offers": 248,
  "spread_eur_kwh": {
    "p10": 0.008,
    "p25": 0.012,
    "median": 0.0165,
    "p75": 0.022,
    "p90": 0.031
  },
  "fixed_cost_eur_month": {
    "p10": 6.5,
    "median": 10.9,
    "p90": 16
  },
  "updated_at": "2026-09-26"
}

Campi della risposta

Campo	Tipo	Descrizione
`spread_eur_kwh`	object	Percentili dello spread sopra il PUN (€/kWh).
`fixed_cost_eur_month`	object	Percentili della quota fissa di commercializzazione (€/mese).

Endpoint

Forecast

Previsioni EIDX Research con bande di confidenza e track record verificabile.

GET/forecast/{asset}/next

In arrivoDeveloper · gratisjsonCache: 1 ora

Forecast del giorno dopo

Il valore previsto da EIDX Research per il prossimo giorno di mercato, con l'errore medio del modello negli ultimi 30 giorni per valutarne l'affidabilita'.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	path	string	Indice.`punpsvttf`

Richiesta

curl "https://energyindex.it/api/v1/forecast/pun/next" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "asset": "PUN",
  "target_date": "2026-09-28",
  "value": 114.6,
  "unit": "€/MWh",
  "model": "eidx-ensemble-v3",
  "mape_30d": 0.071,
  "generated_at": "2026-09-27T06:00:00Z",
  "methodology": "https://energyindex.it/it/forecast/metodologia"
}

Campi della risposta

Campo	Tipo	Descrizione
`target_date`	string	Giorno a cui si riferisce la previsione.
`value`	number	Valore previsto.
`mape_30d`	number	Errore percentuale medio assoluto degli ultimi 30 giorni (0,071 = 7,1%).

GET/forecast/{asset}

In arrivoAPI · 99 €jsoncsvCache: 1 ora

Forecast con bande di confidenza

La curva di previsione completa, un punto al giorno, con banda di confidenza P10–P90. Stesso modello del forecast pubblico, con storico delle previsioni passate verificabile via /forecast/track-record.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	path	string	Indice.`punpsvttf`
`horizon`	query	integer	Orizzonte in giorni.`73090180`Default: `30`

Richiesta

curl "https://energyindex.it/api/v1/forecast/pun?horizon=30" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "asset": "PUN",
  "unit": "€/MWh",
  "horizon_days": 30,
  "generated_at": "2026-09-27T06:00:00Z",
  "points": [
    {
      "date": "2026-09-28",
      "p10": 104.2,
      "p50": 114.6,
      "p90": 126.1
    },
    {
      "date": "2026-09-29",
      "p10": 105.8,
      "p50": 117.2,
      "p90": 130.4
    },
    {
      "date": "2026-10-27",
      "p10": 98.4,
      "p50": 121.9,
      "p90": 149.7
    }
  ],
  "summary": {
    "avg_p50": 119.3,
    "trend": "up"
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`points[].p50`	number	Valore centrale previsto (mediana).
`points[].p10 / p90`	number	Estremi della banda di confidenza all'80%.
`summary.trend`	string	up, down o flat rispetto all'ultimo valore osservato.

GET/forecast/{asset}/scenarios

In arrivoProjsoncsvCache: 6 ore

Forecast 12 mesi a scenari

Proiezione mensile a 12 mesi in tre scenari, con le ipotesi su gas, CO2 e domanda che li guidano. E' la base del modulo Forecast Scenari di EIDX Pro.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	path	string	Indice.`punpsv`
`months`	query	integer	Numero di mesi (1–12, 24 per Enterprise).Default: `12`

Richiesta

curl "https://energyindex.it/api/v1/forecast/pun/scenarios?months=12" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "asset": "PUN",
  "unit": "€/MWh",
  "months": [
    {
      "month": "2026-10",
      "base": 118.4,
      "bull": 134.9,
      "bear": 101.2
    },
    {
      "month": "2026-11",
      "base": 124.7,
      "bull": 146.3,
      "bear": 104.8
    }
  ],
  "assumptions": {
    "ttf_base": 35.5,
    "co2_base": 70.2
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`months[].base / bull / bear`	number	Prezzo medio mensile nei tre scenari.
`assumptions`	object	Ipotesi di input dello scenario base.

Endpoint

Tool di calcolo

I calcolatori di Energy Index ed EIDX Pro esposti come servizio.

GET/tools/bill-estimate

In arrivoOpen · gratisjsonCache: 6 ore

Stima spesa bolletta

Stima la spesa annua e mensile per la sola materia energia su un consumo dato, con PUN o PSV attuale piu' lo spread medio del mercato libero. Utile per blog, siti di consumatori e calcolatori embeddati. Non include oneri di sistema, trasporto e imposte, che vengono indicati a parte come ordine di grandezza.

Parametri

Nome	In	Tipo	Descrizione
`commodity`obbl.	query	string	Commodity.`lucegas`
`consumption`obbl.	query	number	Consumo annuo in kWh (luce) o Smc (gas).
`price_type`	query	string	Offerta a prezzo fisso (Energy Index mediano) o variabile (indice + spread).`fissovariabile`Default: `variabile`

Richiesta

curl "https://energyindex.it/api/v1/tools/bill-estimate?commodity=luce&consumption=2700"

Risposta 200

application/json

{
  "commodity": "luce",
  "consumption": 2700,
  "consumption_unit": "kWh/anno",
  "energy_price_eur_kwh": 0.13523,
  "energy_cost_year_eur": 365.12,
  "energy_cost_month_eur": 30.43,
  "basis": "PUN ultimo mese + spread mediano mercato libero",
  "compare_offers": "https://energiapro.biz",
  "attribution": "Energy Index — https://energyindex.it (gratis, attribuzione richiesta)"
}

Campi della risposta

Campo	Tipo	Descrizione
`energy_price_eur_kwh`	number	Prezzo della materia prima usato per la stima.
`energy_cost_year_eur / month_eur`	number	Spesa materia prima annua e mensile.
`basis`	string	Base di calcolo, da mostrare all'utente.

POST/tools/margin-simulator

In arrivoProjsonCache: Nessuna (calcolo on demand)

Margin Simulator

Simula il margine di un'offerta (spread e quota fissa) su un portafoglio di clienti, con i prezzi forward e gli scenari di stress di EIDX Pro. Stessa logica del modulo Margin Simulator.

Parametri

Nome	In	Tipo	Descrizione
`commodity`obbl.	body	string	luce o gas.`lucegas`
`spread_eur_kwh`obbl.	body	number	Spread applicato sopra l'indice.
`fixed_fee_eur_month`obbl.	body	number	Quota fissa mensile.
`portfolio`obbl.	body	object	Clienti e consumo annuo medio.
`months`	body	integer	Orizzonte in mesi.Default: `12`

Richiesta

curl -X POST "https://energyindex.it/api/v1/tools/margin-simulator" \
  -H "Authorization: Bearer $EIDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commodity":"luce","spread_eur_kwh":0.015,"fixed_fee_eur_month":9.9,"portfolio":{"customers":1200,"avg_consumption_kwh":2700},"months":12}'

Risposta 200

application/json

{
  "gross_margin_eur": {
    "base": 162840,
    "stress_up": 128400,
    "stress_down": 171200
  },
  "margin_per_customer_eur_year": 135.7,
  "breakeven_spread_eur_kwh": 0.0068
}

Campi della risposta

Campo	Tipo	Descrizione
`gross_margin_eur`	object	Margine lordo totale nello scenario base e nei due stress.
`breakeven_spread_eur_kwh`	number	Spread minimo per coprire i costi.

Endpoint

Trading e risk

Indicatori quantitativi per desk di trading e risk management.

GET/trading/vitals

In arrivoTradingjsoncsvCache: 15 minuti

Trading Vitals

Gli indicatori del Trading Desk EIDX Pro: spark spread e clean spark spread (PUN vs gas + CO2), volatilita' ATR a 14 giorni, spread PSV–TTF.

Parametri

Nome	In	Tipo	Descrizione
`date`	query	string	Giorno (YYYY-MM-DD). Default: ultimo.

Richiesta

curl "https://energyindex.it/api/v1/trading/vitals" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "date": "2026-09-26",
  "spark_spread": 47.2,
  "clean_spark_spread": 22.1,
  "psv_ttf_spread": 3.91,
  "atr_14d": {
    "pun": 9.84,
    "psv": 1.72
  },
  "unit": "€/MWh"
}

Campi della risposta

Campo	Tipo	Descrizione
`clean_spark_spread`	number	Margine teorico di un CCGT al netto di gas e CO2.
`atr_14d`	object	Average True Range a 14 giorni per indice.

GET/trading/correlation

In arrivoTradingjsonCache: 1 ora

Matrice di correlazione

Matrice di correlazione di Pearson sui rendimenti giornalieri, su finestra mobile configurabile.

Parametri

Nome	In	Tipo	Descrizione
`window`	query	integer	Finestra in giorni.`3090180`Default: `30`

Richiesta

curl "https://energyindex.it/api/v1/trading/correlation?window=30" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "window_days": 30,
  "assets": [
    "PUN",
    "PSV",
    "TTF"
  ],
  "matrix": [
    [
      1,
      0.82,
      0.79
    ],
    [
      0.82,
      1,
      0.94
    ],
    [
      0.79,
      0.94,
      1
    ]
  ]
}

Campi della risposta

Campo	Tipo	Descrizione
`assets`	string[]	Ordine di righe e colonne.
`matrix`	number[][]	Coefficienti di correlazione da −1 a 1.

POST/trading/backtest

In arrivoTradingjsonCache: Nessuna (calcolo on demand)

Backtest di strategie

Backtest di strategie predefinite (media mobile, soglia, copertura a finestra) su PUN, PSV o TTF, con P&L, drawdown e confronto con buy & hold.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	body	string	Indice.`punpsvttf`
`strategy`obbl.	body	string	Strategia.`sma_crossthresholdrolling_hedge`
`from`obbl.	body	string	Data iniziale del backtest (YYYY-MM-DD).
`to`obbl.	body	string	Data finale del backtest (YYYY-MM-DD).
`params`	body	object	Parametri della strategia.

Richiesta

curl -X POST "https://energyindex.it/api/v1/trading/backtest" \
  -H "Authorization: Bearer $EIDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset":"pun","strategy":"sma_cross","from":"2024-01-01","to":"2026-09-26","params":{"fast":10,"slow":30}}'

Risposta 200

application/json

{
  "total_return_pct": 18.4,
  "max_drawdown_pct": -7.9,
  "sharpe": 1.21,
  "trades": 37,
  "benchmark_return_pct": 4.2
}

Campi della risposta

Campo	Tipo	Descrizione
`sharpe`	number	Sharpe ratio annualizzato.
`benchmark_return_pct`	number	Rendimento buy & hold sullo stesso periodo.

Endpoint

Alert ed export

Webhook su soglie di prezzo ed export massivi.

POST/alerts

In arrivoAPI · 99 €jsonCache: Nessuna

Crea un alert webhook

Registra un alert: quando l'indice pubblicato attraversa la soglia, Energy Index invia una POST firmata al tuo URL (Slack, Teams, Telegram, Zapier, Make, n8n o il tuo backend). Ogni alert scatta al massimo una volta per giorno di mercato.

Parametri

Nome	In	Tipo	Descrizione
`asset`obbl.	body	string	Indice monitorato.`punpsvttfpun-zona-nordpun-zona-sud`
`condition`obbl.	body	string	Condizione.`abovebelowchange_pct`
`threshold`obbl.	body	number	Soglia in €/MWh, o variazione % per change_pct.
`webhook_url`obbl.	body	string	URL HTTPS che ricevera' la notifica.

Richiesta

curl -X POST "https://energyindex.it/api/v1/alerts" \
  -H "Authorization: Bearer $EIDX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset":"psv","condition":"above","threshold":45,"webhook_url":"https://hooks.slack.com/services/T000/B000/XXXX"}'

Risposta 200

application/json

{
  "id": "alr_8Kq2mZ",
  "asset": "psv",
  "condition": "above",
  "threshold": 45,
  "status": "active",
  "signing_secret": "whsec_•••• (mostrato una sola volta)",
  "created_at": "2026-09-27T08:12:44Z"
}

Campi della risposta

Campo	Tipo	Descrizione
`id`	string	Identificativo dell'alert, usato per DELETE /alerts/{id}.
`signing_secret`	string	Segreto per verificare l'header X-EIDX-Signature (HMAC-SHA256).

GET/bulk/{dataset}

In arrivoEnterprisejsonCache: Rigenerato ogni notte

Export bulk

Scarica l'intero storico di un dataset in un solo file, rigenerato ogni notte. Per data warehouse, modelli interni e analisi offline.

Parametri

Nome	In	Tipo	Descrizione
`dataset`obbl.	path	string	Dataset.`pun-hourlyprices-dailyforecast-historymercato-libero`
`format`	query	string	Formato.`csv.gzparquet`Default: `parquet`

Richiesta

curl "https://energyindex.it/api/v1/bulk/pun-hourly?format=parquet" \
  -H "Authorization: Bearer $EIDX_API_KEY"

Risposta 200

application/json

{
  "dataset": "pun-hourly",
  "format": "parquet",
  "rows": 1843200,
  "generated_at": "2026-09-27T02:00:00Z",
  "download_url": "https://energyindex.it/api/v1/bulk/files/pun-hourly-20260927.parquet?sig=…",
  "expires_at": "2026-09-27T03:00:00Z"
}

Campi della risposta

Campo	Tipo	Descrizione
`download_url`	string	URL firmato, valido un'ora.
`rows`	integer	Righe del dataset.

Manca qualcosa? Scrivi a pro@energyindex.pro oppure richiedi una chiave.