openephemeris-com Calendar API

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 Calendar API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:
- description: Mark the turning of the wheel. Cross-quarter days, exact moon phases, and lunar standstills. **10 units per request.**
  name: Calendar
paths:
  /calendar/astrology/cross-quarter:
    get:
      description: Returns the 8 Wheel of the Year events (4 cross-quarters + 4 cardinal points) calculated using true apparent solar longitude from JPL DE440. Cross-quarter dates are the true midpoints between solstices and equinoxes, NOT the traditional Gregorian approximations. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~45%. **Pricing:** 5 credits — one year, 8 events (the transit-search 1-year bracket).
      operationId: cross_quarter_calendar_astrology_cross_quarter_get
      parameters:
      - description: 'Calendar year (Gregorian). Supported range: 1550–2649 (JPL DE440).'
        in: query
        name: year
        required: true
        schema:
          description: 'Calendar year (Gregorian). Supported range: 1550–2649 (JPL DE440).'
          example: 2025
          maximum: 2649
          minimum: 1550
          title: Year
          type: integer
      - description: 'Response format: json | llm.'
        in: query
        name: format
        required: false
        schema:
          title: Format
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossQuarterResponse'
          description: 8 Wheel of the Year events in chronological order
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Internal Server Error
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: Wheel of the Year — True Astronomical Dates
      tags:
      - Calendar
      x-meridian-tier: Explorer
      x-meridian-units: 5
  /calendar/astrology/lunar-standstill:
    get:
      description: Returns the current state of the 18.6-year lunar nodal cycle. Identifies Major Standstill (Moon reaches ±28.6° declination) and Minor Standstill (Moon limited to ±18.3°) epochs. The most recent Major Standstill is circa 2025.4. **Pricing:** 2 credits — a single point-in-time lookup.
      operationId: lunar_standstill_calendar_astrology_lunar_standstill_get
      parameters:
      - description: Date in YYYY-MM-DD format.
        in: query
        name: date
        required: false
        schema:
          title: Date
          type:
          - string
          - 'null'
      - description: Julian Day.
        in: query
        name: jd
        required: false
        schema:
          format: double
          title: Jd
          type:
          - number
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LunarStandstillResponse'
          description: Nodal cycle status and next standstill dates
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Internal Server Error
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: Lunar Standstill — 18.6-Year Nodal Cycle Status
      tags:
      - Calendar
      x-meridian-tier: Explorer
      x-meridian-units: 2
  /calendar/astrology/moon-phases:
    get:
      description: 'Returns the current 8-phase lunar phase classification (not just 4), illumination fraction, Moon age in hours, and the next 4 principal phase moments (New, First Quarter, Full, Third Quarter). 🤖 AI-optimized output available — add `format=llm` to reduce payload ~45%. **Pricing:** 2 credits — one 30-day lunar cycle (at most 4 exact phase events): the cheapest way to get the exact time of the next New, First Quarter, Full or Third Quarter Moon. New and Full Moon events carry the Moon''s distance and supermoon / micromoon class (`supermoon_definition`), and `apsides` lists the perigees and apogees in the same 30 days.'
      operationId: moon_phases_calendar_astrology_moon_phases_get
      parameters:
      - description: Date in YYYY-MM-DD format. Mutually exclusive with jd.
        in: query
        name: date
        required: false
        schema:
          title: Date
          type:
          - string
          - 'null'
      - description: Julian Day. Mutually exclusive with date.
        in: query
        name: jd
        required: false
        schema:
          format: double
          title: Jd
          type:
          - number
          - 'null'
      - description: 'Response format: json | llm.'
        in: query
        name: format
        required: false
        schema:
          title: Format
          type:
          - string
          - 'null'
      - description: 'Which reading of the supermoon rule to apply. Both use the 90% rule of Richard Nolle, who coined the word in 1979 ("a new or full moon which occurs with the Moon at or near (within 90% of) its closest approach to Earth in a given orbit"). `orbit_90` (default; Fred Espenak''s tables and NASA): relative distance = (Da - D) / (Da - Dp) with Da and Dp the apogee and perigee nearest in time to the New or Full Moon. `year_90` (Nolle''s own worked method): Da and Dp are the farthest apogee and closest perigee of that UTC calendar year. Supermoon when the relative distance is 0.9 or more, micromoon when it is 0.1 or less (Espenak). "Supermoon" is not an IAU term.'
        in: query
        name: supermoon_definition
        required: false
        schema:
          default: orbit_90
          description: 'Which reading of the supermoon rule to apply. Both use the 90% rule of Richard Nolle, who coined the word in 1979 ("a new or full moon which occurs with the Moon at or near (within 90% of) its closest approach to Earth in a given orbit"). `orbit_90` (default; Fred Espenak''s tables and NASA): relative distance = (Da - D) / (Da - Dp) with Da and Dp the apogee and perigee nearest in time to the New or Full Moon. `year_90` (Nolle''s own worked method): Da and Dp are the farthest apogee and closest perigee of that UTC calendar year. Supermoon when the relative distance is 0.9 or more, micromoon when it is 0.1 or less (Espenak). "Supermoon" is not an IAU term.'
          enum:
          - orbit_90
          - year_90
          title: Supermoon Definition
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoonPhasesResponse'
          description: Current phase and upcoming principal phases
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__models__schemas__system__ErrorResponse'
          description: Internal Server Error
      security:
      - bearerAuth: []
      - meridianApiKeyAuth: []
      - apiKeyAuth: []
      - serviceKeyAuth: []
      summary: 8-Phase Lunar Classification + Next Principal Phases
      tags:
      - Calendar
      x-meridian-tier: Explorer
      x-meridian-units: 2
