Planetary events
Two date modes: standard civil inputs cover 1800–2200. All 77 date-bearing operations also accept explicit historical inputs from 1000 BCE (BC) to 2500 CE (AD), with a chosen calendar and, for timed calculations, UT1 or a fixed UT1 offset. Date-only numerology requires an explicit year-digit convention. Place search is date-independent. Each tool retains its search, geometry, derived-date and export limits; historical iCalendar is not supported. The ordinary date-string examples below describe standard mode. Historical input guide and current schemas.
Current, 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.cosmicephemeris.com/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 1800-01-01 through 2200-12-31. Results contain at most 512 events.
event_types: one or more unique values fromsign_ingress,station, andaspect.bodies: unique values from Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto, written in lowercase.aspects: optional only whenaspectis selected. Choose conjunction, sextile, square, trine, or opposition. Omission selects all five; at least two bodies are required.zodiac: optionaltropicaldefault orsidereal. Sidereal supports Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, and Galactic Alignment/Mardyks 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 DE440 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. The documented 1800–2200 contract is current. Results remain model-dependent, and future UTC values 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": "current",
"result": {
"start_utc": "2026-01-01T00:00:00Z",
"end_utc": "2026-01-08T00:00:00Z",
"events": [
{
"type": "aspect",
"utc": "2026-01-01T13:33:10Z",
"body1": "mercury",
"body2": "neptune",
"aspect": "square",
"angle_degrees": 90,
"body1_longitude_degrees": 269.51397,
"body2_longitude_degrees": 359.513971
}
],
"event_count": 6,
"model": "de440-apparent-geocentric-planetary-events-v1",
"interval": "start_inclusive_end_exclusive",
"timestamp_resolution_seconds": 1
},
"metadata": {
"ephemeris": "JPL-DE440",
"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 { CosmicEphemeris } from "cosmicephemeris";
const api = new CosmicEphemeris(); // Reads COSMICEPHEMERIS_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 cosmicephemeris_client import CosmicEphemerisClient
api = CosmicEphemerisClient() # Reads COSMICEPHEMERIS_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 current examples use cosmicephemeris@0.5.0 for Node.js and cosmicephemeris-client==0.5.0 for Python. 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.