Back to Docs

Astro Events Notification API

Astro Events Notification API

GET/api/v1/sky-events

Build mobile astrology notifications from exact sky events. This endpoint returns a timezone-aware daily feed of planetary ingresses, exact major aspects, retrograde stations, Moon events, and lunations.

The API is global and geocentric. It does not accept lat or lon; use timezone to define the user's local day.

Full URL

https://api.freeastroapi.com/api/v1/sky-events

Query Parameters

Parameter
date
Type
string
Required
Yes
Default
-
Description
Local calendar date for the notification feed in YYYY-MM-DD format.
Parameter
preset
Type
string (quiet | daily | full)
Required
No
Default
quiet
Description
Notification volume preset. Explicit include_* parameters override the preset for individual event families.
Parameter
timezone
Type
string
Required
No
Default
UTC
Description
IANA timezone used to convert the requested local day into UTC boundaries, such as America/New_York, Europe/Paris, or Asia/Tokyo.
Parameter
include_moon
Type
boolean
Required
No
Default
false
Description
Include Moon sign ingress events. Useful for high-frequency lunar notifications.
Parameter
include_exact_hits
Type
boolean
Required
No
Default
true
Description
Include exact major planetary aspects for conjunction, sextile, square, trine, and opposition.
Parameter
include_moon_exact_hits
Type
boolean
Required
No
Default
false
Description
Include exact Moon aspects. Keep disabled for quieter push notification feeds.
Parameter
include_ingresses
Type
boolean
Required
No
Default
true
Description
Include non-Moon sign ingresses for Sun through Pluto.
Parameter
include_retrogrades
Type
boolean
Required
No
Default
false
Description
Include retrograde and direct station events for Mercury through Pluto.
Parameter
include_lunations
Type
boolean
Required
No
Default
false
Description
Include New Moon and Full Moon events.
Parameter
include_formulation
Type
boolean
Required
No
Default
false
Description
Include a short deterministic notification phrase such as Mercury is squaring Neptune.

Notification Presets

quiet

The default. Planet ingresses and exact major planetary aspects, without Moon events or station noise.

daily

Adds Moon sign ingresses and deterministic notification copy for a more active daily feed.

full

Enables Moon aspects, retrograde stations, lunations, and notification copy. Explicit flags can narrow it.

Example Request

cURL

curl -G "https://api.freeastroapi.com/api/v1/sky-events" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-urlencode "date=2026-01-01" \
  --data-urlencode "preset=quiet" \
  --data-urlencode "timezone=America/New_York" \
  --data-urlencode "include_formulation=true" \
  --data-urlencode "include_lunations=true"

Python

import requests

url = "https://api.freeastroapi.com/api/v1/sky-events"
params = {
    "date": "2026-01-01",
    "preset": "quiet",
    "timezone": "America/New_York",
    "include_formulation": "true",
    "include_lunations": "true",
}
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.get(url, params=params, headers=headers, timeout=20)
response.raise_for_status()
events = response.json()["events"]
print(events)

Node.js

const params = new URLSearchParams({
  date: "2026-01-01",
  preset: "quiet",
  timezone: "America/New_York",
  include_formulation: "true",
  include_lunations: "true"
});

