# Stars API > A catalogue of 9,000+ stars — every named star plus all naked-eye stars to magnitude 6.5 — from the HYG database. Look up a star by name, search and filter by constellation and brightness, list the brightest stars (overall or per constellation), and browse all 88 constellations. Each star includes its constellation, apparent and absolute magnitude, spectral class, distance in light-years and coordinates. Great for astronomy, education and stargazing apps. ## 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/stars-api/..." ``` ## Pricing - **Free** (Free) — 2,500 calls/Mo, 3 req/s - **Starter** ($5/Mo) — 50,000 calls/Mo, 8 req/s - **Pro** ($14/Mo) — 300,000 calls/Mo, 20 req/s - **Mega** ($36/Mo) — 1,400,000 calls/Mo, 40 req/s ## Endpoints ### Stars #### `GET /v1/brightest` — Brightest stars (overall or in a constellation) **Parameters:** - `constellation` (query, optional, string) — Constellation code or name - `limit` (query, optional, string) — How many (1-100, default 10) Example: `10` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/stars-api/v1/brightest?limit=10" ``` **Response:** ```json { "data": { "count": 10, "stars": [ { "id": 0, "ra": 0, "dec": 0, "hip": null, "name": "Sol", "bayer": null, "magnitude": -26.7, "distance_ly": null, "abs_magnitude": 4.85, "constellation": null, "spectral_class": "G2V", "constellation_name": null }, { "id": 32263, "ra": 6.752481, "dec": -16.716116, "hip": "32349", "name": "Sirius", "bayer": "9Alp CMa", "magnitude": -1.44, "distance_ly": 8.6, "abs_magnitude": 1.454, "constellation": "CMa", "spectral_class": "A0m...", "constellation_name": "Canis Major" }, { "id": 30365, "ra": 6.399195, "dec": -52.69566, "hip": "30438", "name": "Canopus", "bayer": "Alp Car", "magnitude": -0.62, "distance_ly": 309.15, "abs_magnitude": -5.504, "constellation": "Car", "spectral_class": "F0Ib", "constellation_name": "Carina" }, { "id": 69451, "ra": …(truncated, see openapi.json for full schema) ``` #### `GET /v1/search` — Search & filter stars **Parameters:** - `q` (query, optional, string) — Name / Bayer designation (substring) - `constellation` (query, optional, string) — Constellation code (Ori) or name (Orion) Example: `Orion` - `max_magnitude` (query, optional, string) — Only stars brighter than this magnitude Example: `3` - `named` (query, optional, string) — Only stars with a proper name (true/false) - `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20` - `offset` (query, optional, string) — Pagination offset Example: `0` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/stars-api/v1/search?constellation=Orion&max_magnitude=3&limit=20&offset=0" ``` **Response:** ```json { "data": { "count": 8, "limit": 20, "total": 8, "offset": 0, "filters": { "q": null, "named": false, "constellation": "Ori", "max_magnitude": 3 }, "results": [ { "id": 24378, "ra": 5.242298, "dec": -8.20164, "hip": "24436", "name": "Rigel", "bayer": "19Bet Ori", "magnitude": 0.18, "distance_ly": 862.85, "abs_magnitude": -6.933, "constellation": "Ori", "spectral_class": "B8Ia", "constellation_name": "Orion" }, { "id": 27919, "ra": 5.919529, "dec": 7.407063, "hip": "27989", "name": "Betelgeuse", "bayer": "58Alp Ori", "magnitude": 0.45, "distance_ly": 497.95, "abs_magnitude": -5.469, "constellation": "Ori", "spectral_class": "M2Ib", "constellation_name": "Orion" }, { "id": 25273, "ra": 5.418851, "dec": 6.349702, "hip": "25336", "name": "Bellatrix", "bayer": "24Gam Ori", "magnitude": 1.64, "distance_ly": 252.44, …(truncated, see openapi.json for full schema) ``` #### `GET /v1/star` — A single star by name or id **Parameters:** - `name` (query, optional, string) — Star name, e.g. Sirius Example: `Sirius` - `id` (query, optional, string) — HYG id (alternative to name) **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/stars-api/v1/star?name=Sirius" ``` **Response:** ```json { "data": { "id": 32263, "ra": 6.752481, "dec": -16.716116, "hip": "32349", "name": "Sirius", "bayer": "9Alp CMa", "magnitude": -1.44, "distance_ly": 8.6, "abs_magnitude": 1.454, "constellation": "CMa", "spectral_class": "A0m...", "constellation_name": "Canis Major" }, "meta": { "timestamp": "2026-05-31T02:18:48.264Z", "request_id": "48d38efa-7188-468a-acaa-4069e09de660" }, "status": "ok", "message": "Star retrieved", "success": true } ``` ### Constellations #### `GET /v1/constellations` — The 88 constellations with star counts **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/stars-api/v1/constellations" ``` **Response:** ```json { "data": { "count": 88, "constellations": [ { "code": "And", "name": "Andromeda", "stars": 158 }, { "code": "Ant", "name": "Antlia", "stars": 44 }, { "code": "Aps", "name": "Apus", "stars": 40 }, { "code": "Aqr", "name": "Aquarius", "stars": 179 }, { "code": "Aql", "name": "Aquila", "stars": 128 }, { "code": "Ara", "name": "Ara", "stars": 73 }, { "code": "Ari", "name": "Aries", "stars": 85 }, { "code": "Aur", "name": "Auriga", "stars": 160 }, { "code": "Boo", "name": "Bootes", "stars": 150 }, { "code": "Cae", "name": "Caelum", "stars": 20 }, { "code": "Cam", "name": "Camelopardalis", "stars": 157 }, { "code": "Cnc", "name": "Cancer", …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Totals & source **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/stars-api/v1/meta" ``` **Response:** ```json { "data": { "named": 465, "total": 9027, "fields": [ "id", "name", "bayer", "constellation", "constellation_name", "magnitude", "abs_magnitude", "spectral_class", "distance_ly", "ra", "dec", "hip" ], "source": "HYG Database (named stars + all stars to magnitude 6.5)", "constellations": 88, "magnitude_limit": 6.5 }, "meta": { "timestamp": "2026-05-31T02:18:48.393Z", "request_id": "2a5476b8-a4aa-4856-9707-592f97885562" }, "status": "ok", "message": "Meta retrieved", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/stars-api OpenAPI spec: https://www.oanor.com/api/stars-api/openapi.json