Everything you need to build with Open Ephemeris, in one clear place.

Basic health check for the entire API service.

curl -X GET "https://api.openephemeris.com/health"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Health check that runs internal calculation self-tests (nakshatra, HD gates, Venus phase, aspects, harmonics, profections, firdaria, zodiacal releasing) plus one true external dependency check (the loaded ephemeris engine).

curl -X GET "https://api.openephemeris.com/health/detailed"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Welcome endpoint with API information and links to documentation.

curl -X GET "https://api.openephemeris.com/"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Get list of supported astrological house systems

curl -X GET "https://api.openephemeris.com/ephemeris/house-systems"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Get JSON schema for natal chart request format

curl -X GET "https://api.openephemeris.com/ephemeris/schemas/natal-request"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Get JSON schema for natal chart response format

curl -X GET "https://api.openephemeris.com/ephemeris/schemas/natal-response"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Get canonical metadata lookups used by calculations (sign elements/modalities, supported enums like dignity systems, house systems, node sources, etc.).

curl -X GET "https://api.openephemeris.com/ephemeris/supported-metadata"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Get list of supported celestial objects in calculations

curl -X GET "https://api.openephemeris.com/ephemeris/supported-objects"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Return the OpenAPI schema for automated client generation. Used by frontend build processes to generate type-safe API clients. Authentication is NOT required for this discovery endpoint to facilitate automated toolchain integration. Returns: OpenAPI 3.0 schema (JSON)

curl -X GET "https://api.openephemeris.com/meta/openapi.json"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Return current API version and contract hash for cache invalidation. Frontend CI uses this to detect schema changes and trigger client regeneration. Authentication is not required for this discovery endpoint.

curl -X GET "https://api.openephemeris.com/meta/version"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Mechanical endpoint returning Asc/MC/Desc/IC plus Vertex and the Equatorial Ascendant/Descendant (Ebertin EQA/EQD). The equatorial ascendant is also returned under the long-published key east_point, which is a synonym for the same point, not a separate one.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "house_system": "P",
  "latitude": 40.7128,
  "longitude": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/angles-points"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "house_system": "P",
  "latitude": 40.7128,
  "longitude": -74.006
}'

Responses

Calculate antiscia (mirror points across the Cancer/Capricorn solstice axis) and contra-antiscia for a set of planetary longitudes. Detects hidden conjunctions where one planet's antiscion falls on another planet's natal position. Central to Hellenistic and traditional Western astrology. 🤖 AI-optimized output available — add format=llm to reduce payload ~60%.

Parameters

{
  "bodies": [
    {
      "id": 0,
      "longitude": 15
    },
    {
      "id": 1,
      "longitude": 165
    },
    {
      "id": 4,
      "longitude": 225
    }
  ],
  "orb": 2
}

curl -X POST "https://api.openephemeris.com/ephemeris/antiscia"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "bodies": [
    {
      "id": 0,
      "longitude": 15
    },
    {
      "id": 1,
      "longitude": 165
    },
    {
      "id": 4,
      "longitude": 225
    }
  ],
  "orb": 2
}'

Responses

Lightweight endpoint for calculating aspects between two celestial longitudes. Supports filtering by aspect type and custom orb limits.

Parameters

{
  "aspect_types": [
    "conjunction",
    "opposition",
    "square",
    "trine"
  ],
  "longitude1": 120,
  "longitude2": 180,
  "max_orb": 6
}

curl -X POST "https://api.openephemeris.com/ephemeris/aspect-check"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "aspect_types": [
    "conjunction",
    "opposition",
    "square",
    "trine"
  ],
  "longitude1": 120,
  "longitude2": 180,
  "max_orb": 6
}'

Responses

Analyse ecliptic coordinates to compute equatorial declinations, detect out-of-bounds (OOB) planets, and find declination aspects (parallels and contraparallels). A planet is out of bounds when its declination exceeds the obliquity of the ecliptic (~23.44°). OOB planets operate outside the Sun's framework and are interpreted as wildcards in contemporary astrology. The Moon is the most frequently OOB body. Parallels (same declination, same hemisphere) behave like conjunctions; contraparallels (equal but opposite declination) behave like oppositions. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris kernel required.

Parameters

{
  "bodies": [
    {
      "id": 1,
      "latitude": 1,
      "longitude": 1
    }
  ],
  "obliquity": 23.4393,
  "parallel_orb": 1
}

curl -X POST "https://api.openephemeris.com/ephemeris/declinations"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "bodies": [
    {
      "id": 1,
      "latitude": 1,
      "longitude": 1
    }
  ],
  "obliquity": 23.4393,
  "parallel_orb": 1
}'

Responses

Mechanical endpoint returning essential dignity scores for Sun..Pluto.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "latitude": 40.7128,
  "longitude": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/dignities"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "latitude": 40.7128,
  "longitude": -74.006
}'

Responses

Build a dispositor tree from a set of planetary sign placements. Each planet is "disposed" by the ruler of the sign it occupies. The algorithm walks these rulership chains to identify final dispositors (planets ruling their own sign) and mutual receptions (pairs disposing each other). No ephemeris kernel required — pass in pre-computed sign placements. Signs are 0-based in the API (0=Aries … 11=Pisces) and converted internally. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

Parameters

{
  "planets": [
    {
      "planet_id": 1,
      "sign": 1
    }
  ]
}

curl -X POST "https://api.openephemeris.com/ephemeris/dispositor-tree"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "planets": [
    {
      "planet_id": 1,
      "sign": 1
    }
  ]
}'

Responses

Calculates draconic chart with True Node as 0 Aries.

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "body_ids": [
    1
  ],
  "format": "json",
  "include_visual": false,
  "visual_config": {
    "format": "svg",
    "layout": "graph",
    "size": 800,
    "theme": "light"
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/draconic"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "body_ids": [
    1
  ],
  "format": "json",
  "include_visual": false,
  "visual_config": {
    "format": "svg",
    "layout": "graph",
    "size": 800,
    "theme": "light"
  }
}'

Responses

Calculate positions for fixed stars and galactic reference points at a specific moment. Supports individual names, predefined groups (royal_stars, behenian, ptolemaic, 15_fixed_stars, galactic), and magnitude filtering. Discover the current group list at GET /catalogs/fixed-stars/groups. Returns ecliptic coordinates, proper motion, and metadata for each entry. 🤖 AI-optimized output available — add format=llm to reduce payload ~60%.

