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

ParameterTypeRequiredDefaultDescription
yearintegeryesCalendar year.
latitudenumberOptional: local times, and with daily=true the day-by-day sunrise, sunset and day length at this place.
longitudenumberOptional, with latitude.
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).
dailybooleanfalseAdd 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

FieldTypeDescription
result.subjectobjectThe year and, with a place, its location and time zone.
result.settingsobjectWhether daily rows are included, and every convention.
result.seasonsarray[{event: march_equinox | june_solstice | september_equinox | december_solstice, utc, timestamp, local (with a place)}].
result.earth_orbitobjectperihelion and aphelion lists: [{utc, timestamp, local, distance_km, distance_au}].
result.dailyarrayWith 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.summaryobjectWith daily=true and a place: longest_day, shortest_day and their lengths in minutes.
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/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.