Planetary events

Beta bounded searches for sign ingresses, motion-reversal stations, and exact major longitude aspects.

POST /api/astro/planetary-events requires a server-side API key. All plans use one standard quota unit per admitted attempt, including invalid input, calculation failure, and timeout. Do not automatically retry.

Public endpoint: https://api.astroapi.io/api/astro/planetary-events. Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json; load the real key from your server environment.

Inputs and limits

Provide whole-second UTC start_utc and end_utc timestamps ending in Z. The interval is start-inclusive, end-exclusive, greater than zero, and at most 31 elapsed days. Input coverage is 1900-01-01 through 2050-12-31. Results contain at most 512 events.

  • event_types: one or more unique values from sign_ingress, station, and aspect.
  • bodies: unique values from Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto, written in lowercase.
  • aspects: optional only when aspect is selected. Choose conjunction, sextile, square, trine, or opposition. Omission selects all five; at least two bodies are required.
  • zodiac: optional tropical default or sidereal. Sidereal supports Lahiri, Raman, and Krishnamurti ayanamsas.

Arrays use exact, case-sensitive enum values and reject duplicates. The route accepts no coordinates, houses, custom orbs, uploaded kernels, arbitrary targets, interpretations, eclipse claims, or automatic calendar export.

What each event means

Sign ingresses are actual crossings of a 30-degree boundary in the selected zodiac. Direct and retrograde crossings identify both the departing and entered sign.

Stations are reversals in apparent geocentric tropical ecliptic longitude, determined with a centered one-hour finite-difference speed. A sidereal request changes the reported longitude, not the physical station time.

Exact aspects are crossings of 0°, 60°, 90°, 120°, or 180° separation in apparent geocentric ecliptic longitude. They are invariant under a shared tropical-to-sidereal rotation. No orb window, applying/separating label, or tangential contact at a stationary extremum is returned.

Model, precision, and accuracy

Positions use the bundled JPL DE421 ephemeris through Skyfield, apparent geocentric ecliptic-of-date longitude, fixed six-hour search samples, and bisection to a 0.05-second numerical bracket. Event timestamps are rounded to one second. These settings describe numerical resolution within this model; they do not promise sub-second physical accuracy.

Selected 2026 events were independently compared with Swiss Ephemeris/Moshier references and must agree within 30 seconds in the automated fixture. Broader epochs, specialist conventions, and practitioner acceptance remain open. Future UTC can change after reviewed time-scale data updates.

Request

{
  "start_utc": "2026-01-01T00:00:00Z",
  "end_utc": "2026-01-08T00:00:00Z",
  "event_types": ["sign_ingress", "aspect"],
  "bodies": ["moon", "mercury", "neptune"],
  "aspects": ["square"]
}

Response shape

{
  "type": "planetary_events",
  "status": "beta",
  "result": {
    "start_utc": "2026-01-01T00:00:00Z",
    "end_utc": "2026-01-08T00:00:00Z",
    "events": [
      {
        "type": "aspect",
        "utc": "2026-01-01T13:33:09Z",
        "body1": "mercury",
        "body2": "neptune",
        "aspect": "square",
        "angle_degrees": 90,
        "body1_longitude_degrees": 269.513953,
        "body2_longitude_degrees": 359.513959
      }
    ],
    "event_count": 6,
    "model": "de421-apparent-geocentric-planetary-events-v1",
    "interval": "start_inclusive_end_exclusive",
    "timestamp_resolution_seconds": 1
  },
  "metadata": {
    "ephemeris": "JPL-DE421",
    "frame": "apparent_geocentric_ecliptic_of_date",
    "zodiac": "tropical",
    "ayanamsa": null,
    "station_frame": "tropical_longitude",
    "search_step_hours": 6,
    "root_tolerance_seconds": 0.05,
    "interpretations": false
  }
}

The shortened example shows one of six events. Parse the complete result.events array and use each event's type discriminator. Malformed inputs return 400. Authentication, quota, concurrency, dependency, and timeout errors retain the standard API behavior.

Node.js 22+ — server only

import { AstroAPI } from "@astroapi/node";
const api = new AstroAPI(); // Reads ASTROAPI_KEY.
const result = await api.planetaryEvents({
  start_utc: "2026-01-01T00:00:00Z",
  end_utc: "2026-01-08T00:00:00Z",
  event_types: ["sign_ingress", "aspect"],
  bodies: ["moon", "mercury", "neptune"],
  aspects: ["square"]
});
console.log(result.result.events);

Python — server only

from astroapi_client import AstroAPIClient
api = AstroAPIClient()  # Reads ASTROAPI_KEY.
result = api.planetary_events({
    "start_utc": "2026-01-01T00:00:00Z",
    "end_utc": "2026-01-08T00:00:00Z",
    "event_types": ["sign_ingress", "aspect"],
    "bodies": ["moon", "mercury", "neptune"],
    "aspects": ["square"],
})
print(result["result"]["events"])

The SDK source packages require local installation from the repository; registry publication is separate. The SDKs use a 35-second default deadline for this bounded route. Each example makes one billable call. Keep credentials out of browser bundles and shared collections.

See the complete OpenAPI contract, Postman collection, calculation methodology, and API overview.