API Documentation

Integrate sunset quality predictions into your applications

Base URLhttps://sunset-predictor.com

Quick Start

Get a sunset prediction in seconds

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

Replace $SUNSET_API_KEY with a key from your dashboard. Unauthenticated calls work for quick demos but are stricter and skip rate-limit headers.

Example Response

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

Authentication

External requests authenticate via the x-api-key header. Mint a key from your dashboard — the raw key is shown exactly once.

Header

x-api-key: sp_live_YOUR_API_KEY_HERE

Send your API key in the x-api-key request header on every call.

Scopes

Scope	Description
predict:read	Read sunset predictions (required for /api/predict)
usage:read	Read this key's own usage stats (required for /api/usage)

Limits

Free tier — 100 requests per day per key, reset at UTC midnight.

Rate-limit response headers

Every successful authenticated response carries these headers so you can track quota in real time:

X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	ISO 8601 timestamp when the quota resets
Retry-After	Seconds to wait before retrying (only on 429)

Example authenticated request

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

Endpoint Reference

API Playground

Test the API directly from your browser. Paste your API key to make an authenticated call (counts against your daily quota); leave blank to make an unauthenticated demo call.

Endpoint

API Key (optional)Get a key →

Starts with sp_live_ and is 40 characters long

Stored only in this browser tab (sessionStorage). Cleared when you close the tab.

City

Latitude

Longitude

Date

Today through 5 days ahead. Leave empty for today.

Language

Units

Request URL

GET /api/v1/predict?city=Paris

Code Examples

Ready-to-use examples in popular languages

# 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 update live as you change the playground parameters above.

Error Responses

Common error responses and their meanings

400Client error

Bad Request

Missing or invalid parameters. Provide either city or lat/lon.

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

401Auth / permission

Unauthorized

Missing, malformed, or revoked API key. Send a valid key in the x-api-key header.

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

403Auth / permission

Forbidden

Key is valid but lacks the predict:read scope required for this endpoint.

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

404Client error

Not Found

The specified city could not be found.

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

429Client error

Too Many Requests

Daily quota exceeded (100 requests/day on the free tier). Reset at UTC midnight; check the Retry-After header.

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

500Server error

Server Error

An internal server error occurred. Please try again later.

{
  "error": "Internal server error"
}

502Server error

Bad Gateway

Upstream geocoding provider failed. Retry with a slight delay; consider sending lat/lon to skip geocoding.

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

Best Practices

Cache responses

Predictions are cached server-side for 20 minutes per (lat, lon, lang, date). Avoid polling more frequently.

Date range

Predictions are available from yesterday through 5 days ahead. Further dates return less accurate results.

Prefer coordinates

Using lat/lon is more precise, avoids ambiguity with city names shared across regions, and skips geocoding.

Handle errors gracefully

Check the HTTP status code and the response code field. Surface 401/403 to the user and back off on 429 using Retry-After.

Respect rate limits

Read X-RateLimit-Remaining on every response. On 429, wait for the Retry-After window (UTC midnight reset) before retrying.

Keep keys server-side

Never embed an API key in a public client bundle, mobile app, or repo. Proxy through your backend and store keys in env vars or a secret manager.

Usage & Licensing

When the free tier is enough — and when you need a paid plan.

Free tier

Free for personal, hobby, smart home, and testing use.

•Personal projects and prototypes
•Hobby and learning
•Smart home dashboards (e.g. Home Assistant) for personal use
•Testing and evaluation

100 requests/day per API key.

Plus tier

Higher personal limits for supporters, plus an ad-free site. Personal use only — commercial projects need Pro.

200 requests/day per API key, 2 API keys.

Commercial use

Commercial usage requires a paid plan — Pro or Business.

Paid tiers have higher daily request limits and allow more API keys.

View pricing

Home Assistant and other smart home integrations stay allowed on the free tier for personal, non-commercial use.

Keep your API key secret. Use it server-side and never embed it in public client-side code or commit it to a repository.

Building something commercial or hitting a limit you can't solve? Contact support