Parameters

{
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "latitude": 32.7767,
  "longitude": -96.797,
  "orb": 1,
  "star_names": [
    "Regulus",
    "Spica",
    "Aldebaran"
  ]
}

curl -X POST "https://api.openephemeris.com/ephemeris/fixed-stars"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "latitude": 32.7767,
  "longitude": -96.797,
  "orb": 1,
  "star_names": [
    "Regulus",
    "Spica",
    "Aldebaran"
  ]
}'

Responses

The geodetic Midheaven, Ascendant, houses and sign zone of a place, and optionally the planets of a moment placed in those houses. A place's east longitude from Greenwich is the zodiac longitude of its Midheaven (74 degrees W is 286 degrees, 16 Capricorn); the Ascendant and the 12 cusps follow from the latitude with the standard house engine, at a fixed mean obliquity (IAU 2006, J2000) so the same place always gives the same answer. Add date_time with include planets or contacts to read a moment against the place: planets in the geodetic houses and their conjunctions, squares and oppositions to the four angles. Honest limits: the doctrine rests on secondary sources, the Greenwich anchor is a convention (anchor_offset_deg moves it), and the Midheaven is the ecliptic degree, not the right ascension. A quadrant house system inside the polar circle is replaced by Porphyry and the response says so. A sidereal chart is the tropical geodetic chart shown in the sidereal zodiac, like every other chart on this API. Pricing: 1 credit per call.

{
  "date_time": {
    "iso": "2021-05-10T12:00:00+03:00"
  },
  "house_system": "P",
  "include": [
    "planets",
    "contacts"
  ],
  "latitude": 31.7683,
  "longitude": 35.2137,
  "orb_deg": 2
}

curl -X POST "https://api.openephemeris.com/ephemeris/geodetic"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2021-05-10T12:00:00+03:00"
  },
  "house_system": "P",
  "include": [
    "planets",
    "contacts"
  ],
  "latitude": 31.7683,
  "longitude": 35.2137,
  "orb_deg": 2
}'

Responses

Calculate harmonic chart positions by multiplying natal longitudes by a harmonic number N and reducing modulo 360°. Finds conjunctions in the harmonic space to reveal hidden aspect patterns. Harmonic analysis is the mathematical backbone of aspect theory: the 5th harmonic unfolds quintiles, the 7th reveals septiles, the 9th produces the Vedic navamsa. Higher harmonics expose increasingly subtle geometric relationships invisible in a standard chart wheel. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

Parameters

{
  "bodies": [
    {
      "id": 1,
      "longitude": 1
    }
  ],
  "harmonic": 1,
  "orb": 8
}

curl -X POST "https://api.openephemeris.com/ephemeris/harmonics"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "bodies": [
    {
      "id": 1,
      "longitude": 1
    }
  ],
  "harmonic": 1,
  "orb": 8
}'

Responses

Calculate Hermetic lots (Fortune Suite + optional/legacy) for a given datetime and location. Returns normalized lot positions with traditional source references, formulas, and keywords. Includes sect determination (diurnal/nocturnal) and house placements. Follows standalone pattern: direct Julian Day calculation without chart context. Supports format=json|llm via query params.

Parameters

{
  "date_time": {
    "iso": "1985-06-15T14:30:00Z"
  },
  "include_legacy": false,
  "include_optional": false,
  "latitude": 40.7128,
  "longitude": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/hermetic-lots"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "1985-06-15T14:30:00Z"
  },
  "include_legacy": false,
  "include_optional": false,
  "latitude": 40.7128,
  "longitude": -74.006
}'

Responses

Mechanical endpoint returning house cusps for up to 5 house systems.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "house_systems": [
    "P",
    "W"
  ],
  "latitude": 40.7128,
  "longitude": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/house-cusps"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "house_systems": [
    "P",
    "W"
  ],
  "latitude": 40.7128,
  "longitude": -74.006
}'

Responses

Calculate the current lunar phase based on Sun-Moon elongation. Returns phase name/angle, illumination percentage, and lunation metadata (New Moon/Full Moon dates, day of lunation, void-of-course status). 🤖 AI-optimized output available — add format=llm to reduce payload ~50%.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/lunar-phase"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  }
}'

Responses

Calculate zodiacal midpoints from planetary longitudes, detecting conjunctions and oppositions to sensitive points. Supports sort-by-type, tree grouping, and dial-degree formatting. 🤖 AI-optimized output available — add format=llm to reduce payload ~65%. Uranian: send uranian for Hamburg-style output on a 360, 90, 45 or 22.5 degree dial: the dial sort, a focal midpoint tree and planetary pictures (A/B = C and A/B = C/D), optionally with the eight transneptunian points and the Aries Point. No extra credit. The orb is measured between the two midpoints; the equation residual is twice that, and both are returned.

Parameters

{
  "arc_type": "short",
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "include_angles": true,
  "include_occupied": false,
  "latitude": 40.7128,
  "longitude": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/midpoints"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "arc_type": "short",
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "include_angles": true,
  "include_occupied": false,
  "latitude": 40.7128,
  "longitude": -74.006
}'

Responses

When can the new crescent Moon be seen from here? For the New Moon (geocentric conjunction) on or after the requested date, and each of the three evenings that start with its local date: sunset, moonset, the lag, Yallop's best time (sunset + 4/9 lag), the Moon's age, ARCL, ARCV, DAZ and the crescent width, then Yallop's q-test (NAO Technical Note 69, zones A-F) and Odeh's V criterion (Experimental Astronomy 18, 2004, zones A-D). An evening on which the Moon sets before the Sun, or the topocentric conjunction is after sunset, is reported as not possible. No evening exists in polar day or night. IMPORTANT: this is an astronomical prediction of whether the crescent can be seen. It is not a religious ruling and does not decide the start of an Islamic month: communities and authorities follow their own rules (local or global sighting, calculation, or a published calendar).

Parameters

