API-Dokumentation
Integrieren Sie Sonnenuntergangs-Qualitätsprognosen in Ihre Anwendungen
Holen Sie sich einen API-Schlüssel zur NutzungsverfolgungSchnellstart
Erhalten Sie eine Sonnenuntergangsprognose in Sekunden
curl -H "x-api-key: $SUNSET_API_KEY" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Ersetzen Sie $SUNSET_API_KEY durch einen Schlüssel aus Ihrem Dashboard. Anonyme Aufrufe funktionieren für schnelle Demos, sind aber strenger limitiert und liefern keine Rate-Limit-Header.
Beispielantwort
{
"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
}
}Authentifizierung
Externe Anfragen authentifizieren sich über den x-api-key-Header. Erstellen Sie einen Schlüssel in Ihrem Dashboard — der Rohschlüssel wird genau einmal angezeigt.
Header
x-api-key: sp_live_YOUR_API_KEY_HERESenden Sie Ihren API-Schlüssel bei jedem Aufruf im x-api-key-Anfrage-Header.
Scopes
| Scope | Beschreibung |
|---|---|
| predict:read | Sonnenuntergangsvorhersagen lesen (erforderlich für /api/predict) |
| usage:read | Eigene Nutzungsstatistik dieses Schlüssels lesen (erforderlich für /api/usage) |
Limits
Kostenlose Stufe — 100 Anfragen pro Tag und Schlüssel, Zurücksetzung um Mitternacht UTC.
Antwort-Header zum Ratenlimit
Jede erfolgreiche authentifizierte Antwort enthält diese Header, sodass Sie Ihr Kontingent in Echtzeit verfolgen können:
| X-RateLimit-Limit | Maximal zulässige Anfragen im aktuellen Zeitfenster |
| X-RateLimit-Remaining | Heute verbleibende Anfragen |
| X-RateLimit-Reset | ISO 8601-Zeitstempel, zu dem das Kontingent zurückgesetzt wird |
| Retry-After | Wartezeit in Sekunden vor einem erneuten Versuch (nur bei 429) |
Beispiel für eine authentifizierte Anfrage
curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
"https://sunset-predictor.com/api/v1/predict?city=Paris"Endpoint-Referenz
API-Spielplatz
Testen Sie die API direkt im Browser
Beginnt mit sp_live_ und ist 40 Zeichen lang
Wird nur in diesem Browser-Tab gespeichert (sessionStorage). Wird beim Schließen des Tabs gelöscht.
Heute bis 5 Tage im Voraus. Leer lassen für heute.
Anfrage-URL
Code-Beispiele
Fertige Beispiele in gängigen Programmiersprachen
# 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"Snippets aktualisieren sich live mit den Playground-Parametern oben.
Fehlerantworten
Häufige Fehler und ihre Bedeutung
Ungültige Anfrage
Fehlende oder ungültige Parameter. Geben Sie entweder Stadt oder lat/lon an.
{
"error": "Either lat/lon or city must be provided"
}Nicht autorisiert
Fehlender, fehlerhafter oder widerrufener API-Schlüssel. Senden Sie einen gültigen Schlüssel im x-api-key-Header.
{
"error": "Invalid or revoked API key",
"code": "unauthorized"
}Verboten
Der Schlüssel ist gültig, besitzt aber nicht den für diesen Endpunkt erforderlichen Scope predict:read.
{
"error": "Insufficient permissions. Required scope: predict:read",
"code": "insufficientScope"
}Nicht gefunden
Die angegebene Stadt konnte nicht gefunden werden.
{
"error": "City not found",
"code": "cityNotFound"
}Zu viele Anfragen
Tageskontingent überschritten (100 Anfragen/Tag in der kostenlosen Stufe). Zurücksetzung um Mitternacht UTC; prüfen Sie den Retry-After-Header.
{
"error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
"code": "rateLimitExceeded",
"retryAfter": 3600
}Serverfehler
Ein interner Serverfehler ist aufgetreten. Bitte versuchen Sie es später erneut.
{
"error": "Internal server error"
}Bad Gateway
Der vorgelagerte Geocoding-Anbieter ist fehlgeschlagen. Versuchen Sie es mit einer kurzen Verzögerung erneut; erwägen Sie, lat/lon zu senden, um das Geocoding zu überspringen.
{
"error": "Unable to look up city location",
"code": "geocodingFailed"
}Best Practices
Antworten zwischenspeichern
Prognosen werden 30 Minuten lang zwischengespeichert. Vermeiden Sie häufigere Abfragen.
Datumsbereich
Prognosen sind für heute bis 5 Tage im Voraus verfügbar. Entferntere Daten sind weniger genau.
Koordinaten bevorzugen
Die Verwendung von lat/lon ist präziser und vermeidet Mehrdeutigkeit bei geteilten Stadtnamen.
Fehler behandeln
Überprüfen Sie immer den HTTP-Statuscode und behandeln Sie 400/404/500-Antworten angemessen.
Ratenlimits beachten
Lesen Sie X-RateLimit-Remaining bei jeder Antwort. Warten Sie bei 429 das Retry-After-Zeitfenster ab (Zurücksetzung um Mitternacht UTC), bevor Sie es erneut versuchen.
Schlüssel serverseitig aufbewahren
Betten Sie einen API-Schlüssel niemals in ein öffentliches Client-Bundle, eine mobile App oder ein Repository ein. Leiten Sie ihn über Ihr Backend weiter und speichern Sie Schlüssel in Umgebungsvariablen oder einem Secret Manager.
Nutzung & Lizenzierung
Wann der kostenlose Tarif reicht — und wann ein kostenpflichtiger Plan nötig ist.
Kostenloser Tarif
Kostenlos für private, Hobby-, Smart-Home- und Testzwecke.
- •Persönliche Projekte und Prototypen
- •Hobby und Lernen
- •Smart-Home-Dashboards (z. B. Home Assistant) für den privaten Gebrauch
- •Testen und Evaluieren
100 Anfragen/Tag pro API-Schlüssel.
Plus-Tarif
Höhere persönliche Limits und eine werbefreie Website. Nur für private Nutzung — kommerzielle Projekte brauchen Pro.
200 Anfragen/Tag pro API-Schlüssel, 2 API-Schlüssel.
Kommerzielle Nutzung
Kommerzielle Nutzung erfordert einen kostenpflichtigen Plan — Pro oder Business.
Kostenpflichtige Tarife haben höhere Tageslimits und erlauben mehr API-Schlüssel.
Preise ansehenHome Assistant und andere Smart-Home-Integrationen bleiben im kostenlosen Tarif für private, nicht-kommerzielle Nutzung erlaubt.
Halten Sie Ihren API-Schlüssel geheim. Nutzen Sie ihn serverseitig und betten Sie ihn nie in öffentlichen Client-Code ein oder committen ihn in ein Repository.
Baust du etwas Kommerzielles oder stößt du an ein Limit, das du nicht lösen kannst? Support kontaktieren