openephemeris-com Tidal 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 Tidal API
  version: 1.0.0
servers:
- description: Production
  url: https://api.openephemeris.com
tags:
- description: Calculate tidal forces and lunar coastal influences. **1 unit per request.**
  name: tidal
paths:
  /tidal/forcing:
    get:
      description: Calculate astronomical gravitational forcing potential (spring/neap, perigee, etc) for a specific location.
      operationId: get_tidal_forcing_endpoint_tidal_forcing_get
      parameters:
      - description: Observer latitude
        in: query
        name: lat
        required: true
        schema:
          description: Observer latitude
          maximum: 90
          minimum: -90
          title: Lat
          type: number
      - description: Observer longitude
        in: query
        name: lon
        required: true
        schema:
          description: Observer longitude
          maximum: 180
          minimum: -180
          title: Lon
          type: number
      - description: Date in YYYY-MM-DD format
        in: query
        name: date
        required: false
        schema:
          title: Date
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TidalForcingResponse'
          description: Tidal forcing metrics and indices
        '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: Astronomical Tidal Forcing
      tags:
      - tidal
      x-meridian-tier: Explorer
      x-meridian-units: 1
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
    LunarSyzygy:
      description: A New or Full Moon with the Moon's distance and its supermoon / micromoon class under the requested supermoon_definition.
      properties:
        distance_class:
          description: supermoon (relative_distance >= 0.9), micromoon (<= 0.1) or regular.
          enum:
          - supermoon
          - micromoon
          - regular
          type: string
        distance_km:
          description: Geometric Earth-Moon centre-to-centre distance at that instant, km.
          format: double
          type: number
        phase:
          description: new_moon or full_moon (stable id).
          enum:
          - new_moon
          - full_moon
          type: string
        reference_apogee:
          $ref: '#/components/schemas/LunarApsis'
        reference_perigee:
          $ref: '#/components/schemas/LunarApsis'
        relative_distance:
          description: '(Da - D) / (Da - Dp): 1 at perigee distance, 0 at apogee distance, against reference_apogee and reference_perigee.'
          format: double
          type: number
        time:
          description: Instant of the New or Full Moon (geocentric, apparent longitudes), ISO-8601 with the UTC offset of the response's timezone.
          format: date-time
          type: string
      required:
      - phase
      - time
      - distance_km
      - relative_distance
      - distance_class
      - reference_perigee
      - reference_apogee
      title: LunarSyzygy
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ForcingIndices:
      properties:
        diurnal_class:
          description: Tidal regime classification
          title: Diurnal Class
          type: string
        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
          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
      - diurnal_class
      - total_forcing
      - king_tide_risk
      - perigee_proximity
      title: ForcingIndices
      type: object
    TidalLunarData:
      properties:
        days_to_perigee:
          description: Whole days (rounded) to the next perigee; next_perigee has the exact instant.
          title: Days To Perigee
          type: integer
        declination:
          description: Moon declination in degrees
          title: Declination
          type: number
        distance_anomaly:
          description: Distance anomaly (perigee proximity)
          title: Distance Anomaly
          type: number
        distance_km:
          description: Moon distance in km
          title: Distance Km
          type: number
        geocentric_distance_km:
          description: Geometric Earth-Moon centre-to-centre distance, km (distance_km is from the observer).
          format: double
          type: number
        next_apogee:
          $ref: '#/components/schemas/LunarApsis'
        next_perigean_spring_tide:
          allOf:
          - $ref: '#/components/schemas/LunarSyzygy'
          description: 'The next New or Full Moon within 90% of perigee (a supermoon under orbit_90): the syzygy behind a perigean spring (''king'') tide. Astronomical forcing only; local tide height depends on the coast.'
        next_perigee:
          $ref: '#/components/schemas/LunarApsis'
        perigee_status:
          description: 'From the Moon''s geocentric distance between the nearest perigee and apogee (relative_distance): ''near_perigee'' at 0.9 or more, ''near_apogee'' at 0.1 or less, else ''intermediate''. The same 90% rule as a supermoon (orbit_90).'
          title: Perigee Status
          type: string
        phase_angle:
          description: Lunar phase angle in degrees
          title: Phase Angle
          type: number
        phase_name:
          description: Lunar phase name
          title: Phase Name
          type: string
        previous_apogee:
          $ref: '#/components/schemas/LunarApsis'
        previous_perigee:
          $ref: '#/components/schemas/LunarApsis'
        relative_distance:
          description: '(Da - D) / (Da - Dp) against the perigee and apogee nearest in time: 1 at perigee, 0 at apogee.'
          format: double
          type: number
      required:
      - phase_name
      - phase_angle
      - distance_km
      - distance_anomaly
      - declination
      - perigee_status
      - days_to_perigee
      title: TidalLunarData
      type: object
    EquilibriumTide:
      properties:
        combined_m:
          description: Combined equilibrium tide (meters)
          title: Combined M
          type: number
        lunar_component_m:
          description: Lunar component of equilibrium tide (meters)
          title: Lunar Component M
          type: number
        note:
          description: Explanatory note
          title: Note
          type: string
        solar_component_m:
          description: Solar component of equilibrium tide (meters)
          title: Solar Component M
          type: number
      required:
      - lunar_component_m
      - solar_component_m
      - combined_m
      - note
      title: EquilibriumTide
      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
    Observer:
      properties:
        lat:
          description: Observer latitude
          title: Lat
          type: number
        lon:
          description: Observer longitude
          title: Lon
          type: number
      required:
      - lat
      - lon
      title: Observer
      type: object
    TidalSolarData:
      properties:
        declination:
          description: Sun declination in degrees
          title: Declination
          type: number
        distance_au:
          description: Sun distance in AU
          title: Distance Au
          type: number
      required:
      - declination
      - distance_au
      title: TidalSolarData
      type: object
    TidalForcingResponse:
      description: Full tidal forcing analysis for a location and time.
      properties:
        date:
          description: Date in YYYY-MM-DD format (if requested by date)
          title: Date
          type: string
        equilibrium:
          allOf:
          - $ref: '#/components/schemas/EquilibriumTide'
          description: Theoretical equilibrium tide heights
        forcing_indices:
          allOf:
          - $ref: '#/components/schemas/ForcingIndices'
          description: Computed forcing indicators
        julian_day:
          description: Julian Day of the calculation
          format: double
          title: Julian Day
          type: number
        lunar:
          allOf:
          - $ref: '#/components/schemas/TidalLunarData'
          description: Lunar parameters
        meta:
          allOf:
          - $ref: '#/components/schemas/TidalMeta'
          description: Metadata and disclaimers
        observer:
          allOf:
          - $ref: '#/components/schemas/Observer'
          description: Observer location
        solar:
          allOf:
          - $ref: '#/components/schemas/TidalSolarData'
          description: Solar parameters
        timezone:
          description: 'IANA zone the perigee, apogee and syzygy times are written in: the zone at the coordinates.'
          type: string
      required:
      - meta
      - date
      - julian_day
      - observer
      - lunar
      - solar
      - forcing_indices
      - equilibrium
      title: TidalForcingResponse
      type: object
    TidalMeta:
      properties:
        calculation_ms:
          description: Calculation time in milliseconds
          title: Calculation Ms
          type: integer
        calculation_type:
          description: Type of calculation performed
          title: Calculation Type
          type: string
        disclaimer:
          description: Disclaimer about astronomical vs local predictions
          title: Disclaimer
          type: string
        ephemeris:
          description: Ephemeris used, e.g., 'DE440'
          title: Ephemeris
          type: string
      required:
      - ephemeris
      - calculation_type
      - disclaimer
      - calculation_ms
      title: TidalMeta
      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