API für Sonnenaufgangs- und Sonnenuntergangszeiten

Unsere kostenlose API sagt Ihnen, wann die Sonne überall auf der Erde auf- und untergeht, dazu Dämmerung, goldene Stunde, Sonnenstand und Monddaten. Sie brauchen nur Breiten- und Längengrad: Sie stellen eine einfache GET-Anfrage und erhalten die Antwort als JSON.

Die Zeiten werden in der lokalen Zeitzone des Ortes geliefert, und Sie können einen einzelnen Tag oder bis zu einem ganzen Jahr in einer Anfrage abrufen.

Die API ist kostenlos: keine Anmeldung, kein API-Schlüssel nötig. Wir verlangen jedoch eine Namensnennung: Zeigen Sie in der App oder auf der Seite, auf der Sie die Daten anzeigen, einen sichtbaren Link zu sunrise-sunset.org.

Die Dokumentation der Version 1 der API (/json) ist zur v1-Dokumentation umgezogen. Die API selbst ist unverändert und wird für immer unterstützt.

API-Dokumentation

Senden Sie eine GET-Anfrage an https://api.sunrise-sunset.org/v2. Probieren Sie es gleich aus, dieser Link funktioniert in Ihrem Browser:

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

Einfaches HTTP wird ebenfalls unterstützt: praktisch für IoT und eingebettete Geräte (Arduino, ESP8266, Mikrocontroller), die keine TLS-Verbindungen aufbauen können.

Weitere Beispiele: ein bestimmtes Datum und ein ganzes Jahr in einer Anfrage:

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

Anfrageparameter

Antwort

Alle Zeiten verwenden das ISO 8601-Format: 2026-01-15T08:27:43+01:00 bedeutet 15. Januar um 08:27:43 morgens, Ortszeit (1 Stunde vor UTC). Jede Programmiersprache versteht es sofort; in JavaScript funktioniert new Date(data.sunrise) einfach. Eine Beispielantwort:


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

Mit date_start/date_end ist die Antwort {"tzid", "lat", "lng", "days": […]}, wobei jedes Element von days die obigen Felder hat (ohne tzid/lat/lng).

Ein Zeitraum kann weniger Tage zurückgeben als angefragt. Manche Kalendertage hat es an manchen Orten nie gegeben: Samoa übersprang am 30. Dezember 2011 einen ganzen Tag beim Überqueren der Datumsgrenze. Solche Tage fehlen in days — ordnen Sie die Einträge über ihr Feld date zu, statt einen pro angefragtem Tag anzunehmen.

Felddefinitionen

Was jedes Feld bedeutet, in einfachen Worten, mit der genauen Definition in Klammern (dieselbe Anfrage liefert immer genau dieselben Zeiten):

Schlagen Sie in unserem Glossar astronomischer Begriffe nach, um mehr über die einzelnen Ereignisse zu erfahren.

Polartage und Nullwerte

sun_status ist normal, midnight_sun (die Sonne geht nie unter: day_length ist 86400) oder polar_night (die Sonne geht nie auf: day_length ist 0). Ereignisse, die nicht eintreten, sind null. Alle Ereignisse sind unabhängig voneinander nullbar: nahe den Polarkreisen gibt es Übergangstage, an denen die Sonne aufgeht, aber innerhalb des Kalendertags nicht untergeht; dann hat sunrise einen Wert, sunset ist null, sun_status ist normal und day_length ist null. Schließen Sie nie von einem Ereignis auf ein anderes.

Genauigkeit der Berechnungen

Jedes Sonnenereignis ist der Moment, in dem der Sonnenmittelpunkt eine bestimmte Höhe über dem Horizont überschreitet — −0,833° für Auf- und Untergang und −6°, −12° und −18° für die drei Dämmerungen — und es ist immer der Übergang innerhalb des angefragten lokalen Kalendertags.

