openephemeris-com Agricultural 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 Agricultural API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:
- description: Work with the earth's rhythms. Biodynamic planting profiles and multi-day agricultural calendars. **1 unit per request.**
  name: agricultural
paths:
  /ephemeris/agro/calendar:
    get:
      description: 'Returns compact biodynamic summaries for a date range (max 31 days).


        Each day includes: day type, quality score, ascending status, void-of-course

        active flag, phase name, and illumination percentage. Designed for building

        monthly planning calendars.


        🤖 AI-optimized output available — add `format=llm` to reduce payload ~80%.


        ```bash

        GET /ephemeris/agro/calendar?lat=-33.87&lon=151.21&start=2026-03-01&end=2026-03-31&tz=Australia/Sydney

        ```'
      operationId: get_agro_calendar_endpoint_ephemeris_agro_calendar_get
      parameters:
      - description: Observer latitude (WGS84, degrees)
        in: query
        name: lat
        required: true
        schema:
          description: Observer latitude (WGS84, degrees)
          maximum: 90
          minimum: -90
          title: Lat
          type: number
      - description: Observer longitude (WGS84, degrees)
        in: query
        name: lon
        required: true
        schema:
          description: Observer longitude (WGS84, degrees)
          maximum: 180
          minimum: -180
          title: Lon
          type: number
      - description: Start date as YYYY-MM-DD
        example: '2026-03-01'
        in: query
        name: start
        required: true
        schema:
          description: Start date as YYYY-MM-DD
          title: Start
          type: string
      - description: End date as YYYY-MM-DD (inclusive, max 31 days from start)
        example: '2026-03-31'
        in: query
        name: end
        required: true
        schema:
          description: End date as YYYY-MM-DD (inclusive, max 31 days from start)
          title: End
          type: string
      - description: Observer elevation in metres above sea level. Lowers the visible horizon (dip ~ 1.76 arcmin * sqrt(metres)), which moves sunrise/sunset and moonrise/moonset earlier and later respectively - about 6 minutes per event at 1600 m. Default 0 reproduces the sea-level result exactly.
        in: query
        name: elev
        required: false
        schema:
          default: 0
          description: Observer elevation in metres above sea level. Lowers the visible horizon (dip ~ 1.76 arcmin * sqrt(metres)), which moves sunrise/sunset and moonrise/moonset earlier and later respectively - about 6 minutes per event at 1600 m. Default 0 reproduces the sea-level result exactly.
          maximum: 8849
          minimum: 0
          title: Elev
          type: number
      - description: Output format
        in: query
        name: format
        required: false
        schema:
          default: json
          description: Output format
          pattern: ^(?i)(json|llm|llm)$
          title: Format
          type: string
      - in: header
        name: authorization
        required: false
        schema:
          title: Authorization
          type:
          - string
          - 'null'
      - in: header
        name: X-API-Key
        required: false
        schema:
          title: X-Api-Key
          type:
          - string
          - 'null'
      - in: header
        name: X-OpenEphemeris-API-Key
        required: false
        schema:
          title: X-OpenEphemeris-API-Key
          type:
          - string
          - 'null'
      - in: header
        name: apikey
        required: false
        schema:
          title: Apikey
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgroCalendarResponse'
          description: Successful Response
        '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: Biodynamic monthly calendar
      tags:
      - agricultural
      x-meridian-tier: Explorer
      x-meridian-units: 1
  /ephemeris/agro/daily:
    get:
      description: 'Returns a complete Maria Thun biodynamic day profile for a given date and location.


        **Includes:**

        - Moon sign, element, latitude velocity (ascending/descending)

        - Thun day type (root / leaf / flower / fruit) with quality score (0–100)

        - Aspect modifiers with explained score impacts (Saturn, Jupiter, Mars, Node)

        - Activity recommendations (favorable / unfavorable / optimal tasks)

        - Void-of-course window (active status + next window)

        - Lunar phase + illumination

        - Sunrise, sunset, moonrise, moonset (topocentric; agree with JPL Horizons to within about a minute)


        **Zodiac:** Always tropical for Thun classification (per Thun methodology).

        **Ephemeris:** DE440.


        🤖 AI-optimized output available — add `format=llm` to reduce payload ~70%.


        ```bash

        GET /ephemeris/agro/daily?lat=-33.87&lon=151.21&date=2026-03-15&timezone=Australia/Sydney

        ```'
      operationId: get_agro_daily_endpoint_ephemeris_agro_daily_get
      parameters:
      - description: Observer latitude (WGS84, degrees)
        in: query
        name: lat
        required: true
        schema:
          description: Observer latitude (WGS84, degrees)
          maximum: 90
          minimum: -90
          title: Lat
          type: number
      - description: Observer longitude (WGS84, degrees)
        in: query
        name: lon
        required: true
        schema:
          description: Observer longitude (WGS84, degrees)
          maximum: 180
          minimum: -180
          title: Lon
          type: number
      - description: Date as YYYY-MM-DD
        example: '2026-03-15'
        in: query
        name: date
        required: true
        schema:
          description: Date as YYYY-MM-DD
          title: Date
          type: string
      - description: 'IANA zone name, for example `Asia/Tokyo`. When given, the day is that zone''s civil day (midnight to midnight on its clock), so the times are the ones a local almanac lists for the date. When omitted, the day is the local mean solar day at the longitude: 24 hours starting at local mean midnight. The UTC day is never used; `day_basis` in the response says which applied. Without a zone, an event within about an hour of local midnight (mostly the Moon''s) can fall on the neighbouring civil date; send `timezone` for the exact civil day. It applies to the sunrise, sunset, moonrise and moonset in `horizon` only. Zone rules come from current tzdata, so dates before 1970 may differ from the clocks of the time.'
        example: Asia/Tokyo
        in: query
        name: timezone
        required: false
        schema:
          description: IANA zone name, for example `Asia/Tokyo`. Selects the civil day; omitted means the local mean solar day at the longitude.
          example: Asia/Tokyo
          title: Timezone
          type: string
      - description: Observer elevation in metres above sea level. Lowers the visible horizon (dip ~ 1.76 arcmin * sqrt(metres)), which moves sunrise/sunset and moonrise/moonset earlier and later respectively - about 6 minutes per event at 1600 m. Default 0 reproduces the sea-level result exactly.
        in: query
        name: elev
        required: false
        schema:
          default: 0
          description: Observer elevation in metres above sea level. Lowers the visible horizon (dip ~ 1.76 arcmin * sqrt(metres)), which moves sunrise/sunset and moonrise/moonset earlier and later respectively - about 6 minutes per event at 1600 m. Default 0 reproduces the sea-level result exactly.
          maximum: 8849
          minimum: 0
          title: Elev
          type: number
      - description: Output format
        in: query
        name: format
        required: false
        schema:
          default: json
          description: Output format
          pattern: ^(?i)(json|llm|llm)$
          title: Format
          type: string
      - in: header
        name: authorization
        required: false
        schema:
          title: Authorization
          type:
          - string
          - 'null'
      - in: header
        name: X-API-Key
        required: false
        schema:
          title: X-Api-Key
          type:
          - string
          - 'null'
      - in: header
        name: X-OpenEphemeris-API-Key
        required: false
        schema:
          title: X-OpenEphemeris-API-Key
          type:
          - string
          - 'null'
      - in: header
        name: apikey
        required: false
        schema:
          title: Apikey
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgroDailyResponse'
          description: Successful Response
        '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: Biodynamic daily profile
      tags:
      - agricultural
      x-meridian-tier: Explorer
      x-meridian-units: 1
  /ephemeris/agro/void-of-course:
    get:
      description: 'Returns the current Void of Course (VoC) Moon window for a given Julian Day.


        Method 3: scans backward from the Moon''s next sign ingress to find the last

        major Ptolemaic aspect (conjunction, sextile, square, trine, opposition) to

        a traditional planet. The VoC period runs from that aspect until the ingress.


        ```bash

        GET /ephemeris/agro/void-of-course?jd=2451545.0

        ```'
      operationId: get_void_of_course_endpoint_ephemeris_agro_void_of_course_get
      parameters:
      - description: Julian Day (UT1)
        example: 2451545
        in: query
        name: jd
        required: true
        schema:
          description: Julian Day (UT1)
          format: double
          title: Jd
          type: number
      - in: header
        name: authorization
        required: false
        schema:
          title: Authorization
          type:
          - string
          - 'null'
      - in: header
        name: X-API-Key
        required: false
        schema:
          title: X-Api-Key
          type:
          - string
          - 'null'
      - in: header
        name: X-OpenEphemeris-API-Key
        required: false
        schema:
          title: X-OpenEphemeris-API-Key
          type:
          - string
          - 'null'
      - in: header
        name: apikey
        required: false
        schema:
          title: Apikey
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoCData'
          description: Successful Response
        '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: Void of Course Moon
      tags:
      - agricultural
      x-meridian-tier: Explorer
      x-meridian-units: 1
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    AgroCalendarResponse:
      description: Multi-day calendar summary.
      properties:
        _meta:
          description: Calculation metadata
          title: ' Meta'
          type: object
        days:
          description: Daily biodynamic summaries
          items:
            $ref: '#/components/schemas/AgroCalendarDay'
          title: Days
          type: array
        observer:
          description: Observer location details
          title: Observer
          type: object
        range:
          additionalProperties:
            type: string
          description: Start and end dates of the calendar
          title: Range
          type: object
      required:
      - range
      - observer
      - days
      - _meta
      title: AgroCalendarResponse
      type: object
    AgroTidalData:
      properties:
        diurnal_inequality:
          description: Diurnal inequality value
          title: Diurnal Inequality
          type: number
        king_tide_risk:
          description: King tide risk score (0 to 1)
          title: King Tide Risk
          type: number
        perigee_proximity:
          description: Perigee proximity score (0 to 1)
          title: Perigee Proximity
          type: number
        spring_neap_index:
          description: Spring-neap index (-1 to +1)
          title: Spring Neap Index
          type: number
        syzygy_status:
          description: Syzygy status (e.g., 'spring', 'neap')
          title: Syzygy Status
          type: string
        total_forcing:
          description: Total tidal forcing score
          title: Total Forcing
          type: number
      required:
      - spring_neap_index
      - syzygy_status
      - diurnal_inequality
      - total_forcing
      - perigee_proximity
      - king_tide_risk
      title: AgroTidalData
      type: object
    ThunAnalysis:
      properties:
        ascending:
          description: True if Moon latitude is increasing
          title: Ascending
          type: boolean
        base_element:
          description: earth | water | air | fire
          title: Base Element
          type: string
        day_type:
          description: root | leaf | flower | fruit
          title: Day Type
          type: string
        favorable:
          items:
            type: string
          title: Favorable
          type: array
        lat_velocity:
          description: Latitude velocity in degrees per day
          title: Lat Velocity
          type: number
        modifiers:
          items:
            $ref: '#/components/schemas/ThunModifier'
          title: Modifiers
          type: array
        optimal:
          items:
            type: string
          title: Optimal
          type: array
        quality_score:
          description: Quality score from 0 to 100
          title: Quality Score
          type: integer
        unfavorable:
          items:
            type: string
          title: Unfavorable
          type: array
      required:
      - day_type
      - base_element
      - quality_score
      - ascending
      - lat_velocity
      title: ThunAnalysis
      type: object
    AgroCalendarDay:
      description: One day's compact entry in the calendar.
      properties:
        ascending:
          description: True if Moon latitude is increasing
          title: Ascending
          type: boolean
        date:
          description: Date in YYYY-MM-DD format
          title: Date
          type: string
        day_type:
          anyOf:
          - type: string
          description: root | leaf | flower | fruit
          title: Day Type
        error:
          anyOf:
          - type: string
          description: Error message if calculation failed
          title: Error
        illumination_pct:
          anyOf:
          - type: number
          description: Illumination percentage
          title: Illumination Pct
        phase_name:
          anyOf:
          - type: string
          description: Current moon phase name
          title: Phase Name
        quality_score:
          anyOf:
          - type: integer
          description: Quality score from 0 to 100
          title: Quality Score
        spring_neap_index:
          anyOf:
          - type: number
          description: Spring-neap index
          title: Spring Neap Index
        total_forcing:
          anyOf:
          - type: number
          description: Total tidal forcing score
          title: Total Forcing
        void_active:
          description: True if Void of Course is active during the day
          title: Void Active
          type: boolean
      required:
      - date
      - ascending
      - void_active
      title: AgroCalendarDay
      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
    AgroLunarData:
      properties:
        ascending:
          description: True if ascending
          title: Ascending
          type: boolean
        distance_km:
          description: Distance from Earth in km
          title: Distance Km
          type: number
        illumination_pct:
          description: Illumination percentage 0-100
          title: Illumination Pct
          type: number
        lat_velocity:
          description: Latitude velocity
          title: Lat Velocity
          type: number
        latitude:
          description: Ecliptic latitude
          title: Latitude
          type: number
        node_lon:
          description: True node longitude
          title: Node Lon
          type: number
        phase_name:
          description: Current moon phase name
          title: Phase Name
          type: string
        sign_longitude:
          description: Longitude within the current sign (0-30)
          title: Sign Longitude
          type: number
        waxing:
          description: True if waxing
          title: Waxing
          type: boolean
      required:
      - sign_longitude
      - latitude
      - distance_km
      - ascending
      - lat_velocity
      - node_lon
      - phase_name
      - illumination_pct
      - waxing
      title: AgroLunarData
      type: object
    AgroDailyResponse:
      description: Full biodynamic daily profile.
      properties:
        _meta:
          description: Calculation metadata
          title: ' Meta'
          type: object
        date:
          description: Date in YYYY-MM-DD format
          title: Date
          type: string
        horizon:
          allOf:
          - $ref: '#/components/schemas/HorizonEvents'
          description: Sunrise/sunset and moonrise/moonset events
        lunar:
          allOf:
          - $ref: '#/components/schemas/AgroLunarData'
          description: Lunar data summary
        observer:
          description: Observer location details
          title: Observer
          type: object
        thun:
          allOf:
          - $ref: '#/components/schemas/ThunAnalysis'
          description: Thun biodynamic analysis
        tidal_forcing:
          $ref: '#/components/schemas/AgroTidalData'
          description: Tidal forcing metrics
        void_of_course:
          allOf:
          - $ref: '#/components/schemas/VoCData'
          description: Void of course Moon data
      required:
      - date
      - observer
      - lunar
      - thun
      - void_of_course
      - horizon
      - _meta
      title: AgroDailyResponse
      type: object
    HorizonEvents:
      properties:
        day_basis:
          description: 'Which day the four events belong to: `civil_tz` (the calendar date in `timezone`) or `local_solar` (the local mean solar day at the longitude). Never the UTC day.'
          title: Day Basis
          type: string
        moonrise:
          anyOf:
          - type: string
          description: ISO 8601 UTC moonrise time
          title: Moonrise
        moonset:
          anyOf:
          - type: string
          description: ISO 8601 UTC moonset time
          title: Moonset
        polar:
          description: True if location experiences polar day/night
          title: Polar
          type: boolean
        sunrise:
          anyOf:
          - type: string
          description: ISO 8601 UTC sunrise time
          title: Sunrise
        sunset:
          anyOf:
          - type: string
          description: ISO 8601 UTC sunset time
          title: Sunset
        timezone:
          description: The IANA zone whose civil day was used. Present only when the request named one.
          title: Timezone
          type: string
      required:
      - polar
      title: HorizonEvents
      type: object
    VoCData:
      properties:
        active:
          description: True if currently void of course
          title: Active
          type: boolean
        last_aspect:
          anyOf:
          - type: string
          description: Last major aspect before ingress
          title: Last Aspect
        last_aspect_jd:
          anyOf:
          - format: double
            type: number
          description: Julian Day of the last major aspect
          title: Last Aspect Jd
        moon_sign:
          description: Current moon sign
          title: Moon Sign
          type: string
        next_sign:
          description: Next moon sign
          title: Next Sign
          type: string
        void_end_jd:
          description: Void end Julian Day
          format: double
          title: Void End Jd
          type: number
        void_start_jd:
          description: Void start Julian Day
          format: double
          title: Void Start Jd
          type: number
      required:
      - active
      - void_start_jd
      - void_end_jd
      - moon_sign
      - next_sign
      title: VoCData
      type: object
    ThunModifier:
      properties:
        aspect:
          anyOf:
          - type: string
          description: Aspect name
          title: Aspect
        impact:
          description: Signed score delta
          title: Impact
          type: integer
        orb:
          anyOf:
          - type: number
          description: Orb in degrees
          title: Orb
        planet:
          anyOf:
          - type: string
          description: Planet name
          title: Planet
        source:
          description: Source of the modifier, e.g., 'saturn_opposition'
          title: Source
          type: string
      required:
      - source
      - impact
      title: ThunModifier
      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