---
title: "Out-of-Bounds Declination Analysis"
method: POST
path: "/ephemeris/declinations"
tags: ["ephemeris"]
---

# Out-of-Bounds Declination Analysis

`POST /ephemeris/declinations`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/declinations`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Analyse ecliptic coordinates to compute equatorial declinations, detect out-of-bounds (OOB) planets, and find declination aspects (parallels and contraparallels).

A planet is out of bounds when its declination exceeds the obliquity of the ecliptic (~23.44°). OOB planets operate outside the Sun's framework and are interpreted as wildcards in contemporary astrology. The Moon is the most frequently OOB body.

Parallels (same declination, same hemisphere) behave like conjunctions; contraparallels (equal but opposite declination) behave like oppositions.

🤖 Agent-first endpoint — pure deterministic math, no ephemeris kernel required.

## Query parameters

- `format` string
- `output_mode` string, nullable

## Request body

- DeclinationAnalysisRequest: Input for out-of-bounds declination analysis. Provide ecliptic coordinates for each body.
  - `bodies` object[], required: Array of celestial bodies with ecliptic coordinates.
    - `id` integer, required: Celestial body identifier (e.g. 0=Sun, 1=Moon, 2=Mercury…)
    - `latitude` number, double, required: Ecliptic latitude in degrees (typically ±8°)
    - `longitude` number, double, required: Ecliptic longitude in degrees [0, 360)
  - `obliquity` number, double: Obliquity of the ecliptic in degrees. Defaults to J2000 mean obliquity (23.4393°).
  - `parallel_orb` number, double: Orb in degrees for detecting parallels and contraparallels. Default 1.0°.

## Response `200`

Successful Response

- DeclinationAnalysisResponse: Out-of-bounds declination analysis results.
  - `bodies` object[]: Per-body declination data.
    - `declination` number, double
    - `direction` 'north' | 'south'
    - `id` integer
    - `is_oob` boolean
    - `latitude` number, double
    - `longitude` number, double
    - `name` string
    - `oob_excess` number, double
  - `calculation_metadata` object: Processing metadata.
    - `output_mode` string
    - `processing_time_ms` number
  - `max_declination` number, double: Most extreme absolute declination across all bodies.
  - `obliquity` number, double: Obliquity value used for the analysis.
  - `oob_count` integer: Number of bodies that are out of bounds.
  - `parallels` object[]: Declination aspects: parallels and contraparallels.
    - `body1` integer
    - `body2` integer
    - `dec1` number, double
    - `dec2` number, double
    - `orb` number, double
    - `type` 'parallel' | 'contraparallel'
  - `success` boolean

## Other responses

- `422`: Unprocessable Entity - Invalid input
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)