📡 Documentazione API

API REST gratuita per sviluppatori. Ottieni dati in tempo reale sulle fasce orarie e i prezzi dell'energia elettrica in Italia.

https://api.fasciaelettrica.it/v1

Panoramica

L'API FasciaElettrica fornisce accesso programmatico ai dati sulle fasce orarie elettriche italiane (F1, F2, F3) e ai prezzi PUN (Prezzo Unico Nazionale).

Caratteristiche

✅ Gratuita — Nessuna chiave API richiesta per uso base
✅ JSON — Risposte in formato JSON standard
✅ Cache-friendly — Header appropriati per caching efficiente
✅ CORS abilitato — Utilizzabile da browser e app frontend
✅ Timezone-aware — Gestione corretta dell'ora legale italiana

Endpoint Fasce Orarie

GET /v1/fascia/now

Restituisce la fascia oraria corrente.

Risposta

{
  "fascia": "F1",
  "started_at": "2024-01-15T07:00:00.000Z",
  "ends_at": "2024-01-15T19:00:00.000Z",
  "next_fascia": "F2",
  "next_change_at": "2024-01-15T19:00:00.000Z",
  "is_holiday": false,
  "calendar_version": "2024-01"
}

GET /v1/fascia?datetime=ISO8601

Restituisce la fascia per un momento specifico.

Parametri

Nome	Tipo	Descrizione
`datetime`	string	Data/ora in formato ISO 8601

Esempio

GET /v1/fascia?datetime=2024-01-15T10:30:00

GET /v1/fascia/calendar?date=YYYY-MM-DD

Restituisce tutte le fasce di un giorno specifico.

Risposta

{
  "date": "2024-01-15",
  "is_holiday": false,
  "intervals": [
    { "fascia": "F3", "start": "...", "end": "..." },
    { "fascia": "F2", "start": "...", "end": "..." },
    { "fascia": "F1", "start": "...", "end": "..." },
    { "fascia": "F2", "start": "...", "end": "..." },
    { "fascia": "F3", "start": "...", "end": "..." }
  ],
  "total_hours": 24
}

Endpoint PUN

Il PUN (Prezzo Unico Nazionale) rappresenta il prezzo all'ingrosso dell'energia elettrica in Italia, espresso in €/MWh. Scopri di più sul PUN →

GET /v1/pun/hourly?date=YYYY-MM-DD

Restituisce i valori orari del PUN per una data specifica.

Risposta

{
  "date": "2024-01-15",
  "currency": "EUR",
  "unit": "MWh",
  "hours": [
    { "hour": 0, "price": 85.50, "fascia": "F3" },
    { "hour": 1, "price": 82.30, "fascia": "F3" },
    ...
  ],
  "source": "GME",
  "fetched_at": "2024-01-15T12:00:00Z"
}

GET /v1/pun/hour?date=YYYY-MM-DD&hour=HH

Restituisce il PUN per un'ora specifica.

Parametri

Nome	Tipo	Descrizione
`date`	string	Data in formato YYYY-MM-DD
`hour`	number	Ora (0-23)

GET /v1/pun/by-band?date=YYYY-MM-DD

Restituisce il PUN aggregato per fascia (media, min, max).

Risposta

{
  "date": "2024-01-15",
  "currency": "EUR",
  "unit": "MWh",
  "bands": {
    "F1": { "average": 125.50, "min": 110.20, "max": 135.80, "hours_count": 11 },
    "F2": { "average": 105.30, "min": 95.00, "max": 115.60, "hours_count": 5 },
    "F3": { "average": 85.20, "min": 75.00, "max": 95.40, "hours_count": 8 }
  },
  "daily_average": 105.33
}

Stato del Servizio

GET /v1/status

Verifica lo stato del servizio e la freschezza dei dati PUN.

Risposta

{
  "api_version": "1.0.0",
  "status": "healthy",
  "pun_data": {
    "latest_date": "2024-01-15",
    "freshness": "fresh",
    "last_ingest_at": "2024-01-15T12:30:00Z",
    "last_ingest_status": "success"
  },
  "timestamp": "2024-01-15T14:00:00Z"
}

Valori di Freshness

fresh — Dati aggiornati nelle ultime 24 ore
stale — Dati più vecchi di 24 ore

Gestione Errori

Tutti gli errori seguono un formato standard:

{
  "error": "ERROR_CODE",
  "message": "Descrizione leggibile dell'errore"
}

Codici Errore

HTTP	Codice	Descrizione
400	BAD_REQUEST	Parametri mancanti o non validi
404	NOT_FOUND	Risorsa non trovata
429	RATE_LIMITED	Troppe richieste
500	INTERNAL_ERROR	Errore interno del server

Rate Limiting

Per garantire la disponibilità del servizio, le richieste sono limitate a 100 richieste al minuto per IP.

Header di Risposta

Header	Descrizione
`X-RateLimit-Limit`	Limite massimo di richieste
`X-RateLimit-Remaining`	Richieste rimanenti nel periodo
`X-RateLimit-Reset`	Timestamp di reset del limite

💡 Suggerimento: Usa gli header Cache-Control nelle risposte per implementare caching lato client e ridurre le richieste.

Pronto per Iniziare?

Prova subito l'API nel tuo terminale:

curl https://api.fasciaelettrica.it/v1/fascia/now | jq

← Torna alla homepage | Guide per consumatori