# Constellations API
> The 88 modern IAU constellations as an API — the reference an astronomy app, planetarium or education tool needs. For each constellation: its official IAU abbreviation, English name, the Latin genitive used when naming stars (e.g. "Alpha Andromedae"), a size rank, the approximate centre in equatorial coordinates (right ascension / declination) and the constellation name in roughly 25 languages. Look one up by abbreviation or name, search across every language, find which constellation a sky position falls nearest to, or list them all. Distinct from stars-api (individual stars) — this is the reference for the constellations themselves. Served from memory — always fast.

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

## Pricing
- **Free** (Free) — 15,000 calls/Mo, 3 req/s
- **Starter** ($4/Mo) — 150,000 calls/Mo, 8 req/s
- **Pro** ($13/Mo) — 700,000 calls/Mo, 20 req/s
- **Mega** ($32/Mo) — 3,500,000 calls/Mo, 50 req/s

## Endpoints

### Lookup

#### `GET /v1/constellation` — Constellation by abbreviation or name

**Parameters:**
- `abbr` (query, optional, string) — IAU abbreviation Example: `And`
- `name` (query, optional, string) — Constellation name Example: `Andromeda`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/constellations-api/v1/constellation?abbr=And&name=Andromeda"
```

**Response:**
```json
{
    "data": {
        "constellation": {
            "ra": 0.75,
            "dec": 43,
            "name": "Andromeda",
            "rank": "1",
            "names": {
                "ar": "المرأة المسلسلة",
                "cz": "Andromeda",
                "de": "Andromeda",
                "ee": "Andromeeda",
                "el": "Ανδρομέδα",
                "en": "Andromeda",
                "es": "Andrómeda",
                "fa": "زن به زنجیر بسته",
                "fi": "Andromeda",
                "fr": "Andromède",
                "he": "אנדרומדה",
                "hi": "देवयानी",
                "it": "Andromeda",
                "ja": "アンドロメダ座",
                "ko": "안드로메다자리",
                "la": "Andromeda",
                "ru": "Андромеда",
                "sw": "Mara",
                "tr": "Andromeda",
                "zh": "仙女座"
            },
            "genitive": "Andromedae",
            "abbreviation": "And"
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.575Z",
        "request_id": "81dcebba-9703-46a9-8dde-35b95b160f18"
    },
    "status": "ok",
    "message": "Constellation retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search constellations across languages

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `orion`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/constellations-api/v1/search?q=orion&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "query": "orion",
        "total": 1,
        "constellations": [
            {
                "ra": 84,
                "dec": 13,
                "name": "Orion",
                "rank": "1",
                "names": {
                    "ar": "الجبار",
                    "cz": "Orion",
                    "de": "Orion",
                    "ee": "Orion",
                    "el": "Ωρίων",
                    "en": "Orion",
                    "es": "Orión",
                    "fa": "شکارچی",
                    "fi": "Orion",
                    "fr": "Orion",
                    "he": "אוריון",
                    "hi": "मृग",
                    "it": "Orione",
                    "ja": "オリオン座",
                    "ko": "오리온자리",
                    "la": "Orion",
                    "ru": "Орион",
                    "sw": "Jabari",
                    "tr": "Avcı",
                    "zh": "獵戶座"
                },
                "genitive": "Orionis",
                "abbreviation": "Ori"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.697Z",
        "request_id": "f7668440-dcc2-4167-8c76-fdc58a39234f"
    },
    "status": "ok",
    "message": "Search results retrieved successfully",
    "success": true
}
```

### Geo

#### `GET /v1/point` — Constellation nearest a sky position

**Parameters:**
- `ra` (query, required, string) — Right ascension (0-360 degrees) Example: `85`
- `dec` (query, required, string) — Declination (-90..90) Example: `-1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/constellations-api/v1/point?ra=85&dec=-1"
```

**Response:**
```json
{
    "data": {
        "ra": 85,
        "dec": -1,
        "nearest": {
            "ra": 84,
            "dec": 13,
            "name": "Orion",
            "rank": "1",
            "names": {
                "ar": "الجبار",
                "cz": "Orion",
                "de": "Orion",
                "ee": "Orion",
                "el": "Ωρίων",
                "en": "Orion",
                "es": "Orión",
                "fa": "شکارچی",
                "fi": "Orion",
                "fr": "Orion",
                "he": "אוריון",
                "hi": "मृग",
                "it": "Orione",
                "ja": "オリオン座",
                "ko": "오리온자리",
                "la": "Orion",
                "ru": "Орион",
                "sw": "Jabari",
                "tr": "Avcı",
                "zh": "獵戶座"
            },
            "genitive": "Orionis",
            "abbreviation": "Ori"
        },
        "separation_deg": 14.04
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.827Z",
        "request_id": "8361b8d9-4705-423e-a5d5-480a7d610297"
    },
    "status": "ok",
    "message": "Nearest constellation retrieved successfully",
    "success": true
}
```

### List

#### `GET /v1/list` — List all constellations

**Parameters:**
- `limit` (query, optional, string) — Page size (1-100) Example: `88`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/constellations-api/v1/list?limit=88&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 88,
        "total": 88,
        "constellations": [
            {
                "ra": 0.75,
                "dec": 43,
                "name": "Andromeda",
                "rank": "1",
                "names": {
                    "ar": "المرأة المسلسلة",
                    "cz": "Andromeda",
                    "de": "Andromeda",
                    "ee": "Andromeeda",
                    "el": "Ανδρομέδα",
                    "en": "Andromeda",
                    "es": "Andrómeda",
                    "fa": "زن به زنجیر بسته",
                    "fi": "Andromeda",
                    "fr": "Andromède",
                    "he": "אנדרומדה",
                    "hi": "देवयानी",
                    "it": "Andromeda",
                    "ja": "アンドロメダ座",
                    "ko": "안드로메다자리",
                    "la": "Andromeda",
                    "ru": "Андромеда",
                    "sw": "Mara",
                    "tr": "Andromeda",
                    "zh": "仙女座"
                },
                "genitive": "Andromedae",
                "abbreviation": "And"
            },
            {
                "ra": 156,
                "dec": -36,
                "name": "Antlia",
                "rank": "3",
                "names": {
                    "ar": "مفرغة الهواء",
                    "cz": "Vývěva",

…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "service": "constellations-api",
        "endpoints": {
            "GET /v1/list": "List all constellations (limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/point": "The constellation nearest a sky position (ra=0..360, dec=-90..90).",
            "GET /v1/search": "Search constellations by name in any language, abbreviation or genitive (q=).",
            "GET /v1/constellation": "Constellation by IAU abbreviation (abbr=, e.g. And) or name (name=, e.g. Andromeda)."
        },
        "description": "The 88 modern IAU constellations: IAU abbreviation, English name, Latin genitive, rank, approximate equatorial centre (RA/Dec) and the name in ~25 languages. Look up by abbreviation or name, search across languages, find the constellation nearest a sky position, or list them all. No key.",
        "total_constellations": 88
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:11.086Z",
        "request_id": "9e712c1f-ba9e-4f5b-b464-e324ad1efa57"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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