curl -X GET "https://api.openephemeris.com/ephemeris/moon/crescent-visibility?date=2026-02-17&latitude=-90&longitude=-180"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Calculate a comprehensive natal chart with optional enhanced features. Features - Core: Planetary positions, houses, angles. - Enhanced: Aspects, patterns, midpoints, harmonics, fixed stars, Arabic parts, dignities. - Output modes: full (default), simple (core only), llm (AI-optimized). Lunar nodes - The default roster returns both North Nodes, each labelled: North Node (Mean) (mean-node polynomial) and North Node (True) (the Moon's osculating ascending node, from its DE440 state vector in the true ecliptic of date; the equivalent of Swiss Ephemeris SE_TRUE_NODE). The true_node body slug always selects the True (osculating) node, never the Mean node. South Nodes are the matching North Node + 180°. - calculation_metadata.lunar_nodes states the method used for each node and apogee in the response, and calculation_metadata.node_source names the node mode in effect. Both are returned on every tier. Input Flexibility - Coordinates: decimal degrees, DMS strings, or component objects - DateTime: ISO-8601 strings, Julian Day, or component objects - Timezone: IANA names, UTC offsets, or auto-detection Legacy request fields (e.g., custom orb tables) are safely ignored under the simplified contract but remain accepted for compatibility. 🤖 AI-optimized output available — add format=llm to reduce payload ~75%.

Parameters

{
  "configuration": {
    "ayanamsa": "lahiri",
    "coordinate_frame": "equatorial",
    "coordinate_system": "topocentric",
    "house_system": "W",
    "object_set": "asteroids_major",
    "zodiac_type": "sidereal"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1985-03-20T08:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 37.7749
      },
      "longitude": {
        "decimal": -122.4194
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Jane Smith"
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/natal-chart"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "configuration": {
    "ayanamsa": "lahiri",
    "coordinate_frame": "equatorial",
    "coordinate_system": "topocentric",
    "house_system": "W",
    "object_set": "asteroids_major",
    "zodiac_type": "sidereal"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1985-03-20T08:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 37.7749
      },
      "longitude": {
        "decimal": -122.4194
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Jane Smith"
  }
}'

Responses

Compute multiple natal charts in a single request with shared guardrails. 🤖 AI-optimized output available — add format=llm to reduce payload ~80%.

Parameters

{
  "format": "json",
  "items": [
    {
      "configuration": {
        "coordinate_frame": "ecliptic",
        "coordinate_system": "geocentric",
        "house_system": "W",
        "object_set": "modern_plus_chiron",
        "zodiac_type": "tropical"
      },
      "subject": {
        "birth_datetime": {
          "iso": "1992-01-10T04:15:00"
        },
        "birth_location": {
          "latitude": {
            "decimal": 40
          },
          "longitude": {
            "decimal": -74
          },
          "timezone": {
            "iana_name": "America/New_York"
          }
        },
        "name": "Batch Subject 1"
      }
    },
    {
      "subject": {
        "birth_datetime": {
          "iso": "1988-07-22T19:45:00"
        },
        "birth_location": {
          "latitude": {
            "decimal": 34.0522
          },
          "longitude": {
            "decimal": -118.2437
          },
          "timezone": {
            "iana_name": "America/Los_Angeles"
          }
        },
        "name": "Batch Subject 2"
      }
    }
  ],
  "limits": {
    "max_subjects": 10
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/natal/batch"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "format": "json",
  "items": [
    {
      "configuration": {
        "coordinate_frame": "ecliptic",
        "coordinate_system": "geocentric",
        "house_system": "W",
        "object_set": "modern_plus_chiron",
        "zodiac_type": "tropical"
      },
      "subject": {
        "birth_datetime": {
          "iso": "1992-01-10T04:15:00"
        },
        "birth_location": {
          "latitude": {
            "decimal": 40
          },
          "longitude": {
            "decimal": -74
          },
          "timezone": {
            "iana_name": "America/New_York"
          }
        },
        "name": "Batch Subject 1"
      }
    },
    {
      "subject": {
        "birth_datetime": {
          "iso": "1988-07-22T19:45:00"
        },
        "birth_location": {
          "latitude": {
            "decimal": 34.0522
          },
          "longitude": {
            "decimal": -118.2437
          },
          "timezone": {
            "iana_name": "America/Los_Angeles"
          }
        },
        "name": "Batch Subject 2"
      }
    }
  ],
  "limits": {
    "max_subjects": 10
  }
}'

Responses

Lightweight endpoint for retrieving a single planet's position at a specific time. Supports both geocentric (default) and topocentric (with latitude/longitude) calculations.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "latitude": 40.7128,
  "longitude": -74.006,
  "planet_id": 0
}

curl -X POST "https://api.openephemeris.com/ephemeris/planet-position"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "latitude": 40.7128,
  "longitude": -74.006,
  "planet_id": 0
}'

Responses

Calculates the prenatal new and full moon for a subject.

{
  "birth_datetime": "string",
  "latitude": 1,
  "longitude": 1,
  "format": "json",
  "house_system": "string",
  "include": [
    "string"
  ],
  "max_age_years": 100
}

curl -X POST "https://api.openephemeris.com/ephemeris/prenatal-lunation"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": "string",
  "latitude": 1,
  "longitude": 1,
  "format": "json",
  "house_system": "string",
  "include": [
    "string"
  ],
  "max_age_years": 100
}'

Responses

Return angles, house cusps, and planet house changes for a relocated chart. 🤖 AI-optimized output available — add format=llm to reduce payload ~55%.

Parameters

