# Moon API
> Everything about the Moon from one fast, fully-local API. Get the current (or any date) lunar phase with illumination percentage, age in days, phase angle and waxing/waning state, plus the matching emoji; list the upcoming principal phases (new, first quarter, full, last quarter) with accurate UTC timestamps; render a full monthly lunar calendar; and look up the Moon’s zodiac sign and ecliptic longitude. Phase instants are computed with Jean Meeus’ astronomical algorithms and are accurate to about a minute. Every endpoint takes an optional ISO date and works by GET or JSON POST. Pure server-side compute with no third-party upstream, so responses are instant and always available. Ideal for calendar and weather apps, photography and astronomy tools, gardening, fishing and astrology features.

## 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/moon-api/..."
```

## Pricing
- **Free** (Free) — 1,000 calls/Mo, 2 req/s
- **Basic** ($3/Mo) — 20,000 calls/Mo, 5 req/s
- **Pro** ($10/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($22/Mo) — 1,000,000 calls/Mo, 40 req/s

## Endpoints

### Moon

#### `GET /v1/astrology` — Moon zodiac sign (beta)

**Parameters:**
- `date` (query, optional, string) — ISO date/time (default: now) Example: `2026-01-03`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/moon-api/v1/astrology?date=2026-01-03"
```

**Response:**
```json
{
    "data": {
        "date": "2026-01-03T00:00:00.000Z",
        "note": "Tropical zodiac, geocentric mean longitude (beta, ~1° precision)",
        "emoji": "🌕",
        "phase": "Full Moon",
        "moon_sign": "Cancer",
        "degree_in_sign": 6.75,
        "ecliptic_longitude": 96.75,
        "illumination_percent": 99.2
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.288Z",
        "request_id": "78c9b461-92c2-47bf-8f52-18057fed7df4"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/calendar` — Monthly lunar calendar

**Parameters:**
- `year` (query, optional, string) — 1900-2100 (default: current) Example: `2026`
- `month` (query, optional, string) — 1-12 (default: current) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/moon-api/v1/calendar?year=2026&month=1"
```

**Response:**
```json
{
    "data": {
        "days": 31,
        "year": 2026,
        "month": 1,
        "calendar": [
            {
                "date": "2026-01-01",
                "emoji": "🌔",
                "phase": "Waxing Gibbous",
                "age_days": 12.43,
                "illumination_percent": 93.9
            },
            {
                "date": "2026-01-02",
                "emoji": "🌔",
                "phase": "Waxing Gibbous",
                "age_days": 13.43,
                "illumination_percent": 98
            },
            {
                "date": "2026-01-03",
                "emoji": "🌕",
                "phase": "Full Moon",
                "age_days": 14.43,
                "illumination_percent": 99.9
            },
            {
                "date": "2026-01-04",
                "emoji": "🌖",
                "phase": "Waning Gibbous",
                "age_days": 15.43,
                "illumination_percent": 99.5
            },
            {
                "date": "2026-01-05",
                "emoji": "🌖",
                "phase": "Waning Gibbous",
                "age_days": 16.43,
                "illumination_percent": 96.9
            },
            {
                "date": "2026-01-06",
                "emoji": "🌖",
                "phase": "Waning Gibbous",
                "age_days": 17.43,
                "illumination_percent": 92.2
            },
            {
                "date": "2026-01-07",
                "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/emoji` — Phase as emoji

**Parameters:**
- `date` (query, optional, string) — ISO date/time (default: now) Example: `2026-01-03`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/moon-api/v1/emoji?date=2026-01-03"
```

**Response:**
```json
{
    "data": {
        "date": "2026-01-03T00:00:00.000Z",
        "emoji": "🌕",
        "phase": "Full Moon",
        "illumination_percent": 99.2
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.446Z",
        "request_id": "2501c8ba-d124-46cb-b26a-c1848c604272"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/next` — Upcoming principal phases

**Parameters:**
- `date` (query, optional, string) — Start date (default: now) Example: `2026-01-03`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/moon-api/v1/next?date=2026-01-03"
```

**Response:**
```json
{
    "data": {
        "from": "2026-01-03T00:00:00.000Z",
        "next_phases": [
            {
                "date": "2026-01-03T10:03:05.620Z",
                "emoji": "🌕",
                "phase": "Full Moon"
            },
            {
                "date": "2026-01-10T15:49:40.980Z",
                "emoji": "🌗",
                "phase": "Last Quarter"
            },
            {
                "date": "2026-01-18T19:53:16.023Z",
                "emoji": "🌑",
                "phase": "New Moon"
            },
            {
                "date": "2026-01-26T04:48:33.776Z",
                "emoji": "🌓",
                "phase": "First Quarter"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.527Z",
        "request_id": "77f49761-6f33-4b27-b09e-b4c1f121fccc"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/phase` — Lunar phase for a date

**Parameters:**
- `date` (query, optional, string) — ISO date/time (default: now) Example: `2026-01-03`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/moon-api/v1/phase?date=2026-01-03"
```

**Response:**
```json
{
    "data": {
        "date": "2026-01-03T00:00:00.000Z",
        "emoji": "🌕",
        "phase": "Full Moon",
        "age_days": 13.93,
        "is_waxing": true,
        "phase_angle": 169.78,
        "cycle_fraction": 0.4716,
        "illumination_percent": 99.2
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.599Z",
        "request_id": "73400904-6255-4dac-b755-f37620264ad0"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


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