Docs › Solunar periods: lunar transits, moonrise and moonset

Solunar periods: lunar transits, moonrise and moonset

The day's solunar periods for a place: major periods centred on the Moon's upper and lower meridian transits, minor periods centred on moonrise and moonset, with the Moon's phase.

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

For fishing, hunting and outdoor apps that use the solunar timing convention: for one local day at a place, each major period (centred on the Moon's upper transit overhead and lower transit underfoot, 2 h by default) and minor period (centred on moonrise and moonset, 1 h by default) with its start, centre and end in local time, the Moon's altitude at its transits and its phase. The events are exact (astronomy/rise-set conventions); the windows are the convention's, adjustable. No rating attached.

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).
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).
optionsobjectWindow lengths.
options.major_minutesinteger120Length of a major period, centred on a lunar transit.
options.minor_minutesinteger60Length of a minor period, centred on moonrise or moonset.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/solunar \
  -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/solunar", 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 p in data["result"]["periods"]:
    print(f'{p["type"]:<5} {p["event"]:<13} {p["start"]["local"][11:16]}-{p["end"]["local"][11:16]}')
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/solunar", {
  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 p of data.result.periods)
  console.log(p.type.padEnd(5), p.event.padEnd(13), p.start.local.slice(11, 16) + "-" + p.end.local.slice(11, 16));
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:

c8f0596d7099d76daaeada87b6f76118f8a79e376d130a18bc4932c08857d796

{
  "endpoint": "astronomy/solunar",
  "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": {
      "major_minutes": 120,
      "minor_minutes": 60,
      "conventions": {
        "major": "centred on the Moon's upper transit (meridian, overhead) and lower transit (opposite meridian, underfoot)",
        "minor": "centred on moonrise and moonset (upper limb, 34' refraction)",
        "windows": "major 120 min, minor 60 min (the solunar convention's 2 h and 1 h by default)",
        "nature": "a timing convention built on the Moon's exact rise, set and transit times; no rating or prediction"
      }
    },
    "moon": {
      "name": "first quarter",
      "illuminated_fraction": 0.44962,
      "age_days": 6.2957
    },
    "periods": [
      {
        "type": "minor",
        "event": "moonset",
        "centre": {
          "utc": "2026-06-20T23:23:02Z",
          "local": "2026-06-21T01:23:02+02:00",
          "timestamp": 1781997782
        },
        "start": {
          "utc": "2026-06-20T22:53:02Z",
          "local": "2026-06-21T00:53:02+02:00",
          "timestamp": 1781995982
        },
        "end": {
          "utc": "2026-06-20T23:53:02Z",
          "local": "2026-06-21T01:53:02+02:00",
          "timestamp": 1781999582
        }
      },
      {
        "type": "major",
        "event": "lower_transit",
        "centre": {
          "utc": "2026-06-21T05:19:19Z",
          "local": "2026-06-21T07:19:19+02:00",
          "timestamp": 1782019159
        },
        "start": {
          "utc": "2026-06-21T04:19:19Z",
          "local": "2026-06-21T06:19:19+02:00",
          "timestamp": 1782015559
        },
        "end": {
          "utc": "2026-06-21T06:19:19Z",
          "local": "2026-06-21T08:19:19+02:00",
          "timestamp": 1782022759
        },
        "moon_altitude": -40.11
      },
      {
        "type": "minor",
        "event": "moonrise",
        "centre": {
          "utc": "2026-06-21T11:30:05Z",
          "local": "2026-06-21T13:30:05+02:00",
          "timestamp": 1782041405
        },
        "start": {
          "utc": "2026-06-21T11:00:05Z",
          "local": "2026-06-21T13:00:05+02:00",
          "timestamp": 1782039605
        },
        "end": {
          "utc": "2026-06-21T12:00:05Z",
          "local": "2026-06-21T14:00:05+02:00",
          "timestamp": 1782043205
        }
      }
    ],
    "counts": {
      "major": 2,
      "minor": 2
    }
  },
  "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": "e4866b27d73ea18af699b3ac36329fda1425dd286dfdc3c57dd5529e9fdc2928",
    "result_sha256": "c8f0596d7099d76daaeada87b6f76118f8a79e376d130a18bc4932c08857d796",
    "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, its time zone, the local date and the day's window in UTC.
result.settingsobjectmajor_minutes, minor_minutes and the convention.
result.moonobjectThe Moon's phase at mid-day: name, illuminated_fraction, age_days.
result.periodsarrayIn time order: {type: major | minor, event: upper_transit | lower_transit | moonrise | moonset, centre, start, end (each {utc, local, timestamp}), moon_altitude (transits)}.
result.countsobjectNumber of major and minor periods that day.
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/solunar?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.