{
  "house_system": "P",
  "natal": {
    "subject": {
      "birth_datetime": {
        "iso": "1990-01-01T12:00:00Z"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Relocation Client"
    }
  },
  "relocation_lat": 40.7128,
  "relocation_lon": -74.006
}

curl -X POST "https://api.openephemeris.com/ephemeris/relocation"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "house_system": "P",
  "natal": {
    "subject": {
      "birth_datetime": {
        "iso": "1990-01-01T12:00:00Z"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Relocation Client"
    }
  },
  "relocation_lat": 40.7128,
  "relocation_lon": -74.006
}'

Responses

{
  "angles": {
    "asc": {
      "longitude": 123.45,
      "sign": "Leo",
      "sign_longitude": 3.45,
      "sign_symbol": "Leo"
    },
    "dsc": {
      "longitude": 303.45,
      "sign": "Aquarius",
      "sign_longitude": 3.45,
      "sign_symbol": "Aquarius"
    },
    "ic": {
      "longitude": 30.1,
      "sign": "Taurus",
      "sign_longitude": 0.1,
      "sign_symbol": "Taurus"
    },
    "mc": {
      "longitude": 210.1,
      "sign": "Scorpio",
      "sign_longitude": 0.1,
      "sign_symbol": "Scorpio"
    }
  },
  "calculation_metadata": {
    "coordinate_system": "geocentric",
    "ephemeris_source": "SuperNOVAS / Calceph",
    "zodiac_type": "tropical"
  },
  "houses": [
    {
      "index": 1,
      "longitude": 123.45,
      "sign": "Leo",
      "sign_longitude": 3.45,
      "size": 30
    },
    {
      "index": 2,
      "longitude": 153.45,
      "sign": "Virgo",
      "sign_longitude": 3.45,
      "size": 28.7
    }
  ],
  "metadata": {
    "calculation_source": "SuperNOVAS / Calceph",
    "house_system": "P",
    "natal_house_system": "P",
    "observer_location": {
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "reference_frame": "geocentric_ecliptic_J2000",
    "requested_house_system": "P",
    "time_system": "UTC",
    "topocentric_flag": false
  },
  "planet_house_changes": [
    {
      "body": "Sun",
      "from_house": 10,
      "to_house": 9
    },
    {
      "body": "Venus",
      "from_house": 7,
      "to_house": 8
    }
  ],
  "success": true,
  "summary": {
    "changed_houses": 12,
    "changed_planets": 2,
    "notes": "Relocated using Placidus; planetary longitudes unchanged."
  }
}

Lightweight endpoint for determining whether a planet is retrograde at a specific time. Returns motion type (direct/retrograde/stationary) and speed data.

Parameters

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "planet_id": 2
}

curl -X POST "https://api.openephemeris.com/ephemeris/retrograde-status"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "planet_id": 2
}'

Responses

What is up tonight from one place: every body's rise, set and upper and lower culmination for the date (Sun, Moon, Mercury to Pluto, each with its own horizon: refraction, the Sun's and Moon's semi-diameter, the dip for elev), and for the night that follows (sunset to the next sunrise) which naked-eye planets can be seen and when, their magnitude and elongation, close approaches between the Moon and the planets, and the Moon hiding a planet or a bright star. Positions are topocentric throughout.

Parameters

curl -X GET "https://api.openephemeris.com/ephemeris/sky-tonight?date=2026-03-20&latitude=-90&longitude=-180"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Which parts of a chart survive an uncertain birth time. For a stated birth moment, a place and a window, returns every boundary crossed inside the window (Ascendant and Midheaven sign changes, house cusp signs, each planet's sign and house), a per-fact verdict of stable, fragile or unstable, and the nearest boundary just outside the window. Angles and cusps are solved in closed form and certified against the production house function a second either side; planets use the ephemeris at the window ends with a few real position calls per root, about 20 to 50 in all. Quadrant house systems inside the polar circle fall back to Porphyry and the response says so. This answers "how much does this chart depend on the minute?" for an agent or a person. It does not estimate the true birth time. Pricing: 2 credits per call.

{
  "include": [
    "angles",
    "houses",
    "planets"
  ],
  "subject": {
    "birth_datetime": {
      "iso": "1990-04-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 41.8781
      },
      "longitude": {
        "decimal": -87.6298
      },
      "timezone": {
        "iana_name": "America/Chicago"
      }
    }
  },
  "window": {
    "minutes_after": 30,
    "minutes_before": 30
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/time-sensitivity"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "include": [
    "angles",
    "houses",
    "planets"
  ],
  "subject": {
    "birth_datetime": {
      "iso": "1990-04-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 41.8781
      },
      "longitude": {
        "decimal": -87.6298
      },
      "timezone": {
        "iana_name": "America/Chicago"
      }
    }
  },
  "window": {
    "minutes_after": 30,
    "minutes_before": 30
  }
}'

Responses

Return progressed positions, aspects, and metadata for a subject. Supports Secondary (Naibod), Tertiary (I), Minor, and Solar Arc methods. 🤖 AI-optimized output available — add ormat=llm to reduce payload ~70%.

Parameters

{
  "configuration": {
    "house_system": "P",
    "object_set": "asteroids_major",
    "zodiac_type": "tropical"
  },
  "options": {
    "include_aspects": true,
    "include_declination_aspects": true
  },
  "progression_options": {
    "day_year_ratio": 1,
    "method": "secondary"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1990-01-01T12:00:00Z"
    },
    "birth_location": {
      "latitude": {
        "decimal": 34.0522
      },
      "longitude": {
        "decimal": -118.2437
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Secondary Progression Example"
  },
  "target_datetime": {
    "iso": "2025-11-06T00:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/ephemeris/progressed"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "configuration": {
    "house_system": "P",
    "object_set": "asteroids_major",
    "zodiac_type": "tropical"
  },
  "options": {
    "include_aspects": true,
    "include_declination_aspects": true
  },
  "progression_options": {
    "day_year_ratio": 1,
    "method": "secondary"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1990-01-01T12:00:00Z"
    },
    "birth_location": {
      "latitude": {
        "decimal": 34.0522
      },
      "longitude": {
        "decimal": -118.2437
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Secondary Progression Example"
  },
  "target_datetime": {
    "iso": "2025-11-06T00:00:00Z"
  }
}'

Responses

A chart cast for the exact instant of a Sun sign ingress (an equinox or solstice for the cardinal signs) or of the next New or Full Moon, at a place you choose. The instant is solved from the Sun's apparent longitude (ingress) or the Sun-Moon elongation (lunation), and the response states how close the solved geometry is to the definition. The chart is geocentric and tropical: angles, 12 cusps, the Sun to Pluto and the Mean North Node with houses and retrograde flags, and sect. For an ingress it adds the traditional validity span (by the Ascendant's modality) and the lord-of-the-year candidates as separate labelled facts, plus house rulers; no candidate is called the lord of the year because the sources disagree. Out of scope in this version: eclipse and great-conjunction events, overlay on a founding chart, and the Moon's applying aspects. Pricing: 2 credits per call.

{
  "event": {
    "sign": "aries",
    "type": "sign_ingress",
    "year": 2027
  },
  "house_system": "P",
  "latitude": 38.8951,
  "longitude": -77.0364
}

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

Responses

Every solar and lunar eclipse in a date range whose degree falls within orb of a natal point (planets, angles, nodes, lots), with the exact time and aspect, and, when location is given, whether and how it could be seen from there: contact times, magnitude, obscuration and the Sun's or Moon's altitude. Pricing (by requested span, decided before any compute): the transit-search brackets — up to 1 year (367 days) = 5, up to 3 years = 10, up to 5 years = 15, up to 10 years = 25, up to 20 years = 40, up to 40 years = 70 credits; a span above your plan's limit is a 400 search_span_limit, nothing charged.

{
  "end_date": "2026-01-01T00:00:00Z",
  "location": {
    "latitude": 22.5726,
    "longitude": 88.3639
  },
  "natal_points": [
    {
      "longitude": 344.5,
      "name": "Sun"
    },
    {
      "longitude": 172,
      "name": "ASC"
    }
  ],
  "start_date": "2025-01-01T00:00:00Z"
}

curl -X POST "https://api.openephemeris.com/predictive/eclipses/natal-hits"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "end_date": "2026-01-01T00:00:00Z",
  "location": {
    "latitude": 22.5726,
    "longitude": 88.3639
  },
  "natal_points": [
    {
      "longitude": 344.5,
      "name": "Sun"
    },
    {
      "longitude": 172,
      "name": "ASC"
    }
  ],
  "start_date": "2025-01-01T00:00:00Z"
}'

Responses

Placidus semi-arc primary directions. Promissors are the Sun through Saturn and their Ptolemaic aspects; significators default to the Ascendant, Midheaven, Sun, Moon and Part of Fortune. Two methods: placidus_mundane (the promissor's body, mundane aspects by semi-arc proportion) and placidus_zodiacal (the promissor's aspect degree on the ecliptic, without latitude). Every event names the method that produced it and gives the arc, the age under the Ptolemy and Naibod keys, and the date each key implies. Uses the true obliquity of the birth date. Placidus semi-arcs do not exist at or inside the polar circle; such births return 422.

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "format": "json",
  "fortune_formula": "sect",
  "include_aspects": [
    0,
    60,
    90,
    120,
    180
  ],
  "include_converse": false,
  "max_age_years": 90,
  "methods": [
    "placidus_mundane",
    "placidus_zodiacal"
  ]
}

