Documentație API
Integrează predicțiile calității apusului în aplicațiile tale
Obțineți o cheie API pentru a urmări utilizareaStart rapid
Obține o predicție de apus în câteva secunde
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Înlocuiește $SUNSET_API_KEY cu o cheie din panoul tău. Apelurile neautentificate funcționează pentru demo-uri rapide, dar sunt mai restrictive și nu trimit anteturi rate-limit.
Exemplu de răspuns
{
"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
}
}Autentificare
Cererile externe se autentifică prin header-ul x-api-key. Generează o cheie din panoul tău de control — cheia brută este afișată o singură dată.
Header
x-api-key: sp_live_YOUR_API_KEY_HERETrimite cheia API în header-ul de cerere x-api-key la fiecare apel.
Scope-uri
| Scope | Descriere |
|---|---|
| predict:read | Citește predicțiile de apus (necesar pentru /api/predict) |
| usage:read | Citește statisticile de utilizare ale propriei chei (necesar pentru /api/usage) |
Limite
Plan gratuit — 100 de cereri pe zi per cheie, resetare la miezul nopții UTC.
Header-e de răspuns pentru limita de rată
Fiecare răspuns autentificat reușit conține aceste header-e, ca să poți urmări cota în timp real:
| X-RateLimit-Limit | Numărul maxim de cereri permise în fereastra curentă |
| X-RateLimit-Remaining | Cereri rămase astăzi |
| X-RateLimit-Reset | Marcaj temporal ISO 8601 pentru momentul resetării cotei |
| Retry-After | Secundele de așteptat înainte de a reîncerca (doar la 429) |
Exemplu de cerere autentificată
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Referință endpoint-uri
Sandbox API
Testează API-ul direct din browser
Începe cu sp_live_ și are 40 de caractere
Stocată doar în această filă de browser (sessionStorage). Ștearsă când închizi fila.
De azi până la 5 zile înainte. Lasă gol pentru azi.
URL cerere
Exemple de cod
Exemple gata de utilizare în limbaje populare
# 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"Exemplele se actualizează în timp real cu parametrii playground.
Răspunsuri de eroare
Erori comune și semnificația lor
Cerere invalidă
Parametri lipsă sau invalizi. Furnizează fie oraș, fie lat/lon.
{
"error": "Either lat/lon or city must be provided"
}Neautorizat
Cheie API lipsă, malformată sau revocată. Trimite o cheie validă în header-ul x-api-key.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Interzis
Cheia este validă, dar nu are scope-ul predict:read necesar pentru acest endpoint.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Nu a fost găsit
Orașul specificat nu a putut fi găsit.
{
"error": "City not found",
"code": "cityNotFound"
}Prea multe cereri
Cota zilnică depășită (100 de cereri/zi pe planul gratuit). Resetare la miezul nopții UTC; verifică header-ul Retry-After.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Eroare de server
A apărut o eroare internă a serverului. Vă rugăm să încercați din nou mai târziu.
{
"error": "Internal server error"
}Bad Gateway
Furnizorul de geocodare din amonte a eșuat. Reîncearcă cu o ușoară întârziere; ia în calcul trimiterea de lat/lon pentru a sări peste geocodare.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Bune practici
Memorează răspunsurile în cache
Predicțiile sunt memorate în cache timp de 30 de minute. Evită interogările mai frecvente.
Interval de date
Predicțiile sunt disponibile pentru azi până la 5 zile în avans. Datele mai îndepărtate sunt mai puțin precise.
Preferă coordonatele
Utilizarea lat/lon este mai precisă și evită ambiguitatea numelor de orașe partajate.
Gestionează erorile cu grație
Verifică întotdeauna codul HTTP și gestionează răspunsurile 400/404/500 corespunzător.
Respectă limitele de rată
Citește X-RateLimit-Remaining la fiecare răspuns. La 429, așteaptă fereastra Retry-After (resetare la miezul nopții UTC) înainte de a reîncerca.
Păstrează cheile pe server
Nu integra niciodată o cheie API într-un bundle public de client, o aplicație mobilă sau un repo. Direcționeaz-o prin backend-ul tău și stochează cheile în variabile de mediu sau într-un manager de secrete.
Utilizare și licențiere
Când e suficient planul gratuit — și când ai nevoie de un plan plătit.
Plan gratuit
Gratuit pentru uz personal, hobby, casă inteligentă și testare.
- •Proiecte personale și prototipuri
- •Hobby și învățare
- •Panouri smart home (de ex. Home Assistant) pentru uz personal
- •Testare și evaluare
100 de cereri/zi per cheie API.
Planul Plus
Limite personale mai mari și site fără reclame. Doar uz personal — proiectele comerciale necesită Pro.
200 cereri/zi pe cheie API, 2 chei API.
Uz comercial
Utilizarea comercială necesită un plan plătit — Pro sau Business.
Planurile plătite au limite zilnice mai mari și permit mai multe chei API.
Vezi prețurileHome Assistant și alte integrări de casă inteligentă rămân permise pe planul gratuit pentru uz personal, necomercial.
Păstrează cheia API secretă. Folosește-o pe server și nu o include niciodată în cod client public și nu o publica într-un repository.
Construiești ceva comercial sau ai atins o limită pe care n-o poți rezolva? Contactează suportul