---
title: "Eclipses"
method: POST
path: "/v1/western/eclipses"
tags: ["Western Astrology"]
---

# Eclipses

`POST /v1/western/eclipses`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/western/eclipses`
- Auth: HTTP bearer

Solar and lunar eclipses in a date range, past or future, up to 10 years. Each gives the type, time of greatest eclipse, start and end (UTC) and the eclipse degree in the tropical zodiac (Swiss Ephemeris). Add birth data to get, for each eclipse, the natal planets and angles within 3° of the eclipse degree by conjunction or opposition. Without a birth time the Ascendant and MC are skipped and the natal Moon is approximate.

## Request body

- EclipsesRequest
  - `from_date` string, required: First day of the range (YYYY-MM-DD, UTC).
  - `to_date` string, required: Last day of the range (YYYY-MM-DD, UTC, inclusive). At most 10 years after from_date.
  - `birth` BirthInput
    - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
    - `name` string: Person name associated with the birth record
    - `date` string, required: Birth date in YYYY-MM-DD format
    - `time` string, nullable: Birth time in HH:MM 24-hour format. If omitted, sunrise chart is used as fallback.
    - `latitude` number, nullable: Latitude. Required if location not provided.
    - `longitude` number, nullable: Longitude. Required if location not provided.
    - `timezone` string, nullable: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.
    - `utc_offset` string, nullable: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.
    - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations
  - `house_system` 'placidus' | 'koch' | 'equal' | 'whole_sign': House system used to compute the natal Ascendant and MC.

## Response `200`

Successful Response

- ApiResponseEclipsesResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` EclipsesResponse, required
    - `from_date` string, required
    - `to_date` string, required
    - `orb_degrees` number, required: Orb used for natal contacts.
    - `birth_data_provided` boolean, required
    - `birth_time_provided` boolean, required: False when no birth time: Ascendant and MC are not checked and the natal Moon is approximate.
    - `angles_checked` boolean, required: True when the natal Ascendant and MC were included in the contact check.
    - `eclipses` EclipseEventSchema[], required
      - `kind` 'solar' | 'lunar', required
      - `type` string, required: Solar: total, annular, hybrid or partial. Lunar: total, partial or penumbral.
      - `max_utc` string, required: Moment of greatest eclipse, UTC.
      - `begin_utc` string, nullable: Start of the eclipse (partial phase; penumbral phase for penumbral lunar eclipses), UTC.
      - `end_utc` string, nullable: End of the eclipse, UTC.
      - `sun_longitude` number, required: Tropical longitude of the Sun at maximum.
      - `moon_longitude` number, required: Tropical longitude of the Moon at maximum.
      - `eclipse_longitude` number, required: The eclipse degree: Sun for a solar eclipse, Moon for a lunar one.
      - `sign` string, required
      - `sign_index` integer, required
      - `degree_in_sign` number, required
      - `natal_contacts` EclipseNatalContact[]: Natal points within 3° of the eclipse degree (empty without birth data).
        - `natal_point` string, required: Natal planet, Ascendant or MC.
        - `natal_longitude` number, required
        - `aspect` 'conjunction' | 'opposition', required: How the eclipse degree meets the natal point: same degree (conjunction) or opposite (opposition).
        - `orb` number, required: Distance from exact, in degrees (0–3).

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)