How to Cast an Ingress or Lunation Chart with the API

POST /mundane/chart casts a chart for the exact instant of an event, at a place you choose. It was added in API 4.3.0. Two event types are supported: the Sun entering a sign (for the cardinal signs, an equinox or solstice), and the next New or Full Moon after a date.

The endpoint solves the instant, tells you how close the solved geometry is to the definition, and casts a geocentric, tropical chart for that instant. For an ingress it adds the traditional validity span and the lord-of-the-year candidates as separate, labelled facts.

---

When to use it

Use it when you need the chart of a recurring sky event as data: a seasonal ingress chart for a capital, the chart of the next Full Moon for a city, or the raw material for your own mundane reading layer.

The place is yours to choose. No capital or city is assumed, and a missing coordinate is a 422.

The request

curl -X POST https://api.openephemeris.com/mundane/chart \
  -H "X-API-Key: $OPENEPHEMERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": { "type": "sign_ingress", "sign": "aries", "year": 2027 },
    "latitude": 38.9072,
    "longitude": -77.0369,
    "house_system": "P"
  }'

Fields:

• event (required): the moment to cast. Its type is sign_ingress or lunation. Fields that belong to the other type are refused, and nothing defaults to now.
  • For sign_ingress: sign (aries through pisces) and year (1551 to 2649, the calendar year of the ingress by UTC date) are required. body is optional and can only be sun. A request for the Moon is refused: use lunation for New and Full Moons, or GET /ephemeris/moon/ingresses for the Moon's sign changes.
  • For lunation: kind (new_moon or full_moon) and after are required. after is a date and time with its zone, for example { "iso": "2026-11-01T00:00:00Z" }. The chart is for the first lunation at or after that instant. A lunation exactly at the instant is returned, so to step to the next one, add a minute.
• latitude and longitude (required): the place the chart is cast for. Decimal degrees, east positive.
• house_system (optional): P (default), K, O, R, C, E or W.
• format (optional): json (default) or llm. With llm the body rows move into metadata as compact rows.

The response

This is a real response to the request above, trimmed: 2 of the 11 bodies, 2 of the 12 house rulers, and the cusps beyond the first four are omitted, and most numbers are rounded for display.

{
  "success": true,
  "event": {
    "type": "sign_ingress",
    "body": "sun",
    "sign": "aries",
    "target_longitude": 0,
    "datetime_utc": "2027-03-20T20:24:41.032133102Z",
    "julian_day": 2461485.350474909,
    "solved_longitude": 359.9999999914481,
    "residual_arcsec": 0.00003078712325077504
  },
  "chart": {
    "angles": {
      "asc": { "longitude": 145.7136, "sign": "Leo", "sign_longitude": 25.7136 },
      "mc": { "longitude": 49.7256, "sign": "Taurus", "sign_longitude": 19.7256 },
      "dsc": { "longitude": 325.7136, "sign": "Aquarius", "sign_longitude": 25.7136 },
      "ic": { "longitude": 229.7256, "sign": "Scorpio", "sign_longitude": 19.7256 }
    },
    "houses": {
      "system": "P",
      "effective_system": "P",
      "cusps": [145.7136, 168.7691, 196.8079, 229.7256]
    },
    "bodies": {
      "Sun": { "longitude": 359.9999999914481, "sign": "Pisces", "sign_longitude": 29.9999999914, "house_number": 8, "speed": 0.9933, "retrograde": false },
      "Moon": { "longitude": 158.8692, "sign": "Virgo", "sign_longitude": 8.8692, "house_number": 1, "speed": 14.3564, "retrograde": false }
    },
    "sect": { "is_day_chart": true, "basis": "sun_above_horizon" }
  },
  "mundane": {
    "house_rulers": [
      { "house": 1, "sign": "Leo", "ruler": "Sun", "ruler_house": 8 },
      { "house": 2, "sign": "Virgo", "ruler": "Mercury", "ruler_house": 7 }
    ],
    "validity": {
      "basis": "ascendant_modality",
      "modality": "fixed",
      "months": 12,
      "tradition": "skyscript_ingress_article",
      "note": "traditional guideline, not a prediction; one other source reverses the fixed and mutable spans"
    },
    "lord_of_year_candidates": [
      { "method": "ascendant_ruler", "planet": "Sun", "house": 8, "dignity_total": 0, "source": "ruler of the Ascendant sign (Skyscript ingress article)" },
      { "method": "mc_ruler", "planet": "Venus", "house": 6, "dignity_total": 0, "source": "ruler of the Midheaven sign" },
      {
        "method": "almuten_ascendant",
        "planets": ["Sun"],
        "points": { "Sun": 8, "Mars": 3, "Jupiter": 0, "Venus": 0, "Mercury": 0, "Moon": 0, "Saturn": 0 },
        "source": "essential-dignity points of the seven classical planets at the Ascendant degree"
      }
    ]
  },
  "metadata": {
    "algorithm_version": "mundane-1.0.0",
    "zodiac": "tropical",
    "center": "geocentric",
    "house_system": "P",
    "latitude": 38.9072,
    "longitude": -77.0369,
    "time_scale": "UT",
    "obliquity": "true_of_date"
  }
}

How to read it:

• event.datetime_utc is the solved instant. event.residual_arcsec is how far the solved geometry is from the definition, in arcseconds. Here it is about 0.00003. For a lunation, the event carries kind, sun_longitude and moon_longitude in place of the ingress fields.
• chart.bodies holds the Sun to Pluto and the Mean North Node, keyed by name, with house_number, speed (degrees per day) and retrograde. The Mean North Node is always flagged retrograde.
• chart.sect.is_day_chart is true when the Sun is above the horizon, which is the geometry between the Descendant and the Ascendant going up through the Midheaven. sect.basis says sun_above_horizon.
• mundane.house_rulers has one row per house: its sign, the classical ruler, and the house that ruler occupies.

Cost

2 credits per call, on every plan including the free Explorer tier.

Gotchas

At an ingress, the Sun sits on a sign boundary, and the Sun's own row can say the old sign. The solver lands within event.residual_arcsec of the target, and that can be on either side. In the sample, the Sun is at 359.99999999 degrees, so chart.bodies.Sun.sign reads Pisces for an Aries ingress. Take the ingress sign from event.sign, not from the Sun's row. Values derived from the Sun's longitude, such as the dignity total of a Sun candidate, read that same unrounded longitude.

Validity and lord-of-the-year candidates exist for the four cardinal ingresses only. That means Aries, Cancer, Libra and Capricorn. For any other sign, and for lunations, the chart is still cast but mundane holds only house_rulers. For a non-cardinal ingress, metadata.warnings says why. These traditional readings belong to the four seasonal ingresses.

No candidate is called the lord of the year. The sources disagree, so the response lists three labelled candidates (ascendant_ruler, mc_ruler, almuten_ascendant) with their sources. Choosing between them is your decision, and your product should say which method it used.

Validity is a guideline, and the note says so. validity.months comes from the modality of the Ascendant sign. The note field records that one other source reverses the fixed and mutable spans.

The lunation after date needs a zone. A clock time without a zone is rejected as ambiguous. A date alone resolves to 12:00 UTC. See A Timestamp Is Not a Moment. The solved instant must also fall inside the supported range, 1550-01-01 to 2650-01-22.

datetime_utc has nine fractional digits. A parser that accepts only milliseconds or microseconds may reject or truncate it.

Polar latitudes replace the house system. A quadrant house system inside the polar circle is replaced by Porphyry. houses.effective_system is then O, and metadata.warnings says so.

What is not in this version. Eclipse and great-conjunction events, overlay on a founding chart, and the Moon's applying aspects.