curl -X POST "https://api.openephemeris.com/predictive/primary-directions"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "format": "json",
  "fortune_formula": "sect",
  "include_aspects": [
    0,
    60,
    90,
    120,
    180
  ],
  "include_converse": false,
  "max_age_years": 90,
  "methods": [
    "placidus_mundane",
    "placidus_zodiacal"
  ]
}'

Responses

Calculate the nearest return timing (body returns to its natal longitude) near a target datetime. Supported bodies: Sun–Uranus, Mean Node, Mean/True Lilith. 🤖 AI-optimized output available — add format=llm to reduce payload ~65%.

Parameters

{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "body": "Sun",
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 5,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/predictive/returns"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "body": "Sun",
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 5,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}'

Responses

Calculate the nearest lunar return timing (Moon returns to its natal longitude) near a target datetime.

Parameters

{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 30,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/predictive/returns/lunar"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 30,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}'

Responses

Calculate the nearest solar return timing (Sun returns to its natal longitude) near a target datetime.

Parameters

{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 5,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/predictive/returns/solar"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": {
    "iso": "1990-06-15T14:30:00Z"
  },
  "house_system": "P",
  "location": {
    "elevation": 10,
    "latitude": {
      "decimal": 40.7128
    },
    "longitude": {
      "decimal": -74.006
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "return_location": {
    "elevation": 71,
    "latitude": {
      "decimal": 34.0522
    },
    "longitude": {
      "decimal": -118.2437
    },
    "timezone": {
      "iana_name": "UTC"
    }
  },
  "search_window_days": 5,
  "target_datetime": {
    "iso": "2024-06-15T00:00:00Z"
  }
}'

Responses

The previous and next times, within 1550-2650, that the slow planets (Jupiter to Pluto, or a subset) all stand again within orb_deg of their natal longitudes together, and the closest match on each side of birth whether or not it is within the orb. The search is exhaustive over the range (branch and bound on each body's maximum speed, so no window is skipped); window edges are to the second and the closest instant to 10 seconds. Checked against JPL Horizons. Positions are geocentric apparent longitudes; all times UTC. Pricing (by requested span, decided before any compute): up to 100 years = 5, up to 300 years = 10, up to 1101 years (the whole DE440 range) = 15 credits. Omitting start_date and end_date searches the whole range (15).

{
  "birth_datetime": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "bodies": [
    "string"
  ],
  "end_date": "string",
  "orb_deg": 10,
  "start_date": "string",
  "timezone": "string",
  "zodiac_type": "tropical"
}

curl -X POST "https://api.openephemeris.com/predictive/sky-recurrence"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "bodies": [
    "string"
  ],
  "end_date": "string",
  "orb_deg": 10,
  "start_date": "string",
  "timezone": "string",
  "zodiac_type": "tropical"
}'

Responses

Direct the Ascendant (or another releaser) through the Egyptian bounds: circumambulation, directing through the terms (Ptolemy, Tetrabiblos III; Valens, Anthology III). Returns a dated table of periods with the distributor (bound lord) and the partners (planets whose body or ray the directed point meets), and, with target_datetime, the period and partner in force. Arcs are checked against Swiss Ephemeris to 0.1′. All dates are ISO-8601 in the birthplace offset with the IANA timezone.

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "format": "string",
  "key": "ptolemy",
  "max_age_years": 100,
  "method": "ascensional_times",
  "releaser": "asc",
  "target_datetime": {
    "iso": "2023-12-07T15:30:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/predictive/time-lords/distributions"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "format": "string",
  "key": "ptolemy",
  "max_age_years": 100,
  "method": "ascensional_times",
  "releaser": "asc",
  "target_datetime": {
    "iso": "2023-12-07T15:30:00Z"
  }
}'

Responses

Calculate firdaria (فرادير) — the medieval Persian planetary period system that assigns each of the seven classical planets a fixed number of years as the dominant ruler of life. The 75-year master cycle differs for day births (diurnal) and night births (nocturnal). Each major period is subdivided into seven sub-periods in Chaldean order. Firdaria operates independently of signs and houses — it is purely a time-based system making it complementary to profections and transits. Think of it as a 75-year program schedule: knowing your current major and sub-period ruler tells you which planetary archetype is most active in your life right now. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

Parameters

{
  "birth_datetime": "2025-01-01T00:00:00Z",
  "is_day_birth": true,
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "target_datetime": "2025-01-01T00:00:00Z"
}

curl -X POST "https://api.openephemeris.com/predictive/time-lords/firdaria"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": "2025-01-01T00:00:00Z",
  "is_day_birth": true,
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "target_datetime": "2025-01-01T00:00:00Z"
}'

Responses

Calculate annual profections — the foundational Hellenistic timing technique that advances one zodiac sign per birthday from the natal Ascendant. Returns the profected sign, activated house, time lord planet, element, modality, and a full multi-year timeline. Profections are the simplest and most widely used timing technique in traditional astrology, experiencing a major revival in modern Hellenistic practice. Each year of life activates one whole-sign house from the Ascendant; the ruler of that sign becomes the "time lord" coloring the entire year. Angular years (1st, 4th, 7th, 10th) are typically the most eventful. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

Parameters

{
  "ascendant_sign": 0,
  "birth_datetime": "2025-01-01T00:00:00Z",
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "target_datetime": "2025-01-01T00:00:00Z",
  "years_backward": 5
}

curl -X POST "https://api.openephemeris.com/predictive/time-lords/profections"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "ascendant_sign": 0,
  "birth_datetime": "2025-01-01T00:00:00Z",
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "target_datetime": "2025-01-01T00:00:00Z",
  "years_backward": 5
}'

Responses

Calculate zodiacal releasing — the Hellenistic timing technique of Vettius Valens (Anthology IV), which divides a life into a handful of chapters released from a sensitive Lot (Fortune for body and health, Spirit for career and action). Each sign releases for its own minor years: Aries 15, Taurus 8, Gemini 20, Cancer 25, Leo 19, Virgo 20, Libra 8, Scorpio 15, Sagittarius 12, Capricorn 27, Aquarius 30, Pisces 12 — a full circuit of 211. Levels run on the traditional clock: a level-1 "year" is 360 days and a level-2 "month" is 30, each sub-level exactly one twelfth of the level above. Angular periods (1st, 4th, 7th, 10th from the Lot) mark peak chapters. The loosing of the bond is an event in the sub-period sequence, not a property of a sign: when the level-2 walk would return to the sign its general period began on, it jumps to the sign opposite that period and carries on forward. Only general periods longer than one circuit (211 months ≈ 17.58 years) can contain one — Gemini, Cancer, Leo, Virgo, Capricorn and Aquarius. When the Lots of Fortune and Spirit fall in the same sign, releasing from Spirit begins one sign forward (Valens IV, 4:7); spirit_advanced reports when that rule fired. Returns L1 general periods with their L2 sub-periods as absolute dates, peak-period identification, angular/loosing flags, and the active period at the target datetime. 🤖 Agent-first endpoint — pure deterministic math, no ephemeris required.

Parameters

{
  "birth_datetime": "2025-01-01T00:00:00Z",
  "lot_name": "fortune",
  "lot_sign": 0,
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "max_years": 100
}

curl -X POST "https://api.openephemeris.com/predictive/time-lords/zodiacal-releasing"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime": "2025-01-01T00:00:00Z",
  "lot_name": "fortune",
  "lot_sign": 0,
  "house_system": "string",
  "latitude": -90,
  "longitude": -180,
  "max_years": 100
}'

