Docs › Rise, set and twilight times for a place

Rise, set and twilight times for a place

Rise, transit and set of the Sun, Moon and planets for a place and local day, with civil, nautical and astronomical twilight, day length, golden hour and blue hour.

POST https://astro-agent.dev/v1/astronomy/rise-set · $0.01 per call · MCP tool rise_set_times · Try it in the playground

For sky, weather, photography and outdoor apps: for one local calendar day at a place (time zone and DST resolved from the coordinates), each body's rise and set (with azimuth) and upper transit (with altitude), or 'always_up' / 'always_down' when it neither rises nor sets (polar day and night); for the Sun, dawn and dusk at -6, -12 and -18 degrees, solar noon, day length, and the golden hour (Sun between -4 and +6 degrees) and blue hour (-6 to -4) intervals. Times in UTC to the second, local time with its offset, and unix timestamps; every convention (refraction, limb, horizon) is in result.settings.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
datestringyesThe local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30), midnight to midnight in its time zone.
latitudenumberyesDecimal degrees, north positive.
longitudenumberyesDecimal degrees, east positive.
elevation_mnumber0Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled).
timezonestringIANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules).
bodiesarray of string (sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto)Bodies to time. Default: all ten (Sun, Moon, Mercury..Pluto). The Sun's twilight block is always returned.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/rise-set \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-06-21", "latitude": 48.8566, "longitude": 2.3522}'

Python

import os
import requests

