# Zodiac API
> Turn a birth date into zodiac signs as an API. Get the Western (tropical) sun sign for any date — its symbol, element (Fire, Earth, Air, Water), quality, ruling planet, polarity, key traits and the signs it is most compatible with (e.g. 15 July → Cancer, Water, ruled by the Moon). Look up a sign by name, get the Chinese zodiac animal, element and yin/yang for any year (e.g. 2020 → Metal Rat), or fetch both Western and Chinese signs from a full birth date at once. Everything is computed locally, so it is fast and always available. Ideal for horoscope and astrology apps, dating and matchmaking, onboarding personalisation, content sites and fun widgets.

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

## Pricing
- **Free** (Free) — 14,000 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 210,000 calls/Mo, 8 req/s
- **Pro** ($9/Mo) — 860,000 calls/Mo, 20 req/s
- **Mega** ($28/Mo) — 3,550,000 calls/Mo, 50 req/s

## Endpoints

### Zodiac

#### `GET /v1/both` — Western + Chinese for a full date

**Parameters:**
- `date` (query, required, string) — Full birth date YYYY-MM-DD, e.g. 1990-07-15 Example: `1990-07-15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/zodiac-api/v1/both?date=1990-07-15"
```

**Response:**
```json
{
    "data": {
        "date": "1990-07-15",
        "chinese": {
            "sign": "Horse",
            "year": 1990,
            "traits": [
                "energetic",
                "independent",
                "warm"
            ],
            "element": "Metal",
            "yin_yang": "Yang"
        },
        "western": {
            "sign": "Cancer",
            "symbol": "♋",
            "traits": [
                "nurturing",
                "loyal",
                "emotional",
                "protective"
            ],
            "element": "Water",
            "quality": "Cardinal",
            "polarity": "Negative",
            "date_range": "21 Jun – 22 Jul",
            "ruling_planet": "Moon",
            "compatible_with": [
                "Capricorn",
                "Pisces",
                "Taurus",
                "Virgo",
                "Scorpio"
            ]
        }
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:25.343Z",
        "request_id": "811fa765-e43b-45ee-a3ea-5d3c05b13594"
    },
    "status": "ok",
    "message": "Both signs retrieved",
    "success": true
}
```

#### `GET /v1/chinese` — Chinese zodiac from a year or date

**Parameters:**
- `year` (query, optional, string) — Birth year, e.g. 1990 Example: `1990`
- `date` (query, optional, string) — Or a full date YYYY-MM-DD

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

**Response:**
```json
{
    "data": {
        "note": "Uses the Gregorian year; births in January/early February may fall under the previous year's animal due to the lunar new year.",
        "sign": "Horse",
        "year": 1990,
        "traits": [
            "energetic",
            "independent",
            "warm"
        ],
        "element": "Metal",
        "yin_yang": "Yang"
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:25.421Z",
        "request_id": "8ddaec96-5cc7-4273-bf24-a8ebd9191a00"
    },
    "status": "ok",
    "message": "Chinese sign retrieved",
    "success": true
}
```

#### `GET /v1/sign` — Western sign details by name

**Parameters:**
- `name` (query, required, string) — Sign name, e.g. leo Example: `leo`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/zodiac-api/v1/sign?name=leo"
```

**Response:**
```json
{
    "data": {
        "sign": "Leo",
        "symbol": "♌",
        "traits": [
            "confident",
            "generous",
            "charismatic",
            "dramatic"
        ],
        "element": "Fire",
        "quality": "Fixed",
        "polarity": "Positive",
        "date_range": "23 Jul – 22 Aug",
        "ruling_planet": "Sun",
        "compatible_with": [
            "Aquarius",
            "Aries",
            "Gemini",
            "Libra",
            "Sagittarius"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:25.492Z",
        "request_id": "0beca6d8-0489-4059-9ff5-668a9978b234"
    },
    "status": "ok",
    "message": "Sign details retrieved",
    "success": true
}
```

#### `GET /v1/western` — Western sun sign from a date

**Parameters:**
- `date` (query, optional, string) — Birth date YYYY-MM-DD, e.g. 1990-07-15 Example: `1990-07-15`
- `month` (query, optional, string) — Month 1-12 (with day=, if no date)
- `day` (query, optional, string) — Day of month (with month=)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/zodiac-api/v1/western?date=1990-07-15"
```

**Response:**
```json
{
    "data": {
        "sign": "Cancer",
        "input": {
            "day": 15,
            "month": 7
        },
        "symbol": "♋",
        "traits": [
            "nurturing",
            "loyal",
            "emotional",
            "protective"
        ],
        "element": "Water",
        "quality": "Cardinal",
        "polarity": "Negative",
        "date_range": "21 Jun – 22 Jul",
        "ruling_planet": "Moon",
        "compatible_with": [
            "Capricorn",
            "Pisces",
            "Taurus",
            "Virgo",
            "Scorpio"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:25.561Z",
        "request_id": "f93bdfb8-9384-4a82-bcc1-869b867d32a7"
    },
    "status": "ok",
    "message": "Western sign retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Signs & usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/zodiac-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Zodiac signs. /v1/western = the Western (tropical) sun sign from a date (date=YYYY-MM-DD or month= & day=) with element, quality, ruling planet and compatible signs; /v1/sign = details for a sign by name (e.g. name=leo); /v1/chinese = the Chinese zodiac animal, element and yin/yang from a year or date; /v1/both = Western + Chinese for a full birth date. Runs fully locally.",
        "source": "local zodiac engine",
        "endpoints": [
            "/v1/western",
            "/v1/sign",
            "/v1/chinese",
            "/v1/both",
            "/v1/meta"
        ],
        "chinese_signs": [
            "Rat",
            "Ox",
            "Tiger",
            "Rabbit",
            "Dragon",
            "Snake",
            "Horse",
            "Goat",
            "Monkey",
            "Rooster",
            "Dog",
            "Pig"
        ],
        "western_signs": [
            "Capricorn",
            "Aquarius",
            "Pisces",
            "Aries",
            "Taurus",
            "Gemini",
            "Cancer",
            "Leo",
            "Virgo",
            "Libra",
            "Scorpio",
            "Sagittarius"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:25.631Z",
        "request_id": "8f659833-fb4e-4485-8a66-b989ba3565a6"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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