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-time-conversion-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.
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 Time Conversion API
version: 1.0.0
servers:
- description: Production
url: https://api.openephemeris.com
tags:
- description: Convert between time formats. Julian Day numbers, sidereal time, sunrise/sunset. **1 unit per request.**
name: Time Conversion
paths:
/time/delta-t:
get:
description: Provide Delta T (TT - UT1) for any historical/future epoch.
operationId: get_delta_t_time_delta_t_get
parameters:
- description: Date (YYYY-MM-DD)
in: query
name: date
required: true
schema:
description: Date (YYYY-MM-DD)
example: '2026-03-15'
title: Date
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/DeltaTResponse'
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: Delta T (TT-UT1) calculation
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
/time/equation-of-time:
get:
description: Compute the Equation of Time (sundial correction) in minutes for a given JD.
operationId: get_equation_of_time_time_equation_of_time_get
parameters:
- description: Julian Day (Terrestrial Time)
in: query
name: jd
required: true
schema:
description: Julian Day (Terrestrial Time)
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/EquationOfTimeResponse'
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: Equation of Time
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
/time/julian-day:
post:
description: Bridge between civil calendars and astronomical time. Handles BCE dates.
operationId: calculate_julian_day_time_julian_day_post
parameters:
- 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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JulianDayRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/JulianDayResponse'
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: Calendar conversion to Julian Day Number
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
/time/scales:
post:
description: Convert between major astronomical time scales (UTC, TT, TAI, TDB, UT1).
operationId: post_time_scales_time_scales_post
parameters:
- 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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeScalesRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TimeScalesResponse'
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: Time Scale Conversions
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
/time/sidereal:
get:
description: Compute Local Apparent Sidereal Time (LAST) and Greenwich Mean Sidereal Time (GMST).
operationId: get_sidereal_time_time_sidereal_get
parameters:
- description: Date (YYYY-MM-DD) or Julian Day (jd:2451545.0)
in: query
name: date
required: true
schema:
description: Date (YYYY-MM-DD) or Julian Day (jd:2451545.0)
example: '2026-03-15'
title: Date
type: string
- description: Observer longitude (positive East)
in: query
name: longitude
required: false
schema:
default: 0
description: Observer longitude (positive East)
maximum: 180
minimum: -180
title: Longitude
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/SiderealTimeResponse'
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: Sidereal Time (LAST & GMST)
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
/time/solar-event:
get:
description: Compute exact times for sunrise, sunset, and solar transit for a given day and location.
operationId: get_solar_events_time_solar_event_get
parameters:
- description: Date (YYYY-MM-DD)
in: query
name: date
required: true
schema:
description: Date (YYYY-MM-DD)
example: '2026-03-20'
title: Date
type: string
- description: Observer latitude
in: query
name: latitude
required: true
schema:
description: Observer latitude
maximum: 90
minimum: -90
title: Latitude
type: number
- description: Observer longitude
in: query
name: longitude
required: true
schema:
description: Observer longitude
maximum: 180
minimum: -180
title: Longitude
type: number
- 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. 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
- 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/SolarEventResponse'
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: Solar Events (Sunrise/Sunset/Transit)
tags:
- Time Conversion
x-meridian-tier: Explorer
x-meridian-units: 1
components:
schemas:
TimeScalesRequest:
properties:
from_scale:
default: utc
description: Input time scale (utc, tt, tai, tdb, ut1)
title: From Scale
type: string
julian_day:
description: Julian Day to convert
format: double
title: Julian Day
type: number
latitude:
anyOf:
- type: number
description: Observer latitude
title: Latitude
longitude:
anyOf:
- type: number
description: Observer longitude
title: Longitude
required:
- julian_day
title: TimeScalesRequest
type: object
EquationOfTimeResponse:
properties:
apparent_solar_time:
description: The computed Apparent Solar Time (decimal hours)
title: Apparent Solar Time
type: number
equation_of_time_minutes:
description: The Equation of Time value in minutes
title: Equation Of Time Minutes
type: number
julian_day:
description: The Julian Day (TT) used for calculation
format: double
title: Julian Day
type: number
mean_solar_time:
description: The computed Mean Solar Time (decimal hours)
title: Mean Solar Time
type: number
required:
- julian_day
- equation_of_time_minutes
- mean_solar_time
- apparent_solar_time
title: EquationOfTimeResponse
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
DeltaTResponse:
properties:
date:
description: Date string used for calculation
title: Date
type: string
delta_t:
additionalProperties:
type: number
description: Delta T value (seconds) and its components
title: Delta T
type: object
julian_day:
description: Julian Day for which Delta T was calculated
format: double
title: Julian Day
type: number
model:
description: The mathematical model used (e.g., Stephenson 2021)
title: Model
type: string
uncertainty:
description: Estimated uncertainty in the Delta T value
title: Uncertainty
type: object
required:
- date
- julian_day
- delta_t
- model
- uncertainty
title: DeltaTResponse
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
SiderealTimeResponse:
properties:
equation_of_equinoxes:
description: The nutation correction in hours
title: Equation Of Equinoxes
type: number
gmst:
description: Greenwich Mean Sidereal Time in hours
title: Gmst
type: number
information:
description: Metadata about the calculation engine
title: Information
type: object
last:
description: Local Apparent Sidereal Time in hours
title: Last
type: number
longitude_used:
description: The observer longitude used for LAST
title: Longitude Used
type: number
required:
- gmst
- last
- equation_of_equinoxes
- longitude_used
- information
title: SiderealTimeResponse
type: object
JulianDayResponse:
properties:
input_interpretation:
description: Metadata about the input date/calendar
title: Input Interpretation
type: object
julian_day:
description: Julian Day number
example: 2451545
format: double
title: Julian Day
type: number
julian_day_terrestrial:
description: Julian Day in Terrestrial Time (TT)
format: double
title: Julian Day Terrestrial
type: number
modified_julian_day:
description: Modified Julian Day (JD - 2400000.5)
format: double
title: Modified Julian Day
type: number
valid_range:
description: Validity range for high-precision calculations
title: Valid Range
type: object
required:
- julian_day
- modified_julian_day
- julian_day_terrestrial
- input_interpretation
- valid_range
title: JulianDayResponse
type: object
SolarEventDetail:
properties:
altitude_deg:
anyOf:
- type: number
description: Altitude in degrees (positive above horizon)
title: Altitude Deg
azimuth_deg:
anyOf:
- type: number
description: Azimuth in degrees (0=North, 90=East)
title: Azimuth Deg
jd:
description: Exact time as a Julian Day number
format: double
title: Jd
type: number
time_iso:
description: Exact time in ISO 8601 format
title: Time Iso
type: string
type:
description: Type of event (sunrise, sunset, transit, etc.)
title: Type
type: string
required:
- type
- time_iso
- jd
title: SolarEventDetail
type: object
SolarEventResponse:
properties:
date:
description: The requested date
title: Date
type: string
events:
description: List of solar events found for the day
items:
$ref: '#/components/schemas/SolarEventDetail'
title: Events
type: array
information:
description: 'Calculation metadata: `model`; `day_basis` (`civil_tz` or `local_solar`, see the `timezone` parameter), `day_start` and `day_end` (the UTC window searched), and `timezone` when one was named; `elev_m` and `horizon_dip_deg` when an elevation was given.'
title: Information
type: object
latitude:
description: Observer latitude
title: Latitude
type: number
longitude:
description: Observer longitude
title: Longitude
type: number
required:
- date
- latitude
- longitude
- events
title: SolarEventResponse
type: object
JulianDayRequest:
additionalProperties: false
properties:
calendar:
default: proleptic_gregorian
description: Calendar system to use (e.g. proleptic_gregorian, julian)
title: Calendar
type: string
day:
description: Day of the month, can include fractional days
title: Day
type: number
hour:
default: 0
description: Hour of the day (0-23)
title: Hour
type: number
minute:
default: 0
description: Minute of the hour (0-59)
title: Minute
type: number
month:
description: Month of the year (1-12)
maximum: 12
minimum: 1
title: Month
type: integer
second:
default: 0
description: Second of the minute (0-59)
title: Second
type: number
time_scale:
default: utc
description: Time scale (utc, tt)
title: Time Scale
type: string
year:
description: Astronomical year (0 = 1 BCE, -1 = 2 BCE)
title: Year
type: integer
required:
- year
- month
- day
title: JulianDayRequest
type: object
TimeScalesResponse:
properties:
delta_t:
description: Delta T value used (seconds)
example: 69.18
title: Delta T
type: number
jd_tai:
description: Julian Day in International Atomic Time
example: 2461114.50043
format: double
title: Jd Tai
type: number
jd_tdb:
description: Julian Day in Barycentric Dynamical Time
example: 2461114.500802
format: double
title: Jd Tdb
type: number
jd_tt:
description: Julian Day in Terrestrial Time
example: 2461114.500801
format: double
title: Jd Tt
type: number
jd_ut1:
description: Julian Day in Universal Time 1
example: 2461114.5000007
format: double
title: Jd Ut1
type: number
jd_utc:
description: Julian Day in Coordinated Universal Time
example: 2461114.5
format: double
title: Jd Utc
type: number
offsets_seconds:
additionalProperties:
type: number
description: Offsets in seconds between scales relative to TT
example:
tai_tt: 32.184
tt_tdb: 0.0016
title: Offsets Seconds
type: object
required:
- jd_utc
- jd_ut1
- jd_tt
- jd_tai
- jd_tdb
- delta_t
- offsets_seconds
title: TimeScalesResponse
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