---
title: "Harmonic Chart Analysis"
method: POST
path: "/ephemeris/harmonics"
tags: ["ephemeris"]
---

# Harmonic Chart Analysis

`POST /ephemeris/harmonics`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/harmonics`
- 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`

Calculate harmonic chart positions by multiplying natal longitudes by a harmonic number N and reducing modulo 360°. Finds conjunctions in the harmonic space to reveal hidden aspect patterns.

Harmonic analysis is the mathematical backbone of aspect theory: the 5th harmonic unfolds quintiles, the 7th reveals septiles, the 9th produces the Vedic navamsa. Higher harmonics expose increasingly subtle geometric relationships invisible in a standard chart wheel.

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

## Query parameters

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

## Request body

- HarmonicsRequest
  - `bodies` HarmonicsRequestBody[], required: Array of celestial body positions with id and longitude.
    - `id` integer, required: Planet/body ID (e.g. 0=Sun, 1=Moon, …)
    - `longitude` number, required: Ecliptic longitude in decimal degrees [0, 360)
  - `harmonic` integer, required: Harmonic number (1–360). H1 = natal, H5 = quintile, H9 = navamsa.
  - `orb` number: Orb in degrees for conjunction detection in the harmonic chart.

## Response `200`

Successful Response

- HarmonicsResponse
  - `calculation_metadata` object: Metadata about the calculation
    - `computation_time_ms` number: Computation time in milliseconds
    - `engine` string: Calculation engine used
  - `conjunctions` HarmonicConjunction[]: Conjunctions found in the harmonic chart
    - `harmonic` integer: Harmonic number
    - `midpoint` number: Midpoint longitude of the conjunction
    - `orb` number: Angular separation in degrees
    - `planet1` integer: First planet ID
    - `planet2` integer: Second planet ID
  - `harmonic` integer: The harmonic number that was calculated
  - `positions` HarmonicPosition[]: Harmonic positions for each body
    - `harmonic` integer: Harmonic number used
    - `longitude` number: Harmonic longitude [0, 360)
    - `natal_longitude` number: Original natal longitude
    - `planet_id` integer: Planet/body ID
    - `planet_name` string: Human-readable planet name
    - `sign` string: Zodiac sign name at harmonic longitude
    - `sign_degree` number: Degree within sign [0, 30)
  - `significance` string: Astrological significance of this harmonic

## Other responses

- `422`: Validation Error
- `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)