body = {'date': '2026-06-21', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/rise-set", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

s = data["result"]["sun"]
print("Sunrise", s["sunrise"]["local"], "  Sunset", s["sunset"]["local"],
      "  Day", s["day_length_minutes"], "min")
for b in data["result"]["bodies"]:
    rise, sett = (b["rise"] or {}).get("local", "-"), (b["set"] or {}).get("local", "-")
    print(f'{b["body"]:<8} rise {rise:<26} set {sett:<26} {b["state"]}')
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"date": "2026-06-21", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/rise-set", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

const s = data.result.sun;
console.log("Sunrise", s.sunrise.local, " Sunset", s.sunset.local, " Day", s.day_length_minutes, "min");
for (const b of data.result.bodies)
  console.log(b.body.padEnd(8), "rise", b.rise ? b.rise.local : "-", "set", b.set ? b.set.local : "-", b.state);
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

e1dfbd240995cda65870a47389ad3d5c571fbfc5480b770a6ba88d5bce7f3896

{
  "endpoint": "astronomy/rise-set",
  "result": {
    "subject": {
      "location": {
        "latitude": 48.8566,
        "longitude": 2.3522,
        "elevation_m": 0.0
      },
      "timezone": "Europe/Paris",
      "timezone_source": "resolved_from_coordinates",
      "date": "2026-06-21",
      "window_utc": {
        "start": "2026-06-20T22:00:00Z",
        "end": "2026-06-21T22:00:00Z"
      }
    },
    "settings": {
      "bodies": [
        "sun",
        "moon",
        "mercury"
      ],
      "conventions": {
        "observer": "WGS84 ellipsoid; elevation above it optional (no terrain, no horizon dip)",
        "rise_set": "upper limb of the Sun and the Moon on the horizon with 34' of standard refraction (Sun: -0.8333 deg; Moon: its apparent radius and parallax); planets: centre at -0.5667 deg",
        "transit": "upper meridian transit (culmination), with the altitude reached",
        "twilight": "Sun's centre at -6 (civil), -12 (nautical), -18 (astronomical) degrees",
        "golden_hour": "Sun's centre between -4 and +6 degrees",
        "blue_hour": "Sun's centre between -6 and -4 degrees",
        "day": "the local calendar day at the place, midnight to midnight in its time zone",
        "times": "UTC to the second, with the local time (ISO 8601 with offset) and a unix timestamp"
      }
    },
    "bodies": [
      {
        "body": "sun",
        "rise": {
          "utc": "2026-06-21T03:46:57Z",
          "local": "2026-06-21T05:46:57+02:00",
          "timestamp": 1782013617,
          "azimuth": 51.6
        },
        "transit": {
          "utc": "2026-06-21T11:52:24Z",
          "local": "2026-06-21T13:52:24+02:00",
          "timestamp": 1782042744,
          "altitude": 64.58
        },
        "set": {
          "utc": "2026-06-21T19:57:52Z",
          "local": "2026-06-21T21:57:52+02:00",
          "timestamp": 1782071872,
          "azimuth": 308.4
        },
        "state": "rises_and_sets"
      },
      {
        "body": "moon",
        "rise": {
          "utc": "2026-06-21T11:30:05Z",
          "local": "2026-06-21T13:30:05+02:00",
          "timestamp": 1782041405,
          "azimuth": 89.87
        },
        "transit": {
          "utc": "2026-06-21T17:40:54Z",
          "local": "2026-06-21T19:40:54+02:00",
          "timestamp": 1782063654,
          "altitude": 39.03
        },
        "set": {
          "utc": "2026-06-20T23:23:02Z",
          "local": "2026-06-21T01:23:02+02:00",
          "timestamp": 1781997782,
          "azimuth": 274.84
        },
        "state": "rises_and_sets"
      },
      {
        "body": "mercury",
        "rise": {
          "utc": "2026-06-21T05:44:00Z",
          "local": "2026-06-21T07:44:00+02:00",
          "timestamp": 1782020640,
          "azimuth": 55.64
        },
        "transit": {
          "utc": "2026-06-21T13:33:53Z",
          "local": "2026-06-21T15:33:53+02:00",
          "timestamp": 1782048833,
          "altitude": 62.38
        },
        "set": {
          "utc": "2026-06-21T21:22:29Z",
          "local": "2026-06-21T23:22:29+02:00",
          "timestamp": 1782076949,
          "azimuth": 304.0
        },
        "state": "rises_and_sets"
      }
    ],
    "sun": {
      "sunrise": {
        "utc": "2026-06-21T03:46:57Z",
        "local": "2026-06-21T05:46:57+02:00",
        "timestamp": 1782013617,
        "azimuth": 51.6
      },
      "solar_noon": {
        "utc": "2026-06-21T11:52:24Z",
        "local": "2026-06-21T13:52:24+02:00",
        "timestamp": 1782042744,
        "altitude": 64.58
      },
      "sunset": {
        "utc": "2026-06-21T19:57:52Z",
        "local": "2026-06-21T21:57:52+02:00",
        "timestamp": 1782071872,
        "azimuth": 308.4
      },
      "civil_dawn": {
        "utc": "2026-06-21T03:04:17Z",
        "local": "2026-06-21T05:04:17+02:00",
        "timestamp": 1782011057
      },
      "civil_dusk": {
        "utc": "2026-06-21T20:40:32Z",
        "local": "2026-06-21T22:40:32+02:00",
        "timestamp": 1782074432
      },
      "nautical_dawn": {
        "utc": "2026-06-21T02:03:32Z",
        "local": "2026-06-21T04:03:32+02:00",
        "timestamp": 1782007412
      },
      "nautical_dusk": {
        "utc": "2026-06-21T21:41:17Z",
        "local": "2026-06-21T23:41:17+02:00",
        "timestamp": 1782078077
      },
      "astronomical_dawn": null,
      "astronomical_dusk": null,
      "day_length_minutes": 970.9,
      "golden_hour": [
        {
          "period": "morning",
          "start": {
            "utc": "2026-06-21T03:21:29Z",
            "local": "2026-06-21T05:21:29+02:00",
            "timestamp": 1782012089
          },
          "end": {
            "utc": "2026-06-21T04:36:58Z",
            "local": "2026-06-21T06:36:58+02:00",
            "timestamp": 1782016618
          }
        },
        {
          "period": "evening",
          "start": {
            "utc": "2026-06-21T19:07:50Z",
            "local": "2026-06-21T21:07:50+02:00",
            "timestamp": 1782068870
          },
          "end": {
            "utc": "2026-06-21T20:23:19Z",
            "local": "2026-06-21T22:23:19+02:00",
            "timestamp": 1782073399
          }
        }
      ],
      "blue_hour": [
        {
          "period": "morning",
          "start": {
            "utc": "2026-06-21T03:04:17Z",
            "local": "2026-06-21T05:04:17+02:00",
            "timestamp": 1782011057
          },
          "end": {
            "utc": "2026-06-21T03:21:29Z",
            "local": "2026-06-21T05:21:29+02:00",
            "timestamp": 1782012089
          }
        },
        {
          "period": "evening",
          "start": {
            "utc": "2026-06-21T20:23:19Z",
            "local": "2026-06-21T22:23:19+02:00",
            "timestamp": 1782073399
          },
          "end": {
            "utc": "2026-06-21T20:40:32Z",
            "local": "2026-06-21T22:40:32+02:00",
            "timestamp": 1782074432
          }
        }
      ]
    }
  },
  "meta": {
    "engine": "astro-agents/1.9.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "e7ebc05d5ce6203c372c141abf8602f4ce843a0c230c2f6b0f563433b51d552e",
    "result_sha256": "e1dfbd240995cda65870a47389ad3d5c571fbfc5480b770a6ba88d5bce7f3896",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
  }
}

Response fields

FieldTypeDescription
result.subjectobjectThe place (latitude, longitude, elevation_m), its time zone and how it was found, the local date and the day's window in UTC (midnight to midnight local time).
result.settingsobjectThe bodies timed and every convention: observer model, rise/set limb and refraction, twilight and golden/blue hour altitudes.
result.bodiesarrayOne row per body: rise and set {utc, local (ISO 8601 with offset), timestamp (unix seconds)} with azimuth, transit with altitude (null when it does not happen that day), and state: rises_and_sets, rises_only, sets_only, always_up or always_down.
result.sunobjectsunrise, solar_noon, sunset, civil/nautical/astronomical dawn and dusk (null when the Sun does not reach that depth), day_length_minutes, golden_hour and blue_hour intervals [{period, start, end}].
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/rise-set?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.