Sunset Score API

Add sunrise and sunset quality forecasts to your app, travel experience, or agent. Send coordinates. Get a score from 0 to 100.

For your own sunrise and sunset forecasts, you can use the Sunset Score mobile app.

See our API & MCP privacy notice for how we handle request data.

Your first forecast

Copy this command into your terminal to request a three-day forecast in Chicago.

TERMINAL · CHICAGO

curl --fail-with-body --show-error \
  --connect-timeout 10 --max-time 60 \
  --get 'https://api.sunset-score.com/v1/api/forecast' \
  --data-urlencode 'latitude=41.8781' \
  --data-urlencode 'longitude=-87.6298' \
  --data-urlencode 'days=3'

The response is JSON. Errors are printed, and requests time out after 60 seconds.

Requests share a daily allowance. A 429 response means a quota has been reached; wait for Retry-After before trying again. For a production integration or higher volume, contact us at info@sunset-score.com.

Connect an AI agent with MCP

Give a compatible agent access to the read-only get_sunset_forecast tool through Model Context Protocol (MCP). Access is free and rate limited, with no service-level guarantee.

Server URL: https://api.sunset-score.com/mcp
Transport: Streamable HTTP · Authentication: None. No API key is required.

Connect Codex

TERMINAL · CODEX

codex mcp add sunset-score --url https://api.sunset-score.com/mcp

In other clients that support remote MCP servers, enter the server URL above and choose no authentication. Custom MCP connections in ChatGPT depend on your account and workspace permissions.

Local forecasts in ChatGPT

The ChatGPT-specific endpoint is https://api.sunset-score.com/mcp/chatgpt, with no authentication. Its get_local_sunset_forecast tool accepts only days (1–3, default 3) and uses the approximate location shared by the client. It returns event scores, times, attribution and timezone without echoing coordinates.

If the client does not share a usable location, the tool returns location_unavailable without making a forecast request. It cannot look up another destination, historical dates, alerts or subscriptions. Public directory review is separate from connecting this endpoint.

Call the forecast tool

Call get_sunset_forecast with coordinates and optional days:

TOOL ARGUMENTS · CHICAGO

{"latitude":41.8781,"longitude":-87.6298,"days":1}

latitude and longitude are required. The timezone is detected automatically from the coordinates. days accepts 1–3 and defaults to 3. The request parameters and forecast results are the same as REST, with rate-limit information added.

REST and MCP share the same allowance: 900 requests per UTC day across all callers, 60 per network per UTC day, and 15 per network per calendar minute. Clients sharing a network address share its allowance. Both use one concurrent forecast job, a 45-second forecast timeout, and the same operator kill switch.

The MCP adapter waits at most 50 seconds and never automatically retries. Admitted calls that fail still count. Respect retryAfterSeconds in tool errors before retrying.

Connecting a client does not automatically publish a public directory or MCP Registry listing. Self-service payments and paid-account linking are not available.

Request

GET https://api.sunset-score.com/v1/api/forecast

Parameter	Required	Description
`latitude`	Yes	Decimal degrees, from −90 to 90.
`longitude`	Yes	Decimal degrees, from −180 to 180.
`days`	No	1–3 calendar days. Defaults to 3.

One location per request. The timezone is detected automatically from the coordinates and returned in location.timezone. Dates start today in that timezone, or tomorrow after today’s sunrise and sunset are over. Today’s past sunrise may still appear. Historical dates, place names, batching and extra parameters are not supported.

Response

Events are ordered by time. Each score estimates how visually impressive the sky will be. It is a quality score, not a percentage chance of a sunset.

ILLUSTRATIVE RESPONSE · ONE EVENT SHOWN

{
  "apiVersion": "v1",
  "algorithmVersion": 436,
  "generatedAt": "2026-10-07T12:00:00Z",
  "location": {
    "latitude": 41.8781,
    "longitude": -87.6298,
    "timezone": "America/Chicago"
  },
  "days": 3,
  "attribution": {
    "name": "Sunset Score",
    "url": "https://sunset-score.com"
  },
  "results": [
    {
      "type": "Sunset",
      "timeUTC": "2026-10-07T23:23:00Z",
      "score": 74,
      "label": "great"
    }
  ]
}

Reading the forecast

type is Sunrise or Sunset. timeUTC is the event time in UTC; use the detected location.timezone to display local time. score is an integer from 0 to 100. label is a lowercase description, such as great or stunning.

Working with changing weather

Scores change as forecasts update. generatedAt records when the response was produced. Polar day or night, or missing weather coverage, can produce fewer events or an empty results array. The scoring model version may change while the v1 response format stays compatible.

API limits

Access is free and rate limited, with no guaranteed allocation or service-level agreement. Self-service billing is not available. For a product integration that needs an agreed allowance, contact info@sunset-score.com.

Allowance	Limit
Shared across all callers	900 requests per UTC day
Per network address	60 requests per UTC day
Per network address, short bursts	15 requests per calendar minute

Errors and retries

ERROR FORMAT

{ "error": {
  "code": "global_daily_limit",
  "message": "The shared daily API quota has been reached."
} }

HTTP	Meaning	What to do
400	Invalid parameters	Check coordinates and days.
405	Unsupported method	Use GET.
429	Daily or minute quota reached	Wait for the number of seconds in `Retry-After`. Avoid repeated immediate retries.
502 / 504	Forecast unavailable or timed out	Retry later, with backoff. The accepted request still counts.
503	API paused, busy, or temporarily unavailable	Respect `Retry-After`. Paused access may last longer than the suggested retry delay.

Building something with it?

Tell us what you’re making and the volume you expect. We’re exploring integrations for travel, photography, outdoor planning and agents.