API für Sonnenauf- und -untergangszeiten v2

Unsere kostenlose API sagt dir, wann die Sonne überall auf der Erde auf- und untergeht, dazu Dämmerung, goldene Stunde, Sonnenstand und Mond-Daten. Du brauchst nur einen Breiten- und Längengrad: du machst eine einfache GET-Anfrage und bekommst die Antwort als JSON.

Die Zeiten kommen in der lokalen Zeitzone des Ortes, und du kannst einen einzelnen Tag oder bis zu einem ganzen Jahr in einer Anfrage abfragen.

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

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

Mache eine GET-Anfrage an https://api.sunrise-sunset.org/v2. Probier es gleich aus, dieser Link funktioniert in deinem 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-08-04
https://api.sunrise-sunset.org/v2?lat=36.7201600&lng=-4.4203400&date_start=2026-01-01&date_end=2026-12-31

Parameter anfordern

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:27:43+01:00",
      "sunset": "2026-01-15T18:26:27+01:00",
      "solar_noon": "2026-01-15T13:27:05+01:00",
      "day_length": 35924,
      "sun_status": "normal",
      "civil_twilight_begin": "2026-01-15T08:01:01+01:00",
      "civil_twilight_end": "2026-01-15T18:53:09+01:00",
      "nautical_twilight_begin": "2026-01-15T07:29:13+01:00",
      "nautical_twilight_end": "2026-01-15T19:24:57+01:00",
      "astronomical_twilight_begin": "2026-01-15T06:58:10+01:00",
      "astronomical_twilight_end": "2026-01-15T19:56:00+01:00",
      "dawn": "2026-01-15T08:01:01+01:00",
      "dusk": "2026-01-15T18:53:09+01:00",
      "first_light": "2026-01-15T07:29:13+01:00",
      "last_light": "2026-01-15T19:24:57+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:01+01:00", "end": "2026-01-15T08:11:54+01:00" },
        "evening": { "begin": "2026-01-15T18:42:33+01:00", "end": "2026-01-15T18:53:09+01:00" }
      },
      "solar_position": {
        "sunrise_azimuth": 118.31,
        "sunset_azimuth": 241.82,
        "solar_noon_azimuth": 180.09,
        "solar_noon_altitude": 32.06
      },
      "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).

Felddefinitionen

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

Sieh in unserem Glossar astronomischer Definitionen nach, um mehr über jedes Ereignis 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ße niemals von einem Ereignis auf ein anderes.

Fehler

Wenn in deiner Anfrage etwas falsch ist, sagt dir die API in einfachen Worten, was passiert ist und wie du es behebst:


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

Für die technisch Interessierten: es werden Standard-HTTP-Statuscodes verwendet: 400 bei ungültiger Eingabe, 404 bei unbekannten Routen, 429, wenn du zu viele Anfragen zu schnell sendest.

Nutzungsbeschränkungen und Namensnennung

Die API ist für angemessene Anfragemengen kostenlos. Wir verlangen, dass du eine Namensnennung mit einem Link zu unserer Seite anzeigst.

Wenn du zu viele Anfragen zu schnell sendest, antwortet die API mit 429 („langsamer") und einem Retry-After-Header, der dir sagt, wie viele Sekunden du vor dem nächsten Versuch warten sollst. Ein Datumsbereich zählt als eine einzige Anfrage, also wenn du täglich die Daten desselben Ortes anzeigst, frage einmal das ganze Jahr mit date_start/date_end ab: schneller für dich, leichter für alle.

Noch ein Tipp, um deutlich unter den Grenzen zu bleiben: die Zeiten für ein bestimmtes Datum ändern sich nie, also speichere die Antwort und verwende 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)

Du kannst die API direkt von deiner Webseite aus aufrufen, 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 (nutze 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:

Änderungsprotokoll

Kontakt

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

Wenn Ihnen die Nutzung unserer API gefällt, sollten Sie das Projekt unterstützen, indem Sie uns einen Kaffee spendieren!