components:
  schemas:
    LunarApsis:
      description: 'One lunar perigee (closest approach) or apogee (farthest point): the instant the Moon''s geocentric distance is at its minimum or maximum, found from DE440 to about a second.'
      properties:
        distance_km:
          description: Geometric Earth-Moon centre-to-centre distance at the apsis, km.
          format: double
          type: number
        time:
          description: Instant of the apsis, ISO-8601 with the UTC offset of the response's timezone.
          format: date-time
          type: string
        type:
          description: perigee or apogee (stable id).
          enum:
          - perigee
          - apogee
          type: string
      required:
      - type
      - time
      - distance_km
      title: LunarApsis
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CrossQuarterResponse:
      description: Solar events and cross-quarter days.
      properties:
        _meta:
          description: Calculation metadata
          title: ' Meta'
          type: object
        events:
          description: List of solar events in chronological order
          items:
            $ref: '#/components/schemas/CrossQuarterEvent'
          title: Events
          type: array
        year:
          description: Year of the events
          title: Year
          type: integer
      required:
      - year
      - events
      - _meta
      title: CrossQuarterResponse
      type: object
    MoonPhasesResponse:
      description: Moon phases over a date range.
      properties:
        _meta:
          description: Calculation metadata
          title: ' Meta'
          type: object
        data:
          allOf:
          - $ref: '#/components/schemas/LunarPhaseResult'
          description: The matching phase events
        range:
          additionalProperties:
            type: string
          description: Start and end dates of the search
          title: Range
          type: object
      required:
      - range
      - data
      - _meta
      title: MoonPhasesResponse
      type: object
    LunarPhaseResult:
      properties:
        apsides:
          description: Perigees and apogees in the same 30-day range, in time order (times in UTC).
          items:
            $ref: '#/components/schemas/LunarApsis'
          type: array
        current_phase:
          description: The eight-bucket lunar phase the Moon is in at the query instant (new_moon, waxing_crescent, first_quarter, waxing_gibbous, full_moon, waning_gibbous, third_quarter, waning_crescent). This is a state at the requested date/jd, not a phase event, and it is never included in events.
          title: Current Phase
          type: string
        events:
          description: Principal phase events (new_moon, first_quarter, full_moon, third_quarter) occurring in the requested range, each timed to the exact moment the phase is reached. Sorted chronologically.
          items:
            $ref: '#/components/schemas/MoonPhaseEvent'
          title: Events
          type: array
        supermoon_definition:
          description: 'The supermoon_definition applied: orbit_90 or year_90.'
          type: string
      required:
      - events
      title: LunarPhaseResult
      type: object
    MoonPhaseEvent:
      properties:
        distance_class:
          description: 'New and Full Moon only: supermoon (relative_distance >= 0.9), micromoon (<= 0.1) or regular.'
          enum:
          - supermoon
          - micromoon
          - regular
          type: string
        distance_km:
          description: 'New and Full Moon only: geometric Earth-Moon centre-to-centre distance at the phase, km.'
          format: double
          type: number
        phase:
          description: One of new_moon, first_quarter, full_moon, third_quarter
          title: Phase
          type: string
        relative_distance:
          description: 'New and Full Moon only: (Da - D) / (Da - Dp) under supermoon_definition; 1 at perigee distance, 0 at apogee distance.'
          format: double
          type: number
        time:
          description: ISO 8601 UTC timestamp of exactly when the phase occurs
          title: Time
          type: string
      required:
      - phase
      - time
      title: MoonPhaseEvent
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    LunarStandstillResponse:
      description: Lunar standstills for a specific year.
      properties:
        _meta:
          description: Calculation metadata
          title: ' Meta'
          type: object
        events:
          description: Standstill events in the year
          items:
            $ref: '#/components/schemas/LunarStandstillInfo'
          title: Events
          type: array
        year:
          description: Year searched
          title: Year
          type: integer
      required:
      - year
      - events
      - _meta
      title: LunarStandstillResponse
      type: object
    CrossQuarterEvent:
      properties:
        declination:
          description: Sun's declination at the time of the event
          title: Declination
          type: number
        distance_au:
          description: Sun's distance in AU
          title: Distance Au
          type: number
        name:
          description: Event name (e.g., Vernal Equinox)
          title: Name
          type: string
        time:
          description: ISO 8601 UTC timestamp of exactly when the event occurs
          title: Time
          type: string
        type:
          description: '''equinox'', ''solstice'', or ''cross-quarter'''
          title: Type
          type: string
      required:
      - name
      - type
      - time
      - declination
      - distance_au
      title: CrossQuarterEvent
      type: object
    LunarStandstillInfo:
      properties:
        declination:
          description: Moon's declination at the peak
          title: Declination
          type: number
        node_distance:
          description: Angular distance to the node
          title: Node Distance
          type: number
        peak_date:
          description: ISO 8601 UTC timestamp of the peak of the standstill
          title: Peak Date
          type: string
        type:
          description: '''major'' or ''minor'''
          title: Type
          type: string
      required:
      - type
      - peak_date
      - declination
      - node_distance
      title: LunarStandstillInfo
      type: object
    app__api__models__schemas__system__ErrorResponse:
      additionalProperties: false
      description: Standardized error response.
      properties:
        debug_info:
          anyOf:
          - type: object
          description: Debug information
          title: Debug Info
        details:
          anyOf:
          - type: object
          description: Additional error details
          title: Details
        error:
          description: Error type/category
          title: Error
          type: string
        message:
          description: Human-readable error message
          title: Message
          type: string
        request_id:
          anyOf:
          - type: string
          description: Request identifier
          title: Request Id
        success:
          default: false
          description: Always false for errors
          title: Success
          type: boolean
        timestamp:
          description: Error timestamp
          format: date-time
          title: Timestamp
          type: string
      required:
      - error
      - message
      - timestamp
      title: ErrorResponse
      type: object
  securitySchemes:
    apiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    bearerAuth:
      bearerFormat: JWT/API-Key
      scheme: bearer
      type: http
    meridianApiKeyAuth:
      in: header
      name: X-OpenEphemeris-API-Key
      type: apiKey
    serviceKeyAuth:
      in: header
      name: X-Service-Key
      type: apiKey