---
title: "Solar Eclipse Local Circumstances"
method: GET
path: "/eclipse/solar/local"
tags: ["eclipse"]
---

# Solar Eclipse Local Circumstances

`GET /eclipse/solar/local`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/eclipse/solar/local`
- 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`

Local circumstances for a specific observer: magnitude, obscuration, contact times (C1-C4), duration, and sun position. 🤖 AI-optimized output available — add `output_format=llm` to reduce payload ~55%.

## Query parameters

- `date` string, nullable
- `jd` number, double, nullable
- `lat` number, required: Observer latitude
- `lon` number, required: Observer longitude
- `elev` number: Observer elevation in meters
- `delta_t_model` string
- `output_format` string

## Response `200`

Solar eclipse local circumstances for observer

- SolarEclipseLocalResponse
  - `besselian_elements` BesselianElements, required
    - `X` number, required: Shadow axis x in fundamental plane
    - `Xdot` number
    - `Y` number, required: Shadow axis y in fundamental plane
    - `Ydot` number
    - `d` number, required: Declination of shadow axis (degrees)
    - `ddot` number
    - `f1` number, required: Penumbral cone half-angle (radians)
    - `f2` number, required: Umbral cone half-angle (radians)
    - `l1` number, required: Penumbral shadow radius
    - `l2` number, required: Umbral shadow radius
    - `mu` number, required: Hour angle of shadow axis (degrees)
    - `mudot` number
    - `reference_jd` number, double, required
    - `reference_time_utc` string, required
  - `eclipse_classification` EclipseClassification, required
    - `central_duration_seconds` number
    - `gamma` number, required
    - `greatest_magnitude` number
    - `inex_series` integer
    - `kind` 'solar' | 'lunar', required
    - `saros_member` integer
    - `saros_series` integer
    - `type` 'total' | 'annular' | 'hybrid' | 'partial' | 'penumbral', required
  - `local_circumstances` LocalCircumstances, required
    - `duration_seconds` number
    - `first_contact` string
    - `fourth_contact` string
    - `magnitude` number, required
    - `max_eclipse` string, required
    - `obscuration` number
    - `second_contact` string
    - `sun_altitude` number
    - `sun_azimuth` number
    - `third_contact` string
    - `type` 'total' | 'annular' | 'hybrid' | 'partial' | 'penumbral', required
  - `meta` CalculationMeta, required
    - `calculation_precision` string
    - `delta_t_model` string, required
    - `delta_t_seconds` number, required
    - `delta_t_uncertainty` number, required
    - `ephemeris` string, required
    - `julian_day` number, double, required
  - `safety` SafetyWarnings
    - `baileys_beads_visible` boolean
    - `corona_visible_duration` string
    - `eye_protection_required` boolean, required
    - `partial_phase_duration` string
    - `path_uncertainty_note` string
  - `uncertainty` UncertaintyInfo
    - `confidence` 'high' | 'medium' | 'low' | 'historical', required
    - `delta_t_uncertainty_seconds` number, required
    - `path_uncertainty_km` number
    - `timing_uncertainty` string

## Other responses

- `400`: Bad Request
- `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)