Dokumentacja API

Zintegruj prognozy jakości zachodu słońca ze swoimi aplikacjami

Zdobądź klucz API, aby śledzić swoje użycie

Bazowy URLhttps://sunset-predictor.com

Szybki start

Otrzymaj prognozę zachodu słońca w kilka sekund

curl -H "x-api-key: $SUNSET_API_KEY" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

Zastąp $SUNSET_API_KEY kluczem ze swojego panelu. Wywołania bez uwierzytelniania działają w szybkich demonstracjach, ale mają surowsze limity i nie zwracają nagłówków limitów.

Przykładowa odpowiedź

{
  "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
  }
}

Uwierzytelnianie

Żądania zewnętrzne uwierzytelniają się nagłówkiem x-api-key. Wygeneruj klucz w swoim panelu — surowy klucz jest wyświetlany tylko raz.

Nagłówek

x-api-key: sp_live_YOUR_API_KEY_HERE

Przy każdym wywołaniu wysyłaj klucz API w nagłówku żądania x-api-key.

Zakresy

Zakres	Opis
predict:read	Odczyt prognoz zachodu słońca (wymagany dla /api/predict)
usage:read	Odczyt statystyk użycia tego klucza (wymagany dla /api/usage)

Limity

Plan Free — 100 żądań dziennie na klucz, reset o północy UTC.

Nagłówki odpowiedzi z limitami

Każda udana uwierzytelniona odpowiedź zawiera te nagłówki, dzięki czemu możesz śledzić limit w czasie rzeczywistym:

X-RateLimit-Limit	Maksymalna liczba żądań dozwolona w bieżącym oknie
X-RateLimit-Remaining	Żądania pozostałe dzisiaj
X-RateLimit-Reset	Znacznik czasu ISO 8601 resetu limitu
Retry-After	Liczba sekund do ponowienia próby (tylko przy 429)

Przykładowe uwierzytelnione żądanie

curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

Dokumentacja endpointów

Plac zabaw API

Przetestuj API bezpośrednio w przeglądarce. Wklej klucz API, aby wykonać uwierzytelnione wywołanie (liczy się do dziennego limitu), albo zostaw puste pole, aby wykonać demonstracyjne wywołanie bez uwierzytelniania.

Endpoint

Klucz API (opcjonalnie)Zdobądź klucz →

Zaczyna się od sp_live_ i ma 40 znaków

Przechowywany tylko w tej karcie przeglądarki (sessionStorage). Usuwany po zamknięciu karty.

Miasto

Szerokość geograficzna

Długość geograficzna

Data

Od dzisiaj do 5 dni naprzód. Zostaw puste, aby użyć dzisiejszej daty.

Język

Jednostki

URL żądania

GET /api/v1/predict?city=Paris

Przykłady kodu

Gotowe do użycia przykłady w popularnych językach

# 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"

Fragmenty kodu aktualizują się na żywo po zmianie parametrów placu zabaw powyżej.

Odpowiedzi z błędem

Typowe odpowiedzi z błędem i ich znaczenie

400Błąd klienta

Nieprawidłowe żądanie

Brakujące lub nieprawidłowe parametry. Podaj city albo lat/lon.

{
  "error": "Either lat/lon or city must be provided"
}

401Uwierzytelnianie / uprawnienia

Brak autoryzacji

Brakujący, nieprawidłowo zbudowany lub unieważniony klucz API. Wyślij prawidłowy klucz w nagłówku x-api-key.

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}

403Uwierzytelnianie / uprawnienia

Brak dostępu

Klucz jest prawidłowy, ale nie ma zakresu predict:read wymaganego przez ten endpoint.

{
  "error": "Insufficient permissions. Required scope: predict:read",
  "code": "insufficientScope"
}

404Błąd klienta

Nie znaleziono

Nie znaleziono podanego miasta.

{
  "error": "City not found",
  "code": "cityNotFound"
}

429Błąd klienta

Zbyt wiele żądań

Przekroczono dzienny limit (100 żądań dziennie w planie Free). Reset o północy UTC; sprawdź nagłówek Retry-After.

{
  "error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
  "code": "rateLimitExceeded",
  "retryAfter": 3600
}

500Błąd serwera

Błąd serwera

Wystąpił wewnętrzny błąd serwera. Spróbuj ponownie później.

{
  "error": "Internal server error"
}

502Błąd serwera

Błąd bramy

Zewnętrzny dostawca geokodowania zawiódł. Ponów próbę z niewielkim opóźnieniem; rozważ wysyłanie lat/lon, aby pominąć geokodowanie.

{
  "error": "Unable to look up city location",
  "code": "geocodingFailed"
}

Dobre praktyki

Buforuj odpowiedzi

Prognozy są buforowane po stronie serwera przez 20 minut dla każdej kombinacji (lat, lon, lang, date). Unikaj częstszego odpytywania.

Zakres dat

Prognozy są dostępne od wczoraj do 5 dni naprzód. Dalsze daty zwracają mniej dokładne wyniki.

Preferuj współrzędne

Użycie lat/lon jest dokładniejsze, eliminuje niejednoznaczność nazw miast powtarzających się w różnych regionach i pomija geokodowanie.

Obsługuj błędy poprawnie

Sprawdzaj kod statusu HTTP oraz pole code w odpowiedzi. Pokazuj użytkownikowi błędy 401/403, a przy 429 zwolnij, stosując Retry-After.

Przestrzegaj limitów

Sprawdzaj X-RateLimit-Remaining w każdej odpowiedzi. Przy 429 poczekaj do końca okna Retry-After (reset o północy UTC) przed ponowną próbą.

Trzymaj klucze po stronie serwera

Nigdy nie umieszczaj klucza API w publicznym pakiecie klienta, aplikacji mobilnej ani repozytorium. Kieruj ruch przez swój backend, a klucze przechowuj w zmiennych środowiskowych lub menedżerze sekretów.

Użycie i licencjonowanie

Kiedy wystarczy plan Free — a kiedy potrzebny jest plan płatny.

Plan Free

Bezpłatny do użytku osobistego, hobbystycznego, w inteligentnym domu i do testów.

•Projekty osobiste i prototypy
•Hobby i nauka
•Panele inteligentnego domu (np. Home Assistant) do użytku osobistego
•Testowanie i ocena

100 żądań dziennie na klucz API.

Plan Plus

Wyższe limity osobiste dla wspierających oraz strona bez reklam. Tylko do użytku osobistego — projekty komercyjne wymagają planu Pro.

200 żądań dziennie na klucz API, liczba kluczy API: 2.

Użycie komercyjne

Użycie komercyjne wymaga planu płatnego — Pro lub Business.

Plany płatne mają wyższe dzienne limity żądań i pozwalają na więcej kluczy API.

Zobacz cennik

Home Assistant i inne integracje inteligentnego domu pozostają dozwolone w planie Free do użytku osobistego i niekomercyjnego.

Zachowaj klucz API w tajemnicy. Używaj go po stronie serwera i nigdy nie umieszczaj w publicznym kodzie po stronie klienta ani w repozytorium.

Tworzysz coś komercyjnego albo trafiasz na limit, którego nie możesz obejść? Skontaktuj się z pomocą