Responses

Return a full chart payload for a given moment (transit chart). Includes all supported bodies: Sun–Pluto (core) plus Chiron, Mean/True North & South Nodes, Mean/True Lilith (Black Moon), and Ceres (extended bodies — gracefully omitted when ephemeris kernels are unavailable). Also returns houses/angles, aspects (major; minor opt-in), and a body_categories map for UI rendering. This is a chart snapshot endpoint (not a transit event search). 🤖 AI-optimized output: add format=llm to reduce payload ~70%.

Parameters

{
  "configuration": {
    "ayanamsa": "lahiri",
    "coordinate_frame": "equatorial",
    "coordinate_system": "topocentric",
    "house_system": "W",
    "object_set": "asteroids_major",
    "zodiac_type": "sidereal"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1985-03-20T08:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 37.7749
      },
      "longitude": {
        "decimal": -122.4194
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Jane Smith"
  }
}

curl -X POST "https://api.openephemeris.com/predictive/transit-chart"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "configuration": {
    "ayanamsa": "lahiri",
    "coordinate_frame": "equatorial",
    "coordinate_system": "topocentric",
    "house_system": "W",
    "object_set": "asteroids_major",
    "zodiac_type": "sidereal"
  },
  "subject": {
    "birth_datetime": {
      "iso": "1985-03-20T08:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 37.7749
      },
      "longitude": {
        "decimal": -122.4194
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Jane Smith"
  }
}'

Responses

Calculate when a planet transits to a specific longitude degree. Features: - Sub-minute precision for transit timing - Retrograde motion handling with multiple crossings - Duration calculations (approach and separation) - All traditional and modern planets supported Performance: <50ms for single transit calculations

{
  "max_crossings": 3,
  "planet_name": "Mars",
  "start_date": "2024-01-01T00:00:00Z",
  "target_degree": 15.5
}

curl -X POST "https://api.openephemeris.com/predictive/transits/planet-to-degree"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "max_crossings": 3,
  "planet_name": "Mars",
  "start_date": "2024-01-01T00:00:00Z",
  "target_degree": 15.5
}'

Responses

Search for various types of transit events within a date range. Features: - Exact crossings of target degrees, several passes per target (results) - Opt-in orb windows (orb_deg / aspect_orbs): enter, every exact hit including retrograde re-passes, and leave, per continuous in-orb episode (windows), with applying/separating at the range start - Natal points × aspects as labelled targets (natal_points, aspects) - Ranked by significance (sort=significance, limit, group=episodes): "my biggest transits this year", each hit with its score components (ranked) - Configurable date ranges (plan limits: 1 year on Explorer/PAYG, 5 years on Pro, 10 years on Startup, 40 years on Scale and above) Performance: one sampled track per planet shared by every target; the cost guard counts days × planets × targets. Pricing (by requested span, decided before any compute): up to 1 year (367 days) = 5, up to 3 years (1097 days) = 10, up to 5 years (1828 days) = 15, up to 10 years (3654 days) = 25, up to 20 years (7306 days) = 40, up to 40 years (14611 days) = 70 credits. Plan limits: Explorer/PAYG 1 year, Pro 5 years, Startup 10 years, Scale and Enterprise 40 years. A span above your plan's limit is rejected with 400 search_span_limit naming the limit and the bracket that fits — nothing is charged. Any 4xx/5xx outcome is refunded, including a 429 compute_overload shed; rate-limit 429s are refused before anything is charged. Results are capped at 1000 transit events per response; past that the earliest 1000 are returned with truncated: true and truncation.resume_from to continue from. Deadline: 30 s of compute on every plan. A search that runs out of time returns the bodies it finished with truncated: true (reason deadline, the unsearched bodies in truncation.remaining); if none finished it returns 503 compute_timeout, and the credits are refunded.

