ephemeris

Enhanced Natal Chart Calculation

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).

**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%.
post/ephemeris/natal-chart

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/ephemeris/natal-chart
  • Auth: one of:
    • HTTP bearer
    • API key in header X-OpenEphemeris-API-Key
    • API key in header X-API-Key
    • API key in header X-Service-Key

Query parameters

output_modestring nullable

Deprecated: use preset+format. Accepts full|simple|llm.

formatstring

Response format: json | llm. Controls response projection only.

include_aspectsboolean nullable

Deprecated: prefer request body options.include_aspects.

include_hermetic_lotsboolean nullable

Deprecated: prefer request body enhanced_options.include_hermetic_lots (or legacy options.include_hermetic_lots).

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

include_all_traditional_partsboolean

DEPRECATED. Prefer request body options.include_all_traditional_parts where applicable. This top-level field is accepted for backward compatibility and may be removed in a future release.

include_aspectsboolean

DEPRECATED. Prefer request body options.include_aspects. This field is accepted for backward compatibility and may be removed in a future release.

include_dignitiesboolean

DEPRECATED. Prefer request body options.include_dignities. This top-level field is accepted for backward compatibility and may be removed in a future release.

include_hermetic_lotsboolean

DEPRECATED. Prefer request body enhanced_options.include_hermetic_lots (or options.include_hermetic_lots). This top-level field is accepted for backward compatibility and may be removed in a future release.

include_visualboolean nullable

When true, a high-fidelity chart wheel SVG/PNG is embedded in the response alongside the data payload. Adds 2 credits to the request cost.

Example request

{
  "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"
  }
}

Response

Successful enhanced chart calculation

chart_typestring

Chart type identifier

element_balanceobject

Elemental balance

elongationsobject

Sun-relative elongations (per-body separation and signed east/west delta) (opt-in).

harmonicsobject

Harmonic chart positions keyed by harmonic number

hemisphere_emphasisobject

Hemisphere weights

human_design_gatesobject

Human Design / I Ching gate + line mappings from ecliptic longitude (math-only; includes mapping version) (opt-in).

lunar_phaseobject

Lunar phase context (phase name, illumination, phase angle, waxing/waning, days-to-new/full) (opt-in).

midpointsobject[]

Calculated midpoints between planet pairs

patterns_by_typeobject

Patterns organized by type for easier filtering

planetsobject required

Planetary positions keyed by name

solar_relationshipsobject

Solar relationship / visibility classifications (e.g., cazimi/combust/under-beams) and Mercury/Venus morning/evening star context.

successboolean

Response success status

void_of_courseobject

Void-of-Course Moon context (status, start/end window, last major aspect, sign context) (opt-in).

Example response

{
  "calculation_metadata": {
    "technique_id": "natal",
    "technique_label": "Composite (Davison)",
    "technique_method": "davidson",
    "technique_version": "v1"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.