Documentazione API
Integra le previsioni di qualità del tramonto nelle tue applicazioni
Ottieni una chiave API per tracciare il tuo utilizzoAvvio Rapido
Ottieni una previsione del tramonto in pochi secondi
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Sostituisci $SUNSET_API_KEY con una chiave dalla tua dashboard. Le chiamate non autenticate funzionano per demo rapide ma sono più rigide e non includono gli header di rate-limit.
Risposta di Esempio
{
"score": 78,
"label": "High",
"explanation": "Scattered clouds and clean air should produce vivid colors near the horizon.",
"confidence": "high",
"location": "Paris, FR",
"predictionType": "sunset",
"sunsetTime": "2026-05-26T19:42:00Z",
"sunriseTime": "2026-05-26T04:51:00Z",
"timezone": "Europe/Paris",
"targetDate": "2026-05-26",
"rawFactors": {
"cloudCover": 15,
"humidity": 55,
"visibility": 18200,
"windSpeed": 5.2,
"windDegree": 180,
"rainProb": 0,
"condition": "clouds",
"temperature": 19.4,
"dewPoint": 10.2,
"pressure": 1015,
"aqi": 2
}
}Autenticazione
Le richieste esterne si autenticano tramite l'header x-api-key. Genera una chiave dalla tua dashboard — la chiave non cifrata viene mostrata una sola volta.
Header
x-api-key: sp_live_YOUR_API_KEY_HEREInvia la tua chiave API nell'header di richiesta x-api-key a ogni chiamata.
Scope
| Scope | Descrizione |
|---|---|
| predict:read | Lettura delle previsioni di tramonto (richiesto per /api/predict) |
| usage:read | Lettura delle statistiche di utilizzo della chiave stessa (richiesto per /api/usage) |
Limiti
Piano gratuito — 100 richieste al giorno per chiave, azzerate alla mezzanotte UTC.
Header di risposta del rate limit
Ogni risposta autenticata andata a buon fine include questi header, così puoi monitorare la quota in tempo reale:
| X-RateLimit-Limit | Numero massimo di richieste consentite nella finestra corrente |
| X-RateLimit-Remaining | Richieste rimanenti oggi |
| X-RateLimit-Reset | Timestamp ISO 8601 in cui la quota si azzera |
| Retry-After | Secondi di attesa prima di riprovare (solo in caso di 429) |
Esempio di richiesta autenticata
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Riferimento Endpoint
API Playground
Testa l'API direttamente dal tuo browser
Inizia con sp_live_ ed è lunga 40 caratteri
Memorizzata solo in questa scheda del browser (sessionStorage). Cancellata alla chiusura della scheda.
Da oggi fino a 5 giorni. Lascia vuoto per oggi.
URL Richiesta
Esempi di Codice
Esempi pronti all'uso nei linguaggi più popolari
# Set your API key once (mint from /dashboard/api-keys)
export SUNSET_API_KEY="sp_live_YOUR_API_KEY_HERE"
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Gli esempi si aggiornano in tempo reale in base ai parametri del playground.
Risposte di Errore
Risposte di errore comuni e loro significato
Richiesta Errata
Parametri mancanti o non validi. Fornisci una città o lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Non autorizzato
Chiave API mancante, malformata o revocata. Invia una chiave valida nell'header x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Vietato
La chiave è valida ma manca dello scope predict:read richiesto per questo endpoint.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Non Trovato
La città specificata non è stata trovata.
{
"error": "City not found",
"code": "cityNotFound"
}Troppe richieste
Quota giornaliera superata (100 richieste/giorno sul piano gratuito). Azzeramento alla mezzanotte UTC; controlla l'header Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Errore Server
Si è verificato un errore interno del server. Riprova più tardi.
{
"error": "Internal server error"
}Bad Gateway
Il provider di geocoding upstream ha avuto un errore. Riprova con un leggero ritardo; valuta l'invio di lat/lon per saltare il geocoding.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Best Practice
Memorizza le risposte nella cache
Le previsioni vengono memorizzate nella cache per 30 minuti. Evita di interrogare più frequentemente.
Intervallo di date
Le previsioni sono disponibili da oggi fino a 5 giorni in avanti. Date più lontane restituiscono risultati meno accurati.
Preferisci le coordinate
Usare lat/lon è più preciso ed evita ambiguità con nomi di città condivisi tra regioni.
Gestisci gli errori in modo elegante
Controlla sempre il codice di stato HTTP e gestisci appropriatamente le risposte 400/404/500.
Rispetta i rate limit
Leggi X-RateLimit-Remaining a ogni risposta. In caso di 429, attendi la finestra Retry-After (azzeramento alla mezzanotte UTC) prima di riprovare.
Mantieni le chiavi lato server
Non incorporare mai una chiave API in un bundle client pubblico, in un'app mobile o in un repository. Instradala tramite il tuo backend e conserva le chiavi in variabili d'ambiente o in un gestore di segreti.
Uso e licenza
Quando basta il piano gratuito — e quando serve un piano a pagamento.
Piano gratuito
Gratis per uso personale, hobby, smart home e test.
- •Progetti personali e prototipi
- •Hobby e apprendimento
- •Dashboard per la casa intelligente (es. Home Assistant) per uso personale
- •Test e valutazione
100 richieste/giorno per chiave API.
Piano Plus
Limiti personali più alti e sito senza pubblicità. Solo uso personale: i progetti commerciali richiedono Pro.
200 richieste/giorno per chiave API, 2 chiavi API.
Uso commerciale
L’uso commerciale richiede un piano a pagamento — Pro o Business.
I piani a pagamento hanno limiti giornalieri più alti e consentono più chiavi API.
Vedi i prezziHome Assistant e altre integrazioni smart home restano consentite nel piano gratuito per uso personale, non commerciale.
Mantieni segreta la tua chiave API. Usala lato server e non incorporarla mai nel codice client pubblico né in un repository.
Stai costruendo qualcosa di commerciale o hai raggiunto un limite che non riesci a risolvere? Contatta il supporto