{
  "end_date": "2025-01-01T00:00:00Z",
  "planet_names": [
    "Mars",
    "Jupiter"
  ],
  "start_date": "2024-01-01T00:00:00Z",
  "target_degrees": [
    0,
    90,
    180,
    270
  ]
}

curl -X POST "https://api.openephemeris.com/predictive/transits/search"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "end_date": "2025-01-01T00:00:00Z",
  "planet_names": [
    "Mars",
    "Jupiter"
  ],
  "start_date": "2024-01-01T00:00:00Z",
  "target_degrees": [
    0,
    90,
    180,
    270
  ]
}'

Responses

Calculate planetary sign ingresses (when planets change zodiac signs). Features: - Sub-minute precision for ingress timing - Retrograde status detection - All traditional and modern planets - Batch processing for multiple planets Performance: <200ms for batch ingress calculations

{
  "end_date": "2025-01-01T00:00:00Z",
  "planet_names": [
    "Mars",
    "Jupiter"
  ],
  "start_date": "2024-01-01T00:00:00Z",
  "target_sign": "Aries"
}

curl -X POST "https://api.openephemeris.com/predictive/transits/sign-ingresses"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "end_date": "2025-01-01T00:00:00Z",
  "planet_names": [
    "Mars",
    "Jupiter"
  ],
  "start_date": "2024-01-01T00:00:00Z",
  "target_sign": "Aries"
}'

Responses

Calculate a composite chart from 2–10 subjects. The default method, davison (also accepted as davidson, the spelling this API originally shipped), computes a true Davison relationship chart: a real chart cast at the mean of the subjects' birth instants and the great-circle midpoint of their birth places, with real planets, angles, and house cusps. method=midpoint instead averages each body's longitude across the subjects; a midpoint composite has no Ascendant or Midheaven, so its angles and house cusps are empty. The response's method field reports which was actually computed. 🤖 AI-optimized output available — add format=llm to reduce payload ~65%.

Parameters

{
  "method": "davidson",
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}

curl -X POST "https://api.openephemeris.com/comparative/composite"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "method": "davidson",
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}'

Responses

Calculate a 2-person Davison-style midpoint. Currently computes the Sun's midpoint longitude only — other planets are not averaged and houses/angles are not returned. 🤖 AI-optimized output available — add format=llm to reduce payload ~65%.

Parameters

{
  "method": "davidson",
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}

curl -X POST "https://api.openephemeris.com/comparative/composite/midpoint"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "method": "davidson",
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}'

Responses

Calculate a synastry-style overlay between a natal chart and transits. - Chart A: natal subject at birth - Chart B: the same subject/location at transit_datetime (defaults to now UTC)

Parameters

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "Alice"
  },
  "transit_datetime": {
    "iso": "2025-01-01T00:00:00Z"
  }
}

curl -X POST "https://api.openephemeris.com/comparative/natal-transits"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "Alice"
  },
  "transit_datetime": {
    "iso": "2025-01-01T00:00:00Z"
  }
}'

Responses

Return lightweight chart payloads for an overlay across multiple subjects (no aspects).

Parameters

{
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}

curl -X POST "https://api.openephemeris.com/comparative/overlay"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subjects": [
    {
      "birth_datetime": {
        "iso": "1990-06-15T14:30:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 40.7128
        },
        "longitude": {
          "decimal": -74.006
        },
        "timezone": {
          "iana_name": "America/New_York"
        }
      },
      "name": "Alice"
    },
    {
      "birth_datetime": {
        "iso": "1992-02-10T09:15:00"
      },
      "birth_location": {
        "latitude": {
          "decimal": 34.0522
        },
        "longitude": {
          "decimal": -118.2437
        },
        "timezone": {
          "iana_name": "America/Los_Angeles"
        }
      },
      "name": "Bob"
    }
  ]
}'

Responses

Calculate a synastry chart (comparison between two subjects). 🤖 AI-optimized output available — add format=llm to reduce payload ~65%.

Parameters

{
  "subject_a": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "Alice"
  },
  "subject_b": {
    "birth_datetime": {
      "iso": "1992-02-10T09:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 34.0522
      },
      "longitude": {
        "decimal": -118.2437
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Bob"
  }
}

curl -X POST "https://api.openephemeris.com/comparative/synastry"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject_a": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "Alice"
  },
  "subject_b": {
    "birth_datetime": {
      "iso": "1992-02-10T09:15:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 34.0522
      },
      "longitude": {
        "decimal": -118.2437
      },
      "timezone": {
        "iana_name": "America/Los_Angeles"
      }
    },
    "name": "Bob"
  }
}'

Responses

Calculate strictly isolated ACG aspect lines. Options configurations to include power lines/midpoints will be explicitly stripped.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/aspects"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

Compute cyclocartography transit snapshots over a time window.

{
  "end_epoch": "2026-12-31T00:00:00Z",
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  },
  "start_epoch": "2026-01-01T00:00:00Z"
}

curl -X POST "https://api.openephemeris.com/acg/ccg"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "end_epoch": "2026-12-31T00:00:00Z",
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  },
  "start_epoch": "2026-01-01T00:00:00Z"
}'

Responses

Computes on-demand transit parans at a single epoch.

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}

curl -X POST "https://api.openephemeris.com/acg/ccg/parans"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}'

Responses

Find exact geographic points where two ACG lines intersect. This is a novel feature — no other public ACG API provides crossing points as structured data. Returns GeoJSON Point features. Response packaging is stable: type=FeatureCollection, features is always an array (possibly empty), and crossing_count matches the feature count.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/crossings"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

List available celestial body catalogs and aspect angles.

curl -X GET "https://api.openephemeris.com/acg/datasets"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Compute declination parallel and contra-parallel latitude bands. A NOVEL feature — no other ACG tool maps declination parallels geographically. Returns horizontal GeoJSON lines where two bodies share (parallel) or oppose (contra-parallel) declination. Current endpoint contract uses a fixed 1.5° orb (DefaultDeclinationOrb). No max_orb query parameter is accepted on this route.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/declination-lines"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

