Moon Phase Timeline

GET/api/v1/moon/month

Retrieve a full month of moon snapshots plus optional sign intervals and ingress events. This endpoint is designed for lunar calendars, timeline views, and UI visualizations that need one request instead of one call per day.

Full URL

https://api.freeastroapi.com/api/v1/moon/month

Plan Access

This endpoint is available on the Entry and High plans. Free keys receive a structured 403 response with entry_or_high_plan_required.

Daily /api/v1/moon/phase remains the right choice for lightweight free-tier checks.

Calendar Behavior

The month endpoint calculates the calendar in UTC by default. Provide location via city or lat/lon for local-calendar behavior and observer-specific data. Each item in days gets a calendar_date, while its timestamp remains in UTC. Without location context, the endpoint falls back to UTC calendar days.

City lookup: Pass city when you want the same convenience as the single-date Moon endpoint.
Local midnights: With city or lat/lon, the month is sampled at local midnight in the resolved timezone.
Timezone handling: tz_str defaults to AUTO, which resolves timezone from city or lat/lon. You can also pass an explicit IANA timezone such as Europe/Paris.
days[] is for daily moon snapshots.
sign_timeline[] is for interval bars on a timeline.
ingresses[] is for event markers such as Virgo -> Libra.

Query Parameters

Parameter	Type	Required	Description
year	integer	Yes	Calendar year to fetch, such as 2026.
month	integer	Yes	Calendar month from 1 to 12.
city	string	No	City name for coordinate lookup and timezone resolution (alternative to lat/lon).
lat	float	No	Latitude for local-calendar sampling and observer-specific data. Default: None.
lon	float	No	Longitude for local-calendar sampling and observer-specific data. Default: None.
tz_str	string	No	Timezone string for local calendar sampling and naive datetime interpretation. Default: AUTO.
include_zodiac	boolean	No	Include the Moon's tropical zodiac sign for each day. Default: false.
include_visuals	boolean	No	Include the moon SVG and shadow ratio for every day in the month. Default: false.
include_special	boolean	No	Include special moon labels for each day, such as supermoon or harvest moon. Default: false.
include_eclipse	boolean	No	Include eclipse checks in each daily row. Default: false.
include_forecast	boolean	No	Include next-phase and next-event forecasting per day. Default: false.
include_traditional_moon	boolean	No	Include the traditional full-moon naming block for each day. Default: false.
include_sign_timeline	boolean	No	Return top-level sign intervals and ingress markers for the month. Default: false.
style_moon_color	string	No	Hex color for illuminated moon fill inside daily SVG responses. Default: #E0E0E0.
style_shadow_color	string	No	Hex color for shadow fill inside daily SVG responses. Default: #1A1A1A.

Timeline Semantics

Segments in sign_timeline include duration_hours and duration_minutesso the frontend can size bars without extra math. Transition rows also include next_sign, next_sign_id, and a ready-made label.

The final segment in the month does not invent a future ingress. It returns next_sign: null, next_sign_id: null, and label: null, while continues_to_next_month tells you the interval continues past the visible range.

Sample Code

curl -X GET "https://api.freeastroapi.com/api/v1/moon/month?year=2026&month=4&city=Paris&tz_str=AUTO&include_zodiac=true&include_visuals=true&include_traditional_moon=true&include_sign_timeline=true" \
 -H "x-api-key: YOUR_API_KEY"

Response Data

This example is based on a real saved April 2026 response for Paris. The structure and values are real; the SVG payload is shortened to <svg>...</svg> for readability.

{
  "year": 2026,
  "month": 4,
  "month_name": "April",
  "days_in_month": 30,
  "calendar_basis": "local",
  "calendar_timezone": "Europe/Paris",
  "sign_timeline": [
    {
      "sign": "Virgo",
      "sign_id": "virgo",
      "starts_at": "2026-03-31T22:00:00Z",
      "ends_at": "2026-04-01T02:51:05Z",
      "starts_at_local": "2026-04-01T00:00:00+02:00",
      "ends_at_local": "2026-04-01T04:51:05+02:00",
      "duration_hours": 4.85,
      "duration_minutes": 291,
      "next_sign": "Libra",
      "next_sign_id": "libra",
      "label": "Virgo -> Libra",
      "continues_from_previous_month": true,
      "continues_to_next_month": false
    }
  ],
  "ingresses": [
    {
      "from_sign": "Virgo",
      "from_sign_id": "virgo",
      "to_sign": "Libra",
      "to_sign_id": "libra",
      "at": "2026-04-01T02:51:05Z",
      "at_local": "2026-04-01T04:51:05+02:00",
      "label": "Virgo -> Libra"
    }
  ],
  "days": [
    {
      "calendar_date": "2026-04-01",
      "timestamp": "2026-03-31T22:00:00+00:00",
      "phase": {
        "name": "Waning Gibbous",
        "phase_angle_deg": 214.63,
        "illumination": 0.91,
        "age_days": 17.6,
        "distance_km": 384120,
        "is_waxing": false
      },
      "zodiac": {
        "sign": "Virgo",
        "sign_id": "virgo",
        "degree": 27.88,
        "zodiac_type": "tropical"
      },
      "moon_visual": {
        "type": "svg",
        "svg": "<svg>...</svg>",
        "shadow_ratio": 0.09,
        "waxing": false
      },
      "traditional_moon": {
        "name": "Pink Moon",
        "naming_system": "north_american_traditional",
        "month": "April",
        "applies_to_full_moon_at": "2026-04-02T02:46:09Z",
        "is_current_full_moon": false
      }
    }
  ]
}

Best Use Cases

Build month-grid moon calendars with one call instead of 28 to 31 daily requests.
Render sign-ingress timelines using sign_timeline plus ingresses.
Attach SVG moon icons to each day by enabling include_visuals=true.
Combine daily astrology context with timeline rendering for apps, dashboards, and printable planners.

Next Steps

Moon Phase Endpoint

Use the single-date moon endpoint for lightweight checks

City Search

Resolve coordinates before building local calendar timelines