Lunar Occultations — When the Moon Passes in Front of a Planet

An occultation is exactly what it sounds like: the Moon passing directly in front of a planet, blocking it from view for a real observer at a specific location. Rare enough to be notable, well-defined enough to compute precisely — a genuine differentiator most astrology APIs don't offer at all.

What the endpoint returns

Pass a date, location, and target planet — the endpoint finds the next occultation of that planet by the Moon, visible from that exact location, with the classical four contact points: first contact (the Moon's edge touches the planet), second (full occultation begins), third (occultation ends), fourth (the Moon's trailing edge clears the planet).

GET /api/v1/panchang/occultations?date=28/08/2026&lat=12.98&lon=77.59&planet=venus&api_key=...

{
  "status": 200,
  "response": {
    "next_occultation": {
      "planet": "venus",
      "found": true,
      "visible_at_location": true,
      "first_contact": { "utc": "11:54:03", "unix": 1789386843 },
      "second_contact": { "utc": "11:56:18", "unix": 1789386978 },
      "third_contact": { "utc": "13:11:56", "unix": 1789391516 },
      "fourth_contact": { "utc": "13:13:52", "unix": 1789391632 }
    }
  }
}

Verified against a real event

Before shipping, this endpoint's output was cross-checked against real, independently-published occultation data — a genuine Moon-occults-Venus event visible from Southeast Asia on September 14, 2026. The endpoint returned the exact same date and a location consistent with the correct visibility region, confirmed independently of the internal calculation itself.

Supported planets

planetaccepts mercury, venus, mars, jupiter, saturn, uranus, neptune, or pluto — defaulting to mercury if omitted. Moon-occults-planet is the well-defined case this endpoint covers; general fixed-star or planet-versus-planet occultations are a substantially larger search space and aren't included here.

Who this is for

Astronomy-adjacent astrology apps, event/timing tools that track notable celestial events, and anyone building on the observational-astronomy side of a chart product. Available on Starter plan and above.