Calculates Astrocartography (ACG) geometry exclusively for the seven classical Hermetic Lots (Lot of Fortune, Spirit, Eros, Necessity, Courage, Victory, and Nemesis). ### Astrological & Mathematical Geometry Hermetic Lots are sensitive mathematical points derived from the natal Ascendant and two planetary positions (e.g., Day Fortune = Ascendant + Moon − Sun). Unlike planets, their ecliptic longitude shifts with the observer's natal birthplace, so natal.birthplace_lat and natal.birthplace_lon are required fields for this endpoint. The engine converts each lot's ecliptic longitude to equatorial coordinates (Right Ascension and Declination) using the standard ecliptic-to-equatorial transformation, then runs those coordinates through the same angular line generators used for all ACG bodies. ### Line Types Returned All four standard angular line types are returned for each lot: - MC — Meridian where the lot culminates (2-point vertical meridian) - IC — Anti-culmination meridian, 180° opposite the MC (2-point vertical meridian) - AC — Horizon curve where the lot's equivalent point rises (181-point sinusoidal arc) - DC — Horizon curve where the lot's equivalent point sets (181-point sinusoidal arc) Use the options.line_types field to restrict output to a subset (e.g., ["MC", "IC"]). ### Sect Awareness Sect (day/night chart) is determined from the Sun's actual altitude at the natal birthplace and time. The day and night formulas are applied accordingly — e.g., Fortune uses ASC + Moon − Sun for day charts and ASC + Sun − Moon for night charts.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/hermetic-lines"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

Find ACG lines closest to a geographic location. Supports two modes: 1. Proximity mode (recommended): Provide query_lat and query_lon in the request body to find lines near any arbitrary point. Optionally set radius_deg (default: 3.0, max: 90). Returns features sorted by distance (closest first) with min_distance_deg and min_distance_km in each feature's properties. 2. Birthplace fallback: If query_lat/query_lon are omitted but natal.birthplace_lat/natal.birthplace_lon are present, those coordinates are used as the query location. 3. Unfiltered mode (backward-compatible): If neither query location nor natal birthplace is provided, all computed features are returned unfiltered. New request fields (all optional): - query_lat (float): Latitude of the query point (-90 to 90) - query_lon (float): Longitude of the query point (-180 to 180) - radius_deg (float): Proximity radius in degrees (1° ≈ 111 km). Default: 3.0

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/hits"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

Compute local space azimuth/altitude lines from observer location.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/local-space"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

ACG engine version, capabilities, and status.

curl -X GET "https://api.openephemeris.com/acg/meta"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Compute astrocartography lines for all N(N-1)/2 body-pair midpoints. Uses short-arc RA averaging in equatorial space, then runs each virtual midpoint body through the standard MC/IC/AC/DC generators. Returns MIDPOINT_MC, MIDPOINT_IC, MIDPOINT_AC, MIDPOINT_DC line types.

{
  "configuration": {
    "coordinate_system": "geocentric",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  },
  "options": {
    "include_aspects": true
  },
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}

curl -X POST "https://api.openephemeris.com/acg/midpoints"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "configuration": {
    "coordinate_system": "geocentric",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  },
  "options": {
    "include_aspects": true
  },
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}'

Responses

Computes exact angular simultaneity events between N planetary bodies for a single chart.

{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}

curl -X POST "https://api.openephemeris.com/acg/parans"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}'

Responses

Calculate strictly isolated ACG power lines (MC, IC, AC, DC). Options configurations to include aspects/midpoints will be explicitly stripped.

{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}

curl -X POST "https://api.openephemeris.com/acg/power-lines"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "epoch": "1990-06-15T14:30:00Z",
  "natal": {
    "birthplace_lat": 34.05,
    "birthplace_lon": -118.24
  },
  "options": {
    "asteroid_groups": [
      "centaur",
      "muse"
    ]
  }
}'

Responses

Computes exact cross-chart angular simultaneity events between NxM planetary bodies for two charts.

{
  "subject1": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "subject2": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}

curl -X POST "https://api.openephemeris.com/acg/relational-parans"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject1": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  },
  "subject2": {
    "birth_datetime": {
      "iso": "1990-06-15T14:30:00"
    },
    "birth_location": {
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "name": "John Doe"
  }
}'

Responses

Generate SVG/PNG bi-wheel chart. Free on every tier, including Explorer.

Parameters

{
  "subject_a": {
    "birth_datetime": {
      "iso": "2023-12-07T15:30:00Z"
    },
    "birth_location": {
      "city": "New York",
      "country": "USA",
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "houses": {},
    "name": "string",
    "positions": [
      {}
    ]
  },
  "subject_b": {
    "birth_datetime": {
      "iso": "2023-12-07T15:30:00Z"
    },
    "birth_location": {
      "city": "New York",
      "country": "USA",
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "houses": {},
    "name": "string",
    "positions": [
      {}
    ]
  },
  "configuration": {
    "coordinate_system": "geocentric",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  }
}

curl -X POST "https://api.openephemeris.com/visualization/bi-wheel"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject_a": {
    "birth_datetime": {
      "iso": "2023-12-07T15:30:00Z"
    },
    "birth_location": {
      "city": "New York",
      "country": "USA",
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "houses": {},
    "name": "string",
    "positions": [
      {}
    ]
  },
  "subject_b": {
    "birth_datetime": {
      "iso": "2023-12-07T15:30:00Z"
    },
    "birth_location": {
      "city": "New York",
      "country": "USA",
      "latitude": {
        "decimal": 40.7128
      },
      "longitude": {
        "decimal": -74.006
      },
      "timezone": {
        "iana_name": "America/New_York"
      }
    },
    "houses": {},
    "name": "string",
    "positions": [
      {}
    ]
  },
  "configuration": {
    "coordinate_system": "geocentric",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  }
}'

Responses

Generates a visually premium Human Design bodygraph (SVG or PNG).

Parameters

{
  "birth_datetime_local": "1985-03-20T08:15:00",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": {
    "iana_name": "America/Los_Angeles"
  }
}

curl -X POST "https://api.openephemeris.com/visualization/bodygraph"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime_local": "1985-03-20T08:15:00",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": {
    "iana_name": "America/Los_Angeles"
  }
}'

Responses

Generate SVG/PNG chart wheel. Free on every tier, including Explorer.

Parameters