API godzin zachodu i wschodu słońca

Nasze darmowe API podaje godziny wschodu i zachodu słońca w dowolnym miejscu na Ziemi oraz dane o świcie, zmierzchu, złotej godzinie, położeniu Słońca i Księżycu. Wystarczą szerokość i długość geograficzna: wyślij proste żądanie GET, a otrzymasz odpowiedź w formacie JSON.

Godziny podawane są w lokalnej strefie czasowej danego miejsca. Jedno żądanie może obejmować jeden dzień lub nawet cały rok.

API jest bezpłatne: nie wymaga rejestracji ani klucza API. Wymagamy jednak podania źródła: umieść widoczny link do sunrise-sunset.org w aplikacji lub na stronie, na której prezentujesz dane.

Dokumentacja wersji 1 API (/json) znajduje się teraz w dokumentacji v1. Samo API pozostaje bez zmian i będzie obsługiwane bezterminowo.

Dokumentacja API

Wyślij żądanie GET na adres https://api.sunrise-sunset.org/v2. Wypróbuj od razu – ten link działa w przeglądarce:

https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400

Obsługiwany jest też zwykły HTTP, przydatny w urządzeniach IoT i systemach wbudowanych (Arduino, ESP8266, mikrokontrolery), które nie mogą nawiązywać połączeń TLS.

Więcej przykładów: konkretna data i cały rok w jednym żądaniu:

https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400&date=2026-10-23
https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400&date_start=2026-01-01&date_end=2026-12-31

Parametry żądania

Odpowiedź

Wszystkie godziny mają format ISO 8601: 2026-01-15T08:27:43+01:00 oznacza 15 stycznia o 08:27:43 rano czasu lokalnego (1 godzinę przed UTC). Każdy język programowania obsługuje go bez dodatkowych bibliotek; w JavaScript wystarczy new Date(data.sunrise). Przykładowa odpowiedź:


    {
      "date": "2026-01-15",
      "tzid": "Europe/Madrid",
      "utc_offset": "+01:00",
      "lat": 36.7202,
      "lng": -4.4203,
      "sunrise": "2026-01-15T08:29:18+01:00",
      "sunset": "2026-01-15T18:25:09+01:00",
      "solar_noon": "2026-01-15T13:26:44+01:00",
      "day_length": 35751,
      "sun_status": "normal",
      "civil_twilight_begin": "2026-01-15T08:01:05+01:00",
      "civil_twilight_end": "2026-01-15T18:53:22+01:00",
      "nautical_twilight_begin": "2026-01-15T07:29:17+01:00",
      "nautical_twilight_end": "2026-01-15T19:25:11+01:00",
      "astronomical_twilight_begin": "2026-01-15T06:58:14+01:00",
      "astronomical_twilight_end": "2026-01-15T19:56:15+01:00",
      "dawn": "2026-01-15T08:01:05+01:00",
      "dusk": "2026-01-15T18:53:22+01:00",
      "first_light": "2026-01-15T06:58:14+01:00",
      "last_light": "2026-01-15T19:56:15+01:00",
      "golden_hour": {
        "morning": {
          "begin": "2026-01-15T08:11:54+01:00",
          "end": "2026-01-15T09:08:17+01:00"
        },
        "evening": {
          "begin": "2026-01-15T17:46:10+01:00",
          "end": "2026-01-15T18:42:33+01:00"
        }
      },
      "blue_hour": {
        "morning": {
          "begin": "2026-01-15T08:01:05+01:00",
          "end": "2026-01-15T08:11:54+01:00"
        },
        "evening": {
          "begin": "2026-01-15T18:42:33+01:00",
          "end": "2026-01-15T18:53:22+01:00"
        }
      },
      "solar_position": {
        "sunrise_azimuth": 116,
        "sunset_azimuth": 244.1,
        "solar_noon_azimuth": 179.9,
        "solar_noon_altitude": 32.22
      },
      "moonrise": "2026-01-15T06:01:54+01:00",
      "moonset": "2026-01-15T15:14:23+01:00",
      "moon_phase": "Waning Crescent",
      "moon_illumination": 10.62
    }

Przy date_start/date_end odpowiedź ma postać {"tzid", "lat", "lng", "days": […]}, a każdy element days zawiera powyższe pola (oprócz tzid/lat/lng).

Zakres może zwrócić mniej dni, niż zamówiono. W niektórych miejscach pewne dni kalendarzowe nigdy nie nastąpiły: Samoa całkowicie pominęło 30 grudnia 2011 przy przekraczaniu linii zmiany daty. Takie dni są pomijane w days, więc dopasowuj wpisy według pola date, zamiast zakładać jeden wpis na każdy zamówiony dzień.

Definicje pól

Znaczenie poszczególnych pól prostym językiem, z dokładną definicją w nawiasach (to samo żądanie zawsze zwraca dokładnie te same godziny):

Więcej o każdym zjawisku znajdziesz w naszym słowniku pojęć astronomicznych.

Dni polarne i wartości null

