How to Get a Geodetic Chart from the API

POST /ephemeris/geodetic returns the geodetic chart of a place. It was added in API 4.3.0. Geodetic astrology maps the Earth onto the zodiac: a place's east longitude from Greenwich is the zodiac longitude of that place's Midheaven. The Ascendant and the 12 house cusps follow from the latitude with the ordinary house engine.

Add a moment and the endpoint also places the planets of that moment in the place's geodetic houses, and reports their conjunctions, squares and oppositions to the four geodetic angles.

---

When to use it

Use it when your product works with places rather than people: a map layer, a "what does this city sit under" lookup, or a comparison of a transit against a fixed location.

The chart belongs to the place. The geodetic angles and houses do not depend on any date. A date only enters when you ask for planets or contacts, or when you ask for a sidereal chart.

The request

curl -X POST https://api.openephemeris.com/ephemeris/geodetic \
  -H "X-API-Key: $OPENEPHEMERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 40.7128,
    "longitude": -74.006,
    "date_time": { "iso": "2026-10-24T12:00:00Z" },
    "include": ["planets", "contacts"],
    "orb_deg": 2
  }'

For the place alone, send only latitude and longitude. The response then has place, geodetic and houses, with no planets or contacts.

Fields:

• latitude and longitude (required): decimal degrees, east positive. A missing coordinate is a 422. It is never read as 0.
• date_time (optional): a moment, as { "iso": "..." } with its zone. Required when include has planets or contacts, and for zodiac_type sidereal.
• include (optional): planets, contacts, or both. contacts implies planets.
• orb_deg (optional, default 2): 0.1 to 10 degrees. Only allowed with contacts.
• bodies (optional): up to 16 body names. The default is Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto and the Mean Node. Only allowed with planets or contacts. An unknown name is a 422, never silently dropped.
• house_system (optional): P (default), K, O, R, C, E or W.
• zodiac_type (optional): tropical (default) or sidereal.
• ayanamsa (optional): lahiri, fagan_bradley, krishnamurti, raman or yukteshwar. Only allowed with sidereal.
• anchor and anchor_offset_deg (optional): greenwich is the only named anchor. anchor_offset_deg (-180 to 180) is added to the longitude to move the anchor.
• format (optional): json (default) or llm. With llm the planet and contact rows move into metadata as fixed-width arrays.

The response

This is a real response to the request above, trimmed: 3 of the 11 bodies are shown, only the first 2 of 4 contacts are shown, some metadata keys are omitted, and most numbers are rounded to four decimals for display.

{
  "success": true,
  "data": {
    "place": { "latitude": 40.7128, "longitude": -74.006 },
    "geodetic": {
      "anchor": "greenwich",
      "anchor_offset_deg": 0,
      "mc": { "longitude": 285.994, "sign": "Capricorn", "sign_longitude": 15.994 },
      "ic": { "longitude": 105.994, "sign": "Cancer", "sign_longitude": 15.994 },
      "asc": { "longitude": 29.2054, "sign": "Aries", "sign_longitude": 29.2054 },
      "dsc": { "longitude": 209.2054, "sign": "Libra", "sign_longitude": 29.2054 },
      "ramc": 287.3494,
      "zone": { "sign": "Capricorn", "band_start_longitude": 270, "band_end_longitude": 300 }
    },
    "houses": {
      "system": "P",
      "effective_system": "P",
      "cusps": [29.2054, 61.9975, 85.0594, 105.994, 129.5429, 161.8168, 209.2054, 241.9975, 265.0594, 285.994, 309.5429, 341.8168]
    },
    "planets": {
      "Sun": { "longitude": 211.0936, "sign": "Scorpio", "sign_longitude": 1.0936, "house_number": 7 },
      "Venus": { "longitude": 210.5397, "sign": "Scorpio", "sign_longitude": 0.5397, "house_number": 7 },
      "North Node (Mean)": { "longitude": 326.4684, "sign": "Aquarius", "sign_longitude": 26.4684, "house_number": 11 }
    },
    "contacts": [
      { "body": "Sun", "angle": "asc", "aspect": "opposition", "orb": 1.8881 },
      { "body": "Sun", "angle": "dsc", "aspect": "conjunction", "orb": 1.8881 }
    ]
  },
  "metadata": {
    "tradition": "geodetic_equivalents_greenwich",
    "zodiac_type": "tropical",
    "obliquity_deg": 23.439279444444445,
    "obliquity_basis": "mean_j2000",
    "mc_basis": "ecliptic_longitude",
    "resolved_utc": "2026-10-24T12:00:00Z",
    "julian_day": 2461338
  }
}

How to read it:

• New York at 74.006 degrees west is 285.994 degrees east of Greenwich. That is the geodetic Midheaven, 15.994 degrees of Capricorn. geodetic.zone is the 30-degree band of the zodiac that holds the place: every place between those two meridians has its geodetic Midheaven in that sign.
• houses.cusps has 12 values, houses 1 to 12.
• planets is keyed by body name. Each planet is a geocentric ecliptic longitude in the zodiac you asked for, with the geodetic house that holds it.
• contacts lists conjunctions, squares and oppositions between a planet and mc, ic, asc or dsc, within orb_deg. orb is the distance from exact, in degrees.
• ramc is the right ascension of the meridian. It is an equatorial angle in the tropical frame, whatever zodiac_type says. It is not a zodiac degree.

Cost

1 credit per call, on every plan including the free Explorer tier. The price does not change with include.

Gotchas

The doctrine is a convention, and the response says which one it used. The geodetic mapping rests on secondary sources, and the primary text was not available. The Greenwich anchor is a convention. The Midheaven is the ecliptic degree, not the right ascension. The response states its choices: the anchor and offset, the fixed mean J2000 obliquity (obliquity_basis is mean_j2000, so the same place always gives the same answer), the house system and the zodiac. If you need a different anchor, send anchor_offset_deg.

A planet on one angle appears twice. The Ascendant and Descendant are opposite points. A planet conjunct the Descendant is also opposite the Ascendant, so it appears in contacts once for each. In the sample, the Sun is at orb 1.8881 to both asc (opposition) and dsc (conjunction). Filter on angle if you want one row per planet.

date_time needs a zone. A clock time without a zone, in the string or as a suffix such as Z, is rejected as ambiguous. A date alone resolves to 12:00 UTC. See A Timestamp Is Not a Moment.

Sidereal is the tropical chart shown in the sidereal zodiac. Every longitude, cusp and sign is shifted by the ayanamsa, so Greenwich reads about 6 degrees of Pisces rather than 0 degrees of Aries, and the shift grows with the date. That is why sidereal needs date_time. The response says so in metadata.sidereal_basis. If you want the place fixed to the sidereal zodiac instead, send anchor_offset_deg equal to the ayanamsa at that date.

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.

Options that do not apply are refused, not ignored. orb_deg without contacts, bodies without planets or contacts, ayanamsa without sidereal, an empty bodies list, and an unsupported anchor are each a 422. Body names look like the keys in the response, for example Sun, Saturn and North Node (Mean).