openephemeris-com Tidal API
Calculate tidal forces and lunar coastal influences. **1 unit per request.**
Calculate tidal forces and lunar coastal influences. **1 unit per request.**
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/openephemeris-com:openephemeris-com-tidal-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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