{"openapi":"3.1.0","info":{"title":"Stars API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/stars-api","description":"oanor gateway"}],"tags":[{"name":"Stars"},{"name":"Constellations"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/brightest":{"get":{"operationId":"get_v1_brightest","tags":["Stars"],"summary":"Brightest stars (overall or in a constellation)","description":"","parameters":[{"name":"constellation","in":"query","required":false,"description":"Constellation code or name","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many (1-100, default 10)","schema":{"type":"string"},"example":"10"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":10,"stars":[{"id":0,"ra":0,"dec":0,"name":"Sol","magnitude":-26.7,"abs_magnitude":4.85,"spectral_class":"G2V"},{"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":14.26103,"dec":19.18241,"hip":"69673","name":"Arcturus","bayer":"16Alp Boo","magnitude":-0.05,"distance_ly":36.72,"abs_magnitude":-0.307,"constellation":"Boo","spectral_class":"K2IIIp","constellation_name":"Bootes"},{"id":71456,"ra":14.660765,"dec":-60.833976,"hip":"71683","name":"Rigil Kentaurus","bayer":"Alp1Cen","magnitude":-0.01,"distance_ly":4.32,"abs_magnitude":4.379,"constellation":"Cen","spectral_class":"G2V","constellation_name":"Centaurus"},{"id":90979,"ra":18.61564,"dec":38.783692,"hip":"91262","name":"Vega","bayer":"3Alp Lyr","magnitude":0.03,"distance_ly":25.04,"abs_magnitude":0.604,"constellation":"Lyr","spectral_class":"A0Vvar","constellation_name":"Lyra"},{"id":24549,"ra":5.27815,"dec":45.997991,"hip":"24608","name":"Capella","bayer":"13Alp Aur","magnitude":0.08,"distance_ly":42.8,"abs_magnitude":-0.51,"constellation":"Aur","spectral_class":"M1: comp","constellation_name":"Auriga"},{"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":37173,"ra":7.655033,"dec":5.224993,"hip":"37279","name":"Procyon","bayer":"10Alp CMi","magnitude":0.4,"distance_ly":11.46,"abs_magnitude":2.671,"constellation":"CMi","spectral_class":"F5IV-V","constellation_name":"Canis Minor"},{"id":7574,"ra":1.628556,"dec":-57.236757,"hip":"7588","name":"Achernar","bayer":"Alp Eri","magnitude":0.45,"distance_ly":139.44,"abs_magnitude":-2.705,"constellation":"Eri","spectral_class":"B3Vp","constellation_name":"Eridanus"}]},"meta":{"timestamp":"2026-05-31T02:18:48.127Z","request_id":"37d0ae3e-0604-40ed-b554-1d60f1d7efe1"},"status":"ok","message":"Brightest stars","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["Stars"],"summary":"Search & filter stars","description":"","parameters":[{"name":"q","in":"query","required":false,"description":"Name / Bayer designation (substring)","schema":{"type":"string"}},{"name":"constellation","in":"query","required":false,"description":"Constellation code (Ori) or name (Orion)","schema":{"type":"string"},"example":"Orion"},{"name":"max_magnitude","in":"query","required":false,"description":"Only stars brighter than this magnitude","schema":{"type":"string"},"example":"3"},{"name":"named","in":"query","required":false,"description":"Only stars with a proper name (true/false)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page (1-100, default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":8,"limit":20,"total":8,"offset":0,"filters":{"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,"abs_magnitude":-2.804,"constellation":"Ori","spectral_class":"B2III","constellation_name":"Orion"},{"id":26246,"ra":5.603559,"dec":-1.20192,"hip":"26311","name":"Alnilam","bayer":"46Eps Ori","magnitude":1.69,"distance_ly":1976.7,"abs_magnitude":-7.223,"constellation":"Ori","spectral_class":"B0Ia","constellation_name":"Orion"},{"id":26662,"ra":5.679313,"dec":-1.942572,"hip":"26727","name":"Alnitak","bayer":"50Zet Ori","magnitude":1.74,"distance_ly":736.24,"abs_magnitude":-5.028,"constellation":"Ori","spectral_class":"O9.5Ib SB","constellation_name":"Orion"},{"id":27298,"ra":5.795941,"dec":-9.669605,"hip":"27366","name":"Saiph","bayer":"53Kap Ori","magnitude":2.07,"distance_ly":647.13,"abs_magnitude":-4.418,"constellation":"Ori","spectral_class":"B0.5Iavar","constellation_name":"Orion"},{"id":25865,"ra":5.533445,"dec":-0.299092,"hip":"25930","name":"Mintaka","bayer":"34Del Ori","magnitude":2.25,"distance_ly":692.48,"abs_magnitude":-4.385,"constellation":"Ori","spectral_class":"O9.5II","constellation_name":"Orion"},{"id":26176,"ra":5.590551,"dec":-5.909901,"hip":"26241","name":"Hatysa","bayer":"44Iot Ori","magnitude":2.75,"distance_ly":2329.69,"abs_magnitude":-6.519,"constellation":"Ori","spectral_class":"O9III","constellation_name":"Orion"}]},"meta":{"timestamp":"2026-05-31T02:18:48.195Z","request_id":"94ea24b7-ade9-4e6f-b302-9dcaeb9cf394"},"status":"ok","message":"Search completed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/star":{"get":{"operationId":"get_v1_star","tags":["Stars"],"summary":"A single star by name or id","description":"","parameters":[{"name":"name","in":"query","required":false,"description":"Star name, e.g. Sirius","schema":{"type":"string"},"example":"Sirius"},{"name":"id","in":"query","required":false,"description":"HYG id (alternative to name)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/constellations":{"get":{"operationId":"get_v1_constellations","tags":["Constellations"],"summary":"The 88 constellations with star counts","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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","stars":104},{"code":"CVn","name":"Canes Venatici","stars":61},{"code":"CMa","name":"Canis Major","stars":149},{"code":"CMi","name":"Canis Minor","stars":48},{"code":"Cap","name":"Capricornus","stars":83},{"code":"Car","name":"Carina","stars":227},{"code":"Cas","name":"Cassiopeia","stars":161},{"code":"Cen","name":"Centaurus","stars":287},{"code":"Cep","name":"Cepheus","stars":159},{"code":"Cet","name":"Cetus","stars":200},{"code":"Cha","name":"Chamaeleon","stars":33},{"code":"Cir","name":"Circinus","stars":40},{"code":"Col","name":"Columba","stars":68},{"code":"Com","name":"Coma Berenices","stars":69},{"code":"CrA","name":"Corona Australis","stars":46},{"code":"CrB","name":"Corona Borealis","stars":39},{"code":"Crv","name":"Corvus","stars":28},{"code":"Crt","name":"Crater","stars":34},{"code":"Cru","name":"Crux","stars":47},{"code":"Cyg","name":"Cygnus","stars":276},{"code":"Del","name":"Delphinus","stars":43},{"code":"Dor","name":"Dorado","stars":30},{"code":"Dra","name":"Draco","stars":220},{"code":"Equ","name":"Equuleus","stars":18},{"code":"Eri","name":"Eridanus","stars":199},{"code":"For","name":"Fornax","stars":63},{"code":"Gem","name":"Gemini","stars":119},{"code":"Gru","name":"Grus","stars":58},{"code":"Her","name":"Hercules","stars":246},{"code":"Hor","name":"Horologium","stars":32},{"code":"Hya","name":"Hydra","stars":245},{"code":"Hyi","name":"Hydrus","stars":34},{"code":"Ind","name":"Indus","stars":45},{"code":"Lac","name":"Lacerta","stars":69},{"code":"Leo","name":"Leo","stars":128},{"code":"LMi","name":"Leo Minor","stars":38},{"code":"Lep","name":"Lepus","stars":73},{"code":"Lib","name":"Libra","stars":88},{"code":"Lup","name":"Lupus","stars":124},{"code":"Lyn","name":"Lynx","stars":102},{"code":"Lyr","name":"Lyra","stars":71},{"code":"Men","name":"Mensa","stars":24},{"code":"Mic","name":"Microscopium","stars":44},{"code":"Mon","name":"Monoceros","stars":142},{"code":"Mus","name":"Musca","stars":63},{"code":"Nor","name":"Norma","stars":44},{"code":"Oct","name":"Octans","stars":60},{"code":"Oph","name":"Ophiuchus","stars":183},{"code":"Ori","name":"Orion","stars":204},{"code":"Pav","name":"Pavo","stars":88},{"code":"Peg","name":"Pegasus","stars":183},{"code":"Per","name":"Perseus","stars":163},{"code":"Phe","name":"Phoenix","stars":75},{"code":"Pic","name":"Pictor","stars":50},{"code":"Psc","name":"Pisces","stars":152},{"code":"PsA","name":"Piscis Austrinus","stars":48},{"code":"Pup","name":"Puppis","stars":245},{"code":"Pyx","name":"Pyxis","stars":43},{"code":"Ret","name":"Reticulum","stars":24},{"code":"Sge","name":"Sagitta","stars":27},{"code":"Sgr","name":"Sagittarius","stars":199},{"code":"Sco","name":"Scorpius","stars":174},{"code":"Scl","name":"Sculptor","stars":56},{"code":"Sct","name":"Scutum","stars":32},{"code":"Ser","name":"Serpens","stars":115},{"code":"Sex","name":"Sextans","stars":40},{"code":"Tau","name":"Taurus","stars":225},{"code":"Tel","name":"Telescopium","stars":56},{"code":"Tri","name":"Triangulum","stars":25},{"code":"TrA","name":"Triangulum Australe","stars":35},{"code":"Tuc","name":"Tucana","stars":49},{"code":"UMa","name":"Ursa Major","stars":218},{"code":"UMi","name":"Ursa Minor","stars":40},{"code":"Vel","name":"Vela","stars":220},{"code":"Vir","name":"Virgo","stars":177},{"code":"Vol","name":"Volans","stars":34},{"code":"Vul","name":"Vulpecula","stars":71}]},"meta":{"timestamp":"2026-05-31T02:18:48.324Z","request_id":"c40db637-d169-4a81-a7d7-86066de4a79c"},"status":"ok","message":"Constellations retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Totals & source","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":2500,"rps_limit":3,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":500,"monthly_call_quota":50000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1400,"monthly_call_quota":300000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3600,"monthly_call_quota":1400000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/stars-api"}