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.
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.
curl "https://api.apiverve.com/v1/starslookup?name=Sirius" \
-H "x-api-key: your_api_key_here"const res = await fetch('https://api.apiverve.com/v1/starslookup?name=Sirius', {
headers: { 'x-api-key': 'your_api_key_here' },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data } = await res.json();
console.log(data);import requests
res = requests.get(
"https://api.apiverve.com/v1/starslookup?name=Sirius",
headers={"x-api-key": "your_api_key_here"},
timeout=15,
)
res.raise_for_status()
print(res.json()["data"])package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/starslookup?name=Sirius", nil)
req.Header.Set("x-api-key", "your_api_key_here")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}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.
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.
| Parameter | Type | Description |
|---|---|---|
nameRequired | string | The 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.
{
"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.
| Field | Type | Example | Description |
|---|---|---|---|
starName | string | "Sirius" | The name of the star |
mass | number | 4.674385e+30 | Mass of the star in kilograms; null when no mass is recorded |
diameterPremium | number | 2825760 | Diameter of the star in kilometers |
galXPremium | number | -5.895 | Galactic X coordinate position |
galYPremium | number | -6.152 | Galactic Y coordinate position |
galZPremium | number | -1.167 | Galactic Z coordinate position |
dist | number | 8.6 | Distance to star in light-years |
starType | string | "A1(V)" | Stellar classification type (e.g., A1V) |
tempPremium | number | 9500 | Surface temperature of the star in Kelvin |
colorPremium | string | "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.
| Status | Meaning | What to do |
|---|---|---|
400 | Input was rejected | Read error; it names the parameter. |
401 | Key missing or invalid | Check the header name and the key value. |
403 | Key valid, but not permitted | A key restriction or IP allow-list; see key scoping. |
429 | Rate limited, or out of credits | Read 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.
Related
More in Science: