Docs/APIs/Stars Lookup

Stars Lookup

Lookup star data

OperationalCredits 2 per callp50 131msScienceStar

Overview

A `name` query matches the whole star name, ignoring case, accents, spacing and the degree sign, and treating Gliese, GJ and Gl as the same prefix, so `Xi Bootis` finds `Xi Boötis` and `Gliese 618 B` finds `Gl 618 B`. Partial names are not matched, and an unknown name returns 404.

A `type` query is matched in three steps, and the first step with results wins. First, an exact spectral code, with or without brackets and spaces, so `A1V` matches `A1(V)`. Second, a class name mapped to the luminosity suffix stored in the data: `supergiant` (I), `bright giant` (II), `giant` (III), `subgiant` (IV), `main sequence` or `dwarf` (V), `red dwarf` (M-type V) and `white dwarf` (wd); spaces, hyphens and a trailing `star` or `stars` are ignored. Third, a spectral class prefix such as `G`, `K5` or `DA`. Stars without a recorded type are skipped. For a type query, the first match is returned at the top level and `stars` lists up to the first 10 matches in catalogue order; `count` is the length of that list, not the total number of matches.

`mass` is in kilograms and `dist` in light-years. `starType` is the spectral code with the luminosity class in brackets, such as `A1(V)`. `temp` is the effective surface temperature in Kelvin and `diameter` the diameter in kilometres (see below), `color` a hex colour written as `0xRRGGBB`, and `galX`, `galY` and `galZ` are galactic coordinates whose combined length matches `dist`. `diameter`, `temp`, `color` and the three coordinates are null on the Free plan.

The catalogue is a list of about 2,600 nearby and named stars. Each month it is cross-matched against the HYG star database (v4.x, by David Nash / astronexus, codeberg.org/astronexus/hyg, licensed CC BY-SA 4.0), which combines the Hipparcos, Yale Bright Star and Gliese catalogues. A star is matched by its proper name or by its Bayer, Flamsteed, variable-star or Gliese designation, and only when HYG's distance agrees with the stored one. For matched stars, `temp` is derived from the measured B-V colour index with the Ballesteros (2012) formula; for O and B stars, whose B-V colour barely changes with temperature, the temperature that goes with the spectral type is kept. `diameter` is then derived from HYG's luminosity, converted from visual to bolometric with the Flower (1996) bolometric correction, and the temperature, using the Stefan-Boltzmann law (D = 2 R☉ × √L × (5772 K / T)²). The Sun keeps its measured values (1,392,000 km, 5772 K).

Derived diameters are estimates. Checked against measured sizes, Sirius, Vega, Procyon, Rigel and Arcturus land within 15%; red dwarfs such as Proxima Centauri and Barnard's Star come out at about half their true size, and distant giants and supergiants (Betelgeuse, Antares, Deneb, Aldebaran, Polaris) can be off by 30-70%, because their colours and distances are the least certain. Stars that cannot be matched keep their catalogue values, and `diameter` is null where no diameter is known. `mass` is null for stars with no recorded mass, which includes Polaris, Canopus and most white dwarfs. Mass, distance, coordinates, spectral type and colour are not taken from HYG.

Live Test Stars Lookup API →

Endpoint

One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.

GEThttps://api.apiverve.com/v1/starslookup
curl "https://api.apiverve.com/v1/starslookup?name=Sirius" \
  -H "x-api-key: your_api_key_here"

Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.

Authentication

Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.

401 is the only auth verdict

A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.

Parameters

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.

ParameterTypeDescription
nameRequiredstringThe name of the star (e.g., Sirius). IAU proper names (Rigil Kentaurus), Bayer designations (Alpha Orionis or alf Ori), Flamsteed numbers (58 Ori), HD and HIP numbers (HD 48915) and common names (Sun, North Star) are also accepted

Response

Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.

Sample response
{
  "status": "ok",
  "error": null,
  "data": {
    "starName": "Sirius",
    "mass": 4.674385e+30,
    "diameter": 2825760,
    "galX": -5.895,
    "galY": -6.152,
    "galZ": -1.167,
    "dist": 8.6,
    "starType": "A1(V)",
    "temp": 9500,
    "color": "0xbaccff"
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

FieldTypeExampleDescription
starNamestring"Sirius"The name of the star
massnumber4.674385e+30Mass of the star in kilograms; null when no mass is recorded
diameterPremiumnumber2825760Diameter of the star in kilometers
galXPremiumnumber-5.895Galactic X coordinate position
galYPremiumnumber-6.152Galactic Y coordinate position
galZPremiumnumber-1.167Galactic Z coordinate position
distnumber8.6Distance to star in light-years
starTypestring"A1(V)"Stellar classification type (e.g., A1V)
tempPremiumnumber9500Surface temperature of the star in Kelvin
colorPremiumstring"0xbaccff"Color representation as hex code

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.

StatusMeaningWhat to do
400Input was rejectedRead error; it names the parameter.
401Key missing or invalidCheck the header name and the key value.
403Key valid, but not permittedA key restriction or IP allow-list; see key scoping.
429Rate limited, or out of creditsRead error to tell them apart; see rate limits.

Use cases

Planetarium Display Systems
Stargazing apps query star names to show visitors distance from Earth, stellar classification, and real celestial mass during live sky tours.
Sci-Fi Worldbuilding
To build believable galaxy maps, game developers pull spectral classes like red dwarf or main sequence to seed star systems with authentic physics.
Astronomy Curriculum Portals
When students compare celestial bodies, digital textbooks pull mass in kilograms and stellar types to demonstrate the Hertzsprung-Russell relationship.
Telescope Calibration Software
Align optical tracking mounts by looking up known reference stars to verify catalog identity and light-year distance against visual field observations.

Other ways to use Stars Lookup

Set up Stars Lookup on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.

Give it to an AI agentConnect over MCP and your agent calls it as a native tool — Claude, Cursor, ChatGPT.VerveKit →Reference →
Google Sheets or ExcelA =VERVE() formula fills a column — no script, no export, recalculates in place.VerveSheets →Reference →
Ground an agent on itA cited, machine-checkable fact your model can't produce on its own.VerveContext →Reference →

More in Science:

Was this page helpful?