Diese Zeiten sind nicht dieselben wie in Version 1 der API. Diese ältere Version behält ihre ursprünglichen Berechnungen bei, damit bestehender Code weiter funktioniert, und ihre Zeiten können von diesen um einige Sekunden in Äquatornähe und um eine Minute oder mehr in hohen Breiten abweichen.

Wir haben diese Version ein ganzes Jahr lang mit einer unabhängigen astronomischen Referenz verglichen, den Planeten-Ephemeriden des JPL, für Städte vom Äquator bis zur Arktis: Sonnenaufgang, Sonnenuntergang und die drei Dämmerungen liegen nur wenige Sekunden daneben, und an den Tagen nahe den Polarkreisen, an denen die Sonne die Schwelle gerade so überschreitet, höchstens etwa eine halbe Minute. Die Zeiten auf unserer Website werden genauso berechnet.

Fehler

Wenn in Ihrer Anfrage etwas nicht stimmt, sagt Ihnen die API in einfachen Worten, was passiert ist und wie Sie es beheben:


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

Für technisch Interessierte: Es werden Standard-HTTP-Statuscodes verwendet: 400 bei ungültiger Eingabe, 404 bei unbekannten Routen, 429, wenn Sie zu viele Anfragen zu schnell senden.

Nutzungsbeschränkungen und Namensnennung

Die API ist bei einer vernünftigen Zahl von Anfragen kostenlos. Eine Quellenangabe ist Pflicht. Nenne Sunrise-Sunset.org überall, wo man sehen kann, woher die Daten stammen:

Wenn Sie zu viele Anfragen zu schnell senden, antwortet die API mit 429 („langsamer“) und einem Retry-After-Header, der angibt, wie viele Sekunden Sie bis zum nächsten Versuch warten sollen. Ein Datumsbereich zählt als eine einzige Anfrage. Wenn Sie also täglich die Daten desselben Ortes anzeigen, fragen Sie einmal das ganze Jahr mit date_start/date_end ab: schneller für Sie, leichter für alle.

Noch ein Tipp, um deutlich unter den Grenzen zu bleiben: Die Zeiten für ein bestimmtes Datum ändern sich nie. Speichern Sie die Antwort also und verwenden Sie sie wieder, statt erneut zu fragen (Browser tun das mit unseren Antworten sogar automatisch). (Technische Details: Explizite Daten werden mit Cache-Control: immutable ausgeliefert, today/tomorrow mit max-age bis Mitternacht Ortszeit, und ETag wird unterstützt.)

Die API von einer Webseite aus verwenden (JavaScript)

Sie können die API direkt von Ihrer Webseite aus aufrufen, ganz ohne Server oder Backend: Anfragen von jeder Website sind erlaubt:

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);
  });

Von v1 migrieren

v1 (/json)v2 (/v2)
formatted=0 (ISO 8601)immer ISO 8601, kein Parameter nötig
formatted=1 (12h AM/PM)entfernt
tzid=X (ungültige Werte fallen still auf UTC zurück)tz=X (ungültige Werte geben HTTP 400 invalid_tz zurück)
Zeiten standardmäßig in UTCZeiten standardmäßig in der lokalen Zeitzone der Koordinaten
callback (JSONP)entfernt (nutzen Sie CORS)
Fehler als status: INVALID_*Fehler als {error, message, docs}
Polartage: Epoch-1970-Zeitstempelnull + sun_status
lat=abc als 0 berechnetHTTP 400 invalid_lat
eine Anfrage pro Tagdate_start/date_end (bis zu 366 Tage)
n/agoldene & blaue Stunde, Azimut, Sonnenhöhe

Ankündigungen

Abonnieren Sie unseren API-Newsletter, um über Änderungen und Ankündigungen zu unserem Dienst auf dem Laufenden zu bleiben:

Über jede Änderung informiert werden: Öffne auf GitHub unser API-Repository und wähle Watch → Custom → Releases, oder abonniere unseren RSS-Feed.

Änderungsprotokoll

Kontakt

Bitte kontaktieren Sie uns für alle Ihre API-Fragen.

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