Planetary aspect windows

Beta bounded orb windows anchored to real exact major-aspect crossings, including retrograde repeats and optional iCalendar text.

POST /api/astro/aspect-windows 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/aspect-windows. 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. The interval is start-inclusive, end-exclusive, greater than zero, and at most 31 elapsed days, within 1900-01-01 through 2050-12-31.

• bodies: two to ten unique lowercase names from Sun through Pluto.
• aspects: optional unique conjunction, sextile, square, trine, or opposition values. Omission selects all five.
• orb_degrees: optional 0.5 through 10.0 in 0.1-degree increments; default 3.0.
• zodiac: optional tropical default or sidereal; sidereal supports Lahiri, Raman, and Krishnamurti.
• include_ical: optional boolean. When true, result.ical contains bounded RFC 5545 text.

Exact-hit-anchored semantics

A returned window is a contiguous period within the chosen orb that contains at least one exact longitude crossing. Merely touching or entering an orb without an exact hit inside the requested interval is not returned. This intentionally excludes tangential orb-only contacts.

window_start_utc and window_end_utc are clipped to the requested interval. If the physical orb boundary lies outside it, entry_utc or exit_utc is null and the matching clipped flag is true. Each exact hit reports relative motion plus applying-before and separating-after labels. Retrograde repetitions use repeat_index and repeat_total per body pair and aspect.

The optional calendar contains one interval event per returned window. It is returned inside JSON only: AstroAPI does not write to, publish, subscribe to, or schedule reminders in any external calendar.

Model and precision

Positions use bundled JPL DE421 apparent geocentric ecliptic-of-date longitude. Exact hits use six-hour search samples and nearest-second timestamps. Orb boundaries use three-hour stepping and a 0.05-second numerical tolerance; entry is the first whole second inside the orb and exit is the first whole second outside it. These are numerical settings, not claims of sub-second physical accuracy. Sidereal rotation changes displayed longitudes but not aspect times.

Request

{
  "start_utc": "2025-03-01T00:00:00Z",
  "end_utc": "2025-04-01T00:00:00Z",
  "bodies": ["mercury", "neptune"],
  "aspects": ["conjunction"],
  "orb_degrees": 3.0,
  "include_ical": false
}

Response shape

{
  "type": "aspect_windows",
  "status": "beta",
  "result": {
    "start_utc": "2025-03-01T00:00:00Z",
    "end_utc": "2025-04-01T00:00:00Z",
    "windows": [
      {
        "body1": "mercury",
        "body2": "neptune",
        "aspect": "conjunction",
        "angle_degrees": 0,
        "orb_degrees": 3.0,
        "window_start_utc": "2025-03-01T00:00:00Z",
        "window_end_utc": "2025-03-04T19:29:16Z",
        "entry_utc": null,
        "exit_utc": "2025-03-04T19:29:16Z",
        "clipped_start": true,
        "clipped_end": false,
        "exact_hits": [{
          "utc": "2025-03-02T16:21:55Z",
          "relative_motion": "increasing",
          "phase_before": "applying",
          "phase_after": "separating",
          "body1_longitude_degrees": 358.953742,
          "body2_longitude_degrees": 358.953749,
          "repeat_index": 1,
          "repeat_total": 2
        }]
      },
      {
        "body1": "mercury",
        "body2": "neptune",
        "aspect": "conjunction",
        "angle_degrees": 0,
        "orb_degrees": 3.0,
        "window_start_utc": "2025-03-26T14:21:06Z",
        "window_end_utc": "2025-04-01T00:00:00Z",
        "entry_utc": "2025-03-26T14:21:06Z",
        "exit_utc": null,
        "clipped_start": false,
        "clipped_end": true,
        "exact_hits": [{
          "utc": "2025-03-30T02:46:30Z",
          "relative_motion": "decreasing",
          "phase_before": "applying",
          "phase_after": "separating",
          "body1_longitude_degrees": 359.985628,
          "body2_longitude_degrees": 359.985632,
          "repeat_index": 2,
          "repeat_total": 2
        }]
      }
    ],
    "window_count": 2,
    "exact_hit_count": 2,
    "model": "de421-apparent-geocentric-aspect-windows-v1",
    "interval": "start_inclusive_end_exclusive",
    "timestamp_resolution_seconds": 1
  }
}

The response example shows the complete two-window result for this request. 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.aspectWindows({
  start_utc: "2025-03-01T00:00:00Z",
  end_utc: "2025-04-01T00:00:00Z",
  bodies: ["mercury", "neptune"],
  aspects: ["conjunction"],
  orb_degrees: 3.0
});
console.log(result.result.windows);

Python - server only

from astroapi_client import AstroAPIClient
api = AstroAPIClient()  # Reads ASTROAPI_KEY.
result = api.aspect_windows({
    "start_utc": "2025-03-01T00:00:00Z",
    "end_utc": "2025-04-01T00:00:00Z",
    "bodies": ["mercury", "neptune"],
    "aspects": ["conjunction"],
    "orb_degrees": 3.0,
})
print(result["result"]["windows"])

The SDK source packages require local installation from this repository; registry publication is separate. Both SDKs use a 35-second default deadline for this 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, exact event search, and API overview.