const response = await fetch("https://api.freeastroapi.com/api/v1/sky-events?" + params, {
  headers: {
    "x-api-key": process.env.FREEASTROAPI_KEY,
    "Content-Type": "application/json"
  }
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { events } = await response.json();
console.log(events);

Response Shape

Field
date
Type
string
Required
Yes
Description
The requested local calendar date.
Field
timezone
Type
string
Required
Yes
Description
The resolved IANA timezone used for the local-day event window.
Field
events
Type
array<SkyEvent>
Required
Yes
Description
Chronologically sorted astrology events for the requested local day. Empty days return an empty array.

SkyEvent Fields

Field
id
Type
string
Required
Yes
Description
Stable event identifier for client-side dedupe and notification scheduling.
Field
type
Type
string
Required
Yes
Description
One of moon_ingress, planet_ingress, exact_aspect, retrograde_station, or lunation.
Field
title
Type
string
Required
Yes
Description
Human-readable event title, such as Mercury square Neptune.
Field
formulation
Type
string
Required
No
Description
Short notification phrase returned only when include_formulation=true.
Field
exact_time
Type
string
Required
Yes
Description
ISO 8601 datetime in the requested timezone. Use this value to schedule local push notifications.
Field
importance
Type
string
Required
Yes
Description
daily, medium, or major. Use this to filter noisy mobile notification streams.
Field
body
Type
string
Required
No
Description
Single body label for ingress and station events.
Field
sign
Type
string
Required
No
Description
Zodiac sign for ingress and lunation events.
Field
bodies
Type
array<string>
Required
No
Description
Bodies involved in aspect or lunation events.
Field
aspect
Type
string
Required
No
Description
Aspect name for exact_aspect events: conjunction, sextile, square, trine, or opposition.
Field
angle
Type
integer
Required
No
Description
Aspect angle in degrees for exact_aspect events.
Field
orb
Type
integer
Required
No
Description
Always 0 for exact aspect events.
Field
direction
Type
string
Required
No
Description
retrograde or direct for station events.
Field
phase
Type
string
Required
No
Description
new_moon or full_moon for lunation events.

Event Types

planet_ingress

Planet enters a new zodiac sign.

Fields

body, sign

moon_ingress

Moon enters a new zodiac sign.

Fields

body, sign

exact_aspect

Two bodies reach an exact major aspect.

Fields

bodies, aspect, angle, orb

retrograde_station

A planet stations retrograde or direct.

Fields

body, direction

lunation

New Moon or Full Moon event.

Fields

phase, bodies, sign

Sample Response

{
  "date": "2026-01-01",
  "timezone": "America/New_York",
  "events": [
    {
      "id": "mercury_square_neptune_2026_01_01",
      "type": "exact_aspect",
      "title": "Mercury square Neptune",
      "formulation": "Mercury is squaring Neptune",
      "exact_time": "2026-01-01T08:33:10-05:00",
      "importance": "major",
      "bodies": ["Mercury", "Neptune"],
      "aspect": "square",
      "angle": 90,
      "orb": 0
    },
    {
      "id": "mercury_enters_capricorn_2026_01_01",
      "type": "planet_ingress",
      "title": "Mercury enters Capricorn",
      "formulation": "Mercury is entering Capricorn",
      "exact_time": "2026-01-01T16:10:42-05:00",
      "importance": "medium",
      "body": "Mercury",
      "sign": "Capricorn"
    }
  ]
}

Mobile Notification Notes

Use event.id as the dedupe key when scheduling push jobs. Use event.exact_time as the local trigger time, and store the requested timezone with each user's notification settings.

For quieter default notifications, keep Moon exact hits, retrogrades, and lunations opt-in. Filter by importance when customers only want major events.

include_formulation=true adds short deterministic text for push copy. It is not AI-generated, so repeated requests return stable phrasing.

Use preset=daily for a balanced daily feed or preset=full for every supported event family. Individual include_* parameters override the preset.

Errors and Limits

Authentication uses the standard x-api-key header. Rate limit headers are returned by the API middleware.

Validation errors return HTTP 400 with a structured detail object. Common errors are invalid_date and invalid_timezone.

Successful responses include a private 24-hour Cache-Control header and a deterministic ETag. Send the ETag in If-None-Match to receive HTTP 304 when the feed has not changed.

{
  "detail": {
    "error": "invalid_timezone",
    "message": "Invalid timezone 'Mars/Phobos'. Use a valid IANA timezone such as UTC or Europe/Paris."
  }
}

Related Endpoints

Ephemeris API

Query planetary positions and date ranges for more detailed astronomy data.

Moon Phase Timeline API

Build lunar calendars with phase and Moon sign timeline data.

Transit Timeline API

Generate longer transit intervals for calendars and forecasting UIs.

Rate Limits

Understand quota headers, Retry-After behavior, and backoff strategy.

FAQ

What is the Astro Events Notification API?

The Astro Events Notification API returns daily sky event timing for astrology apps, including ingresses, exact aspects, retrograde stations, and lunations. It is designed for mobile push notification scheduling and event feeds.

Can I use this endpoint for mobile astrology notifications?

Yes. Use exact_time to schedule notifications in the user's timezone, id to deduplicate scheduled jobs, importance to filter volume, and formulation for short notification copy.

Does the sky events endpoint use latitude or longitude?

No. The current endpoint is a global geocentric sky event feed. It accepts date and timezone only for local-day boundaries, and does not expose lat or lon parameters.

Which event types are supported?

The endpoint supports Moon ingresses, planet ingresses, exact major aspects, retrograde or direct stations, and New Moon or Full Moon lunations.