openephemeris-com

openephemeris-com Predictive API

Look ahead (or behind). Find exact times for transits, cast solar & lunar returns, calculate progressions, and run traditional time-lord techniques (primary directions, firdaria, annual profections, zodiacal releasing). **5 units per request** (progressed-chart and transit-chart snapshot calls are 1 unit).

GitHub OpenAPI

Operations 16

POST /ephemeris/progressed Calculate progressed chart (Secondary, Tertiary, Solar Arc) #
POST /mundane/chart Mundane Chart #
POST /predictive/eclipses/natal-hits Eclipses That Hit a Natal Chart #
POST /predictive/primary-directions Calculate Primary Directions #
POST /predictive/returns Calculate Planetary Return Timing #
POST /predictive/returns/lunar Calculate Lunar Return Timing #
POST /predictive/returns/solar Calculate Solar Return Timing #
POST /predictive/sky-recurrence Sky Recurrence: When Does Your Sky Return? #
POST /predictive/time-lords/distributions Distribution Through the Bounds #
POST /predictive/time-lords/firdaria Firdaria Planetary Periods #
POST /predictive/time-lords/profections Annual Profections Time Lords #
POST /predictive/time-lords/zodiacal-releasing Zodiacal Releasing Time Lords #
POST /predictive/transit-chart Calculate transit chart (full chart snapshot) #
POST /predictive/transits/planet-to-degree Calculate Planetary Transit to Degree #
POST /predictive/transits/search Search Transit Events #
POST /predictive/transits/sign-ingresses Calculate Sign Ingresses #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/openephemeris-com/openapi/openephemeris-com-predictive-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-acgccgrequest-payload-schema.json
📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-acgrequest-payload-schema.json
📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-natal-chart-enhanced-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-vedic-chart-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-zodiacal-releasing-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-acglocal-space-request-payload-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/openephemeris-com:openephemeris-com-predictive-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openephemeris-com-predictive-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: '**Open Ephemeris Engine** - Professional Astrological Calculations


    A high-performance REST API for precise astrological chart calculations using the SuperNOVAS / Calceph engine. ## Features


    - 🎯 **Precise Calculations**: SuperNOVAS / Calceph backend (NASA DE440) for astronomical accuracy

    - 🏗️ **Flexible Input Formats**: Support for multiple coordinate, datetime, and timezone formats

    - 🏠 **Seven House Systems**: Placidus (default), Koch, Porphyry, Regiomontanus, Campanus, Equal, and Whole Sign — the complete set, enumerated by `GET /ephemeris/house-systems`

    - ⚡ **High Performance**: Parallel processing and intelligent caching

    - 📊 **Comprehensive Data**: Complete natal charts with planets, houses, angles, and aspects

    - 🔒 **Input Validation**: Robust validation with clear error messages

    - 📖 **OpenAPI Documentation**: Interactive API documentation and schema validation

    - 🪐 **Transit Calculations**: Precise planetary transit timing with retrograde support

    - 📅 **Predictive Features**: Solar/lunar returns, sign ingresses, and future transits

    - 🤖 **Agent-First Design**: Optimized for LLM consumption and autonomous tool use


    ## Agent-First Design


    Open Ephemeris is built from the ground up to be "Agent-First". This means:


    1. **High Information Density**: We provide comprehensive metadata to minimize the need for external lookup. 2. **Optimized Projections**: The `format=llm` parameter converts raw astronomical data into a structure that LLMs can reason about more effectively, reducing token usage while preserving interpretive nuance. 3. **Deterministic Contract**: API responses are versioned and strictly typed to ensure reliable tool-calling for AI agents. ### Output Modes (`format` parameter)


    Endpoints supporting enhanced formatting accept a `format` query parameter:


    - `format=json` (default): The full, raw response schema — every field the endpoint produces, in its complete nested form. Choose it when you need the whole object graph. It does not carry more numeric resolution than `format=llm`: most angular values are serialized as 32-bit floats in both, which quantizes them to at worst about 0.055 arcsec (the step grows with the angle — finest near 0°, coarsest approaching 360°). `format=json` returns more fields, not more decimal places. - `format=llm`: A token-optimized projection. It replaces complex nested objects with flattened, "punchy" descriptions that provide immediate context for an LLM (e.g., automatically including the sign name alongside the degree). ## Authentication


    Open Ephemeris supports several authentication modes:


    1. **JWT tokens (end users)** via Supabase:


    ```http

    Authorization: Bearer

    ```


    2. **User API keys (integrations)** via `X-OpenEphemeris-API-Key`, `X-API-Key`, or `Authorization: Bearer`:


    ```http

    X-OpenEphemeris-API-Key: opene-... ```

    or

    ```http

    Authorization: Bearer opene-... ```


    *Note: Use `X-OpenEphemeris-API-Key` if your infrastructure (e.g. AWS/Azure) intercepts the standard `X-API-Key` header.*


    3. **Service API keys (internal services)** via `X-Service-Key` header:


    ```http

    X-Service-Key:

    ```


    Valid service keys are intended for trusted internal services and

    bypass rate limits. User requests remain subject to tier-based

    rate limiting and usage metering. ## Supported Formats


    ### Coordinates

    - **Decimal degrees**: `40.7128, -74.0060`

    - **DMS strings**: `"40°42''46"N", "74°00''22"W"`

    - **Component objects**: `{"degrees": 40, "minutes": 42, "seconds": 46, "direction": "N"}`


    ### DateTime


    **A datetime that states a clock time must also state its zone.** A

    zone-less clock time is rejected with `400 ambiguous_datetime`; it is not

    assumed to be UTC. An unstated zone moves the Ascendant by roughly 15° per

    hour while every planet keeps its sign, so a guess would be a confident

    wrong answer.'
  title: Open Ephemeris Predictive API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:


# --- truncated at 32 KB (262 KB total) ---
# Full source: https://artifacts.apis.io/openephemeris-com/openapi/openephemeris-com-predictive-api-openapi.yml