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

Comprehensive health check with dependency status validation.

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/Anti-Vertex.

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"
  },
  "format": "json"
}

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"
  },
  "format": "json"
}'

Responses

Calculate positions for fixed stars at a specific moment. Supports individual star names, predefined groups (royal_stars, behenian, navigational, foundation_24, galactic), and magnitude filtering. Returns ecliptic coordinates, proper motion, and metadata for each star. 🤖 AI-optimized output available — add format=llm to reduce payload ~60%.

Parameters

{
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "min_magnitude": 2,
  "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"
  },
  "min_magnitude": 2,
  "star_names": [
    "Regulus",
    "Spica",
    "Aldebaran"
  ]
}'

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

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

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

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

{
  "enhanced_options": {
    "aspect_patterns": true,
    "include_midpoints": true
  },
  "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_payload_kilobytes": 512,
    "max_subjects": 10
  },
  "preset": "full"
}

curl -X POST "https://api.openephemeris.com/ephemeris/natal/batch"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "enhanced_options": {
    "aspect_patterns": true,
    "include_midpoints": true
  },
  "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_payload_kilobytes": 512,
    "max_subjects": 10
  },
  "preset": "full"
}'

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",
  "prenatal_type": "auto"
}

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",
  "prenatal_type": "auto"
}'

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

Return progressed positions, aspects, and metadata for a subject. Supports Secondary (Naibod), Tertiary, 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

Calculates Placidian semi-arc primary directions.

{
  "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",
  "include_aspects": [
    1
  ],
  "include_converse": true,
  "max_age_years": 1
}

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",
  "include_aspects": [
    1
  ],
  "include_converse": true,
  "max_age_years": 1
}'

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",
  "include_chart": true,
  "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",
  "include_chart": true,
  "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",
  "include_chart": true,
  "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",
  "include_chart": true,
  "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",
  "include_chart": true,
  "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",
  "include_chart": true,
  "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 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 most powerful timing technique in Hellenistic astrology. Divides life into chapters ruled by zodiac signs, starting from a sensitive Lot (Fortune or Spirit). Each sign rules for its planetary ruler's minor years in months. Angular periods (1st, 4th, 7th, 10th from the Lot) mark peak chapters. Loosing of the bond occurs when a period's ruler falls in a cadent sign. Returns L1 major periods with optional L2 sub-periods, peak period identification, angular/loosing flags, and an optional current-period highlight 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

Parameters

{
  "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: - Comprehensive transit searches - Configurable date ranges (up to 5 years) - Multiple transit types and aspects - Detailed timing and metadata Performance: Optimized for large-scale searches

Parameters

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

Parameters

{
  "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 (Davidson or Midpoint). 🤖 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 midpoint composite (planets averaged; houses/angles from Davison midpoint time+place). 🤖 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.

{
  "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/ccg"
  -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 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

Query ACG features as a GeoJSON FeatureCollection.

{
  "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/features"
  -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. Requires Pro tier.

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",
    "delta_t_profile": "swiss_default",
    "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",
    "delta_t_profile": "swiss_default",
    "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_utc": "2025-01-01T00:00:00Z",
  "format": "json",
  "include_chiron": false,
  "include_lilith": false,
  "include_visual": false,
  "latitude": 0,
  "longitude": 0
}

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_utc": "2025-01-01T00:00:00Z",
  "format": "json",
  "include_chiron": false,
  "include_lilith": false,
  "include_visual": false,
  "latitude": 0,
  "longitude": 0
}'

Responses

Generate SVG/PNG chart wheel. Requires Pro tier. Explorer-tier and lower API keys receive 403 by design; there is no lower-tier fallback wheel-rendering endpoint in the current contract.

Parameters

{
  "subject": {
    "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",
    "delta_t_profile": "swiss_default",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  }
}

curl -X POST "https://api.openephemeris.com/visualization/chart-wheel"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "subject": {
    "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",
    "delta_t_profile": "swiss_default",
    "house_system": "P",
    "object_set": "modern_plus_chiron",
    "zodiac_type": "tropical"
  }
}'

Responses

Raw Besselian elements (X, Y, d, μ, l₁, l₂, f₁, f₂) and their time derivatives for any eclipse. For researchers and advanced users.

Parameters

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

Responses

Lunar eclipse visibility with contact times (penumbral, partial, total). Safe to view without eye protection. 🤖 AI-optimized output available — add output_format=llm to reduce payload ~55%.

Parameters

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

Responses

Find the next solar or lunar eclipse visible from specific coordinates. Planning tool for eclipse chasers.

Parameters

curl -X GET "https://api.openephemeris.com/eclipse/next-visible?lat=-90&lon=-180"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Calculate complete solar eclipse circumstances with Besselian elements and global path for a given date. Returns eclipse classification, Saros series, safety warnings, and uncertainty analysis. 🤖 AI-optimized output available — add output_format=llm to reduce payload ~55%.

Parameters

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

Responses

Local circumstances for a specific observer: magnitude, obscuration, contact times (C1-C4), duration, and sun position. 🤖 AI-optimized output available — add output_format=llm to reduce payload ~55%.

Parameters

curl -X GET "https://api.openephemeris.com/eclipse/solar/local?lat=-90&lon=-180"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"

Responses

Generate a full Human Design bodygraph. Requires 'service' tier or admin access (Beta).

{
  "birth_datetime_utc": "2025-01-01T00:00:00Z",
  "format": "json",
  "include_chiron": false,
  "include_lilith": false,
  "include_visual": false,
  "latitude": 0,
  "longitude": 0
}

curl -X POST "https://api.openephemeris.com/human-design/chart"
  -H "X-OpenEphemeris-API-Key: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
  "birth_datetime_utc": "2025-01-01T00:00:00Z",
  "format": "json",
  "include_chiron": false,
  "include_lilith": false,
  "include_visual": false,
  "latitude": 0,
  "longitude": 0
}'

Responses