sun_status ma wartość normal, midnight_sun (Słońce nie zachodzi: day_length wynosi 86400) lub polar_night (Słońce nie wschodzi: day_length wynosi 0). Zdarzenia, które nie występują, mają wartość null. Każde zdarzenie może niezależnie mieć wartość null: w pobliżu kół podbiegunowych zdarzają się dni przejściowe, kiedy Słońce wschodzi, lecz nie zachodzi w tym samym dniu kalendarzowym; wtedy sunrise ma wartość, sunset to null, sun_status to normal, a day_length to null. Nigdy nie wnioskuj o jednym zdarzeniu na podstawie innego.

Dokładność obliczeń

Każde zjawisko słoneczne to chwila, gdy środek Słońca przekracza określoną wysokość nad horyzontem — −0.833° dla wschodu i zachodu słońca oraz −6°, −12° i −18° dla trzech rodzajów świtu i zmierzchu — zawsze w obrębie wskazanego lokalnego dnia kalendarzowego.

Te godziny różnią się od godzin w wersja 1 API. Starsza wersja zachowuje pierwotne obliczenia, aby istniejący kod nadal działał. Jej godziny mogą różnić się od tych o kilka sekund przy równiku i nawet o minutę lub więcej na wysokich szerokościach geograficznych.

Sprawdziliśmy tę wersję względem niezależnego wzorca astronomicznego, efemeryd planetarnych JPL, dla miast od równika po Arktykę przez cały rok: wschód i zachód słońca oraz trzy rodzaje świtu i zmierzchu różnią się od niego o kilka sekund, a w dniach blisko kół podbiegunowych, gdy Słońce ledwie przekracza próg – o około pół minuty. Godziny w naszym serwisie obliczamy tą samą metodą.

Błędy

Jeśli żądanie zawiera błąd, API wyjaśni prostym językiem, co się stało i jak to poprawić:


    {
      "error": "invalid_tz",
      "message": "Unknown tz 'PST'. Use IANA identifiers like 'America/Los_Angeles'.",
      "docs": "https://sunrise-sunset.org/api#tz"
    }

Dla osób zainteresowanych szczegółami technicznymi: używamy standardowych kodów HTTP: 400 dla nieprawidłowych danych wejściowych, 404 dla nieznanych ścieżek, 429 dla zbyt wielu żądań w krótkim czasie.

Limity użycia i podawanie źródła

API jest bezpłatne przy rozsądnej liczbie żądań. Wymagamy podania źródła. Wskaż Sunrise-Sunset.org w widocznym miejscu, aby odbiorcy wiedzieli, skąd pochodzą dane:

Jeśli wysyłasz zbyt wiele żądań w krótkim czasie, API odpowiada kodem 429 („zwolnij”) i nagłówkiem Retry-After z liczbą sekund do odczekania przed kolejną próbą. Zakres dat liczy się jako jedno żądanie, więc jeśli codziennie pokazujesz dane dla tego samego miejsca, pobierz od razu cały rok przez date_start/date_end: szybciej dla ciebie, mniejsze obciążenie dla wszystkich.

Jeszcze jedna rada, jak unikać limitów: godziny dla konkretnej daty nigdy się nie zmieniają, więc zapisz odpowiedź i wykorzystuj ją ponownie (przeglądarki robią to nawet automatycznie). (Szczegóły techniczne: konkretne daty są zwracane z Cache-Control: immutable, today/tomorrow z max-age do lokalnej północy; obsługiwany jest też ETag).

Korzystanie z API na stronie internetowej (JavaScript)

Możesz wywoływać API bezpośrednio ze swojej strony, bez serwera ani zaplecza aplikacji: żądania z dowolnej witryny są dozwolone:

fetch('https://api.sunrise-sunset.org/v2?lat=36.72&lng=-4.42')
  .then(response => response.json())
  .then(data => {
    console.log('Sunrise:', data.sunrise);
    console.log('Sunset:', data.sunset);
  });

Migracja z v1

v1 (/json)v2 (/v2)
formatted=0 (ISO 8601)zawsze ISO 8601, bez dodatkowego parametru
formatted=1 (12h AM/PM)usunięto
tzid=X (nieprawidłowe wartości bez ostrzeżenia zastępowane są przez UTC)tz=X (nieprawidłowe wartości zwracają HTTP 400 invalid_tz)
domyślnie godziny w UTCdomyślnie godziny w lokalnej strefie czasowej współrzędnych
callback (JSONP)usunięto (użyj CORS)
błędy jako status: INVALID_*błędy jako {error, message, docs}
dni polarne: znaczniki czasu z epoki 1970null + sun_status
lat=abc obliczane jako 0HTTP 400 invalid_lat
jedno żądanie dzienniedate_start/date_end (do 366 dni)
n/azłota & niebieska godzina, azymut, wysokość Słońca

Aktualności

Zapisz się do newslettera API, aby otrzymywać informacje o zmianach i aktualnościach dotyczących usługi:

Otrzymuj powiadomienia o każdej zmianie: na GitHub otwórz nasze repozytorium API i wybierz Watch → Custom → Releases lub obserwuj nasz kanał RSS.

Historia zmian

Kontakt

W sprawach dotyczących API skontaktuj się z nami.

If you enjoy using our API please consider supporting the project by buying us a coffee!