Moon Phase & Visuals

GET/api/v1/moon/phase

Retrieve detailed moon phase data, including illumination, age, distance, and zodiac sign. Generate high-quality SVG visuals for any date and observer location.

Need a full monthly lunar calendar or ingress timeline? Use the Moon Phase Timeline API docs for /api/v1/moon/month.

Full URL

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

Monthly Calendar Endpoint

Use /api/v1/moon/month when you need a full calendar month in one request. It accepts the same optional include flags as /phase and returns a days array, with one moon snapshot per calendar date. When you pass coordinates, each snapshot is taken at local midnight for that resolved timezone and each row is labeled with calendar_date. Enable include_sign_timeline=true to also receive Moon sign intervals with start/end times, durations, transition labels, and a separate ingresses event array for cleaner timeline rendering.

Access is limited to Entry and High plans.

See the dedicated Moon Phase Timeline docshttps://api.freeastroapi.com/api/v1/moon/month

curl -X GET "https://api.freeastroapi.com/api/v1/moon/month?year=2026&month=4&lat=48.8566&lon=2.3522&include_zodiac=true&include_traditional_moon=true&include_sign_timeline=true" \
 -H "x-api-key: YOUR_API_KEY"

{
  "year": 2026,
  "month": 4,
  "month_name": "April",
  "days_in_month": 30,
  "calendar_basis": "local",
  "calendar_timezone": "Europe/Paris",
  "sign_timeline": [
    {
      "sign": "Leo",
      "sign_id": "leo",
      "starts_at": "2026-03-31T22:00:00Z",
      "ends_at": "2026-04-02T11:14:00Z",
      "starts_at_local": "2026-04-01T00:00:00+02:00",
      "ends_at_local": "2026-04-02T13:14:00+02:00",
      "duration_hours": 37.23,
      "duration_minutes": 2234,
      "next_sign": "Virgo",
      "next_sign_id": "virgo",
      "label": "Leo -> Virgo",
      "continues_from_previous_month": true,
      "continues_to_next_month": false
    }
  ],
  "ingresses": [
    {
      "from_sign": "Leo",
      "from_sign_id": "leo",
      "to_sign": "Virgo",
      "to_sign_id": "virgo",
      "at": "2026-04-02T11:14:00Z",
      "at_local": "2026-04-02T13:14:00+02:00",
      "label": "Leo -> Virgo"
    }
  ],
  "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": "Scorpio",
        "sign_id": "scorpio",
        "degree": 18.2,
        "zodiac_type": "tropical"
      },
      "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
      },
      "next_phases": {
        "new_moon": "2026-04-17T12:22:51Z",
        "first_quarter": "2026-04-24T23:10:00Z",
        "full_moon": "2026-05-01T15:00:00Z",
        "last_quarter": "2026-04-10T04:17:02Z"
      },
      "eclipse": {
        "is_eclipse": false,
        "is_blood_moon": false
      }
    }
  ]
}

Query Parameters

Parameter	Type	Required	Description
date	string	No	ISO 8601 datetime (YYYY-MM-DDTHH:MM:SS) or 'now'. Default: now.
city	string	No	City name for coordinate lookup (alternative to lat/lon).
lat	float	No	Latitude for observer-specific data (Rise/Set). Default: None.
lon	float	No	Longitude for observer-specific data (Rise/Set). Default: None.
tz_str	string	No	Timezone string for naive datetime interpretation and local outputs. Default: AUTO.
include_zodiac	boolean	No	Include moon's zodiac sign (Tropical). Default: false.
include_rise_set	boolean	No	Include rise/set times (requires city or lat/lon). Default: false.
include_visuals	boolean	No	Include SVG visualization and shadow ratio. Default: false.
include_special	boolean	No	Detect special moon types: Supermoon, Blue Moon, Harvest Moon, etc. Default: false.
include_eclipse	boolean	No	Check for lunar eclipse within 15 days (returns is_blood_moon for total). Default: false.
include_forecast	boolean	No	Get days until next full/new moon, special moons, and eclipses. Default: false.
include_interpretation	boolean	No	Include psychological/spiritual interpretation based on moon sign, phase, and decan. Default: false.
include_traditional_moon	boolean	No	Include the traditional full moon name using the North American naming system, for the current full moon or the next upcoming full moon. Harvest Moon and Hunter's Moon are resolved by event logic. Default: false.
style_moon_color	string	No	Hex color for moon illumination in SVG. Default: #E0E0E0.
style_shadow_color	string	No	Hex color for moon shadow in SVG. Default: #1A1A1A.

Observer Location

The Moon Phase endpoint calculates the geocentric phase by default. Provide location via city or lat/lon for observer-specific data.

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.
Rise/Set times: Requires city or lat/lon.
Eclipse visibility: When location provided, returns visible_at_location (true/false).
Special moons: Supermoon, Blue Moon, Harvest Moon detection.
Blood Moon: is_blood_moon flag for total lunar eclipses.
Forecast: Days until next full/new moon, special moons, and eclipses.
Traditional full moon names: Optional North American labels like Wolf Moon or Pink Moon; Harvest Moon and Hunter's Moon are calculated by event timing.
SVG colors customizable via style_moon_color and style_shadow_color.

Traditional Moon Names Returned By The Endpoint

Wolf Moon, Snow Moon, Worm Moon, Pink Moon, Flower Moon, Strawberry Moon, Buck Moon, Sturgeon Moon, Harvest Moon, Hunter's Moon, Beaver Moon, and Cold Moon.

Visual Response Examples

The API returns a procedural SVG that adapts to the moon's exact phase angle. Below are examples of common phases with their corresponding phase_angle_deg.

New Moon

0°

Waxing Crescent

45°

First Quarter

90°

Waxing Gibbous

135°

Full Moon

180°

Waning Gibbous

225°

Last Quarter

270°

Waning Crescent

315°

Moon Interpretation (Optional)

Enable include_interpretation=true to add one psychological/spiritual interpretation block derived from Moon sign + phase + decan. This is disabled by default.

key: planet.moon.sign.scorpio.phase.waning_gibbous.decan.3

"In practical inner work, this placement emphasizes depth, loyalty, and transformative feeling states. With Moon in Scorpio, 3rd decan, expression often takes the form of compassionate surrender, while the pressure point is martyr dynamics..."

curl -X GET "https://api.freeastroapi.com/api/v1/moon/phase?date=2026-03-09&lat=48.866669&lon=2.33333&include_zodiac=true&include_interpretation=true" \
 -H "x-api-key: YOUR_API_KEY"

Sample Code

curl -X GET "https://api.freeastroapi.com/api/v1/moon/phase?date=2024-01-01T12:00:00&include_visuals=true&include_zodiac=true&include_interpretation=true&include_traditional_moon=true" \
 -H "x-api-key: YOUR_API_KEY"

Response Data

{
  // Always returned:
  "timestamp": "2024-01-01T12:00:00Z",
  "phase": {
    "name": "Waning Gibbous",
    "phase_angle_deg": 241.36,
    "illumination": 0.785,
    "age_days": 19.4,
    "distance_km": 384400,
    "is_waxing": false
  },
  "next_phases": {
    "new_moon": "2024-01-11T11:57:00Z",
    "first_quarter": "2024-01-24T13:28:00Z",
    "full_moon": "2024-01-25T17:54:00Z",
    "last_quarter": "2024-02-02T23:18:00Z"
  },
  
  // Only when include_zodiac=true:
  "zodiac": {
    "sign": "Leo",
    "sign_id": "leo",
    "degree": 15.42,
    "zodiac_type": "tropical"
  },
  
  // Only when include_visuals=true:
  "moon_visual": {
    "type": "svg",
    "svg": "<svg>...</svg>",
    "shadow_ratio": 0.215,
    "waxing": false
  },
  
  // Only when include_special=true:
  "special_moon": {
    "is_supermoon": true,
    "is_micromoon": false,
    "is_blue_moon": false,
    "is_black_moon": false,
    "is_harvest_moon": false,
    "is_hunter_moon": false,
    "labels": ["Supermoon"]
  },
  
  // Only when include_eclipse=true:
  "eclipse": {
    "is_eclipse": true,
    "is_blood_moon": true,
    "type": "total",
    "date": "2026-03-03T11:33:00Z",
    "visibility": "Americas, Europe, Africa",
    "days_from_query": 0.0
  },
  
  // Only when include_forecast=true:
  "forecast": {
    "days_until_full_moon": 24.8,
    "days_until_new_moon": 10.8,
    "next_special_moon": {
      "type": "Supermoon",
      "subtype": "new",
      "days_until": 99.5
    },
    "next_eclipse": {
      "type": "total",
      "is_blood_moon": true,
      "date": "2026-03-03T11:33:00Z",
      "days_until": 24.8
    }
  },

  // Only when include_interpretation=true:
  "interpretation": {
    "key": "planet.moon.sign.scorpio.phase.waning_gibbous.decan.3",
    "title": "Moon in Scorpio | Waning Gibbous | 3rd Decan",
    "body": "In practical inner work, this placement emphasizes depth, loyalty, and transformative feeling states. With Moon in Scorpio, 3rd decan, expression often takes the form of compassionate surrender, while the pressure point is martyr dynamics. During the Waning Gibbous, momentum sits in integration, so the useful move is to distill the lesson and share it with humility. One reliable devotional discipline is to release what is not yours to carry.",
    "tone": "improved",
    "tags": ["moon", "scorpio", "waning_gibbous", "decan_3", "water", "fixed", "psychological", "spiritual"]
  },

  // Only when include_traditional_moon=true:
  "traditional_moon": {
    "name": "Wolf Moon",
    "naming_system": "north_american_traditional",
    "month": "January",
    "applies_to_full_moon_at": "2024-01-25T17:54:00Z",
    "is_current_full_moon": false
  }
}

Next Steps

API Playground

Try the Moon Phase endpoint live

City Search

Resolve coordinates for any city