Docs › Equinoxes, solstices, perihelion and day length over a year
Equinoxes, solstices, perihelion and day length over a year
The year's equinoxes and solstices and Earth's perihelion and aphelion to the second; optionally the Sun day by day: sunrise, sunset, day length, solar noon, declination and equation of time.
POST https://astro-agent.dev/v1/astronomy/seasons · $0.01 per call · MCP tool seasons
· Try it in the playground
For calendars, almanacs, education and solar apps: the March and September equinoxes and the June and December solstices (UTC, and local with a place), Earth's perihelion and aphelion with their distances, and with daily=true a row per day: solar noon, the Sun's apparent declination, the equation of time and, for a place, sunrise, sunset and day length, plus the longest and shortest days. Matches the published 2026 times to the minute.
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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
year | integer | yes | | Calendar year. |
latitude | number | | Optional: local times, and with daily=true the day-by-day sunrise, sunset and day length at this place. | |
longitude | number | | Optional, with latitude. | |
elevation_m | number | 0 | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). | |
timezone | string | | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). | |
daily | boolean | false | Add one row per day: solar noon, the Sun's declination, the equation of time and, with a place, sunrise, sunset and day length. |
Example request
curl
curl -s https://astro-agent.dev/v1/astronomy/seasons \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"year": 2026, "latitude": 48.8566, "longitude": 2.3522}'Python
import os
import requests
body = {'year': 2026, 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/seasons", 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()
for e in data["result"]["seasons"]:
print(f'{e["event"]:<19} {e["local"]}')
p = data["result"]["earth_orbit"]["perihelion"][0]
print("Perihelion", p["utc"], p["distance_km"], "km")
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 = {"year": 2026, "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/seasons", {
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();
for (const e of data.result.seasons) console.log(e.event.padEnd(19), e.local);
const p = data.result.earth_orbit.perihelion[0];
console.log("Perihelion", p.utc, p.distance_km, "km");
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:
f199a9fe6c5caf0eb7d4c052138089873f429e315cbba510889f67e110741c1c
{
"endpoint": "astronomy/seasons",
"result": {
"subject": {
"year": 2026,
"location": {
"latitude": 48.8566,
"longitude": 2.3522,
"elevation_m": 0.0
},
"timezone": "Europe/Paris",
"timezone_source": "resolved_from_coordinates"
},
"settings": {
"daily": false,
"conventions": {
"seasons": "the Sun's apparent geocentric ecliptic longitude reaches 0 (March equinox), 90 (June solstice), 180 (September equinox), 270 (December solstice) degrees",
"perihelion_aphelion": "minimum and maximum of the Earth-Sun centre distance",
"daily": "per local calendar day: sunrise/sunset (upper limb, 34' refraction), day length, solar noon, the Sun's apparent declination at solar noon and the equation of time (apparent minus mean solar time, minutes) at solar noon; without a place: latitude 0, longitude 0, no sunrise or sunset"
}
},
"seasons": [
{
"event": "march_equinox",
"utc": "2026-03-20T14:45:57Z",
"timestamp": 1774017957,
"local": "2026-03-20T15:45:57+01:00"
},
{
"event": "june_solstice",
"utc": "2026-06-21T08:24:30Z",
"timestamp": 1782030270,
"local": "2026-06-21T10:24:30+02:00"
},
{
"event": "september_equinox",
"utc": "2026-09-23T00:05:13Z",
"timestamp": 1790121913,
"local": "2026-09-23T02:05:13+02:00"
}
],
"earth_orbit": {
"perihelion": [
{
"utc": "2026-01-03T17:15:47Z",
"timestamp": 1767460547,
"local": "2026-01-03T18:15:47+01:00",
"distance_km": 147099893.0,
"distance_au": 0.983302
}
],
"aphelion": [
{
"utc": "2026-07-06T17:30:51Z",
"timestamp": 1783359051,
"local": "2026-07-06T19:30:51+02:00",
"distance_km": 152087774.0,
"distance_au": 1.016644
}
]
}
},
"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": "d317c614f0067a47a7ba9d08c3b1157cf548ea029578c9f658710cd38d55e8b8",
"result_sha256": "f199a9fe6c5caf0eb7d4c052138089873f429e315cbba510889f67e110741c1c",
"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
| Field | Type | Description |
|---|---|---|
result.subject | object | The year and, with a place, its location and time zone. |
result.settings | object | Whether daily rows are included, and every convention. |
result.seasons | array | [{event: march_equinox | june_solstice | september_equinox | december_solstice, utc, timestamp, local (with a place)}]. |
result.earth_orbit | object | perihelion and aphelion lists: [{utc, timestamp, local, distance_km, distance_au}]. |
result.daily | array | With daily=true: one row per local day: date, solar_noon, sun_declination, equation_of_time_minutes and, with a place, sunrise, sunset, day_length_minutes (null when the Sun does not rise or set). |
result.summary | object | With daily=true and a place: longest_day, shortest_day and their lengths in minutes. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine 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/seasons?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.