# Astronomy API
> A fast, fully-local astronomy and ephemeris engine: compute the equatorial (right-ascension/declination) and horizontal (azimuth/altitude) positions of the Sun, Moon and all planets for any observer and moment, get precise rise, set and transit (culmination) times for any body, read detailed lunar state (phase angle, named phase, illuminated fraction, apparent magnitude, geocentric distance, age since the last new moon and the dates of the next new/first-quarter/full/last-quarter moons), and list the exact equinoxes and solstices of any year. Every endpoint accepts input via the query string or the request body. Pure server-side computation (no third-party upstream), so responses are instant and always available. Ideal for weather and tide apps, astrophotography planners, calendars, solar/energy tools, Islamic and lunar calendars, and education.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/astronomy-api/..."
```

## Pricing
- **Free** (Free) — 10,000 calls/Mo, 2 req/s
- **Basic** ($9/Mo) — 150,000 calls/Mo, 10 req/s
- **Pro** ($29/Mo) — 1,000,000 calls/Mo, 25 req/s
- **Mega** ($79/Mo) — 5,000,000 calls/Mo, 100 req/s

## Endpoints

### Astronomy

#### `GET /v1/moon` — Detailed lunar phase & next phases

**Parameters:**
- `date` (query, optional, string) — ISO-8601 instant (default now)
- `lat` (query, optional, string) — Observer latitude (optional, adds position) Example: `52.52`
- `lon` (query, optional, string) — Observer longitude (optional) Example: `13.405`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/astronomy-api/v1/moon?lat=52.52&lon=13.405"
```

#### `GET /v1/positions` — Body positions (equatorial + horizontal)

**Parameters:**
- `lat` (query, required, string) — Observer latitude Example: `52.52`
- `lon` (query, required, string) — Observer longitude Example: `13.405`
- `date` (query, optional, string) — ISO-8601 instant (default now)
- `bodies` (query, optional, string) — CSV of bodies Example: `sun,moon,mars`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/astronomy-api/v1/positions?lat=52.52&lon=13.405&bodies=sun%2Cmoon%2Cmars"
```

#### `GET /v1/rise-set` — Rise, set and transit for a body

**Parameters:**
- `body` (query, optional, string) — Body (default sun) Example: `sun`
- `lat` (query, required, string) — Observer latitude Example: `52.52`
- `lon` (query, required, string) — Observer longitude Example: `13.405`
- `date` (query, optional, string) — Day to search (default today) Example: `2026-06-21`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/astronomy-api/v1/rise-set?body=sun&lat=52.52&lon=13.405&date=2026-06-21"
```

#### `GET /v1/seasons` — Equinoxes & solstices of a year

**Parameters:**
- `year` (query, optional, string) — Year 1700..2200 (default current) Example: `2026`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/astronomy-api/v1/seasons?year=2026"
```


---
Marketplace page: https://www.oanor.com/api/astronomy-api
OpenAPI spec: https://www.oanor.com/api/astronomy-api/openapi.json