---
title: "Get Moon Month"
method: GET
path: "/api/v1/moon/month"
tags: ["Moon Phase"]
---

# Get Moon Month

`GET /api/v1/moon/month`

## Request

- Base URL: `https://api.freeastroapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.freeastroapi.com/api/v1/moon/month`
- Auth: none declared

Get a full calendar month of moon snapshots.

Each entry in `days` mirrors the `/phase` payload for that calendar date.
When a location is provided, the snapshot is taken at local midnight for that calendar day.

## Query parameters

- `year` integer, required: Astronomical year for the month (supported range: 0-2399; year 0 = 1 BCE)
- `month` integer, required: Calendar month number (1-12)
- `city` string, nullable: City name for coordinate lookup (alternative to lat/lon)
- `lat` number, nullable: Latitude for rise/set times
- `lon` number, nullable: Longitude for rise/set times
- `tz_str` string: Timezone string for local calendar sampling. Use AUTO to resolve from city/lat/lon.
- `style_moon_color` string: SVG fill color for the moon (hex)
- `style_shadow_color` string: SVG fill color for the shadow (hex)
- `include_zodiac` boolean: Include zodiac sign information
- `include_rise_set` boolean: Include rise and set times
- `include_visuals` boolean: Include SVG visuals and shadow ratio
- `include_special` boolean: Include special moon types (supermoon, blue moon, etc.)
- `include_eclipse` boolean: Check for a solar or lunar eclipse on or near each date
- `include_forecast` boolean: Include days until next phases and special moons, plus next lunar and solar eclipses
- `include_interpretation` boolean: Include psychological/spiritual moon interpretation based on sign, phase, and decan
- `include_traditional_moon` boolean: Include the traditional full moon name from the North American naming system, for the current full moon or the next upcoming full moon
- `include_sign_timeline` boolean: Include the Moon's sign ingress timeline across the requested month, with start/end times and durations for visual timeline rendering

## Response `200`

Successful Response

- MoonMonthResponse
  - `year` integer, required
  - `month` integer, required
  - `month_name` string, required
  - `days_in_month` integer, required
  - `calendar_basis` string, required
  - `calendar_timezone` string, required
  - `sign_timeline` MoonSignTimelineSegmentData[], nullable
    - `sign` string, required
    - `sign_id` string, required
    - `starts_at` string, required
    - `ends_at` string, required
    - `starts_at_local` string, nullable
    - `ends_at_local` string, nullable
    - `duration_hours` number, required
    - `duration_minutes` integer, required
    - `continues_from_previous_month` boolean, required
    - `continues_to_next_month` boolean, required
    - `next_sign` string, nullable
    - `next_sign_id` string, nullable
    - `label` string, nullable
  - `ingresses` MoonSignIngressData[], nullable
    - `from_sign` string, required
    - `from_sign_id` string, required
    - `to_sign` string, required
    - `to_sign_id` string, required
    - `at` string, required
    - `at_local` string, nullable
    - `label` string, required
  - `days` MoonMonthDayResponse[], required
    - `timestamp` string, required
    - `phase` MoonPhaseData, required
      - `name` string, required
      - `phase_angle_deg` number, required
      - `illumination` number, required
      - `age_days` number, required
      - `distance_km` number, required
      - `is_waxing` boolean, required
    - `zodiac` ZodiacData
      - `sign` string, required
      - `sign_id` string, required
      - `degree` number, required
      - `zodiac_type` string
    - `rise_set` RiseSetData
      - `rise` string, nullable, required
      - `set` string, nullable, required
      - `rise_local` string, nullable
      - `set_local` string, nullable
      - `location` string, nullable
      - `timezone` string
      - `timezone_local` string, nullable
    - `moon_visual` MoonVisualData
      - `type` string
      - `svg` string, required
      - `shadow_ratio` number, required
      - `waxing` boolean, required
    - `special_moon` SpecialMoonData
      - `is_supermoon` boolean
      - `is_micromoon` boolean
      - `is_blue_moon` boolean
      - `is_black_moon` boolean
      - `is_harvest_moon` boolean
      - `is_hunter_moon` boolean
      - `labels` string[]
    - `eclipse` EclipseData
      - `is_eclipse` boolean
      - `is_blood_moon` boolean
      - `kind` string, nullable
      - `type` string, nullable
      - `date` string, nullable
      - `starts_at` string, nullable
      - `ends_at` string, nullable
      - `central_phase_starts_at` string, nullable
      - `central_phase_ends_at` string, nullable
      - `visibility` string, nullable
      - `visible_at_location` boolean, nullable
      - `type_at_location` string, nullable
      - `days_from_query` number, nullable
      - `magnitude` number, nullable
      - `obscuration` number, nullable
      - `maximum_location` EclipseMaximumLocationData
        - `lat` number, required
        - `lon` number, required
      - `local_starts_at` string, nullable
      - `local_maximum_at` string, nullable
      - `local_ends_at` string, nullable
      - `magnitude_at_location` number, nullable
      - `obscuration_at_location` number, nullable
    - `forecast` object, nullable
    - `interpretation` MoonInterpretationData
      - `key` string, required
      - `title` string, required
      - `body` string, required
      - `tone` string, nullable
      - `tags` string[]
    - `traditional_moon` TraditionalMoonData
      - `name` string, required
      - `naming_system` string
      - `month` string, required
      - `applies_to_full_moon_at` string, required
      - `is_current_full_moon` boolean
    - `next_phases` object, required
    - `calendar_date` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/freeastroapi/apis/astroservice-api.md) · [All operations](https://skmtc.dev/freeastroapi/apis/astroservice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freeastroapi/apis/astroservice-api/revisions/0c9b4a759522?raw)