API Documentation

TheStarDB REST API

Query 33M+ astronomical objects 16M stars, 9.7M variable stars, 5.7M quasars, 997K deep-sky objects, pulsars, exoplanets, black holes, and more via a clean, versioned REST API. All responses are JSON. All endpoints are read-only.

33M+

Objects

Current Version

JSON

Response Format

HTTPS

Only

https://thestardb.org/api/v1

Authentication

All API requests require a valid API key passed in the X-API-Key header.

X-API-Key: YOUR_API_KEY

API access is included with Professional, Institution, and Academic memberships (generate keys from your account dashboard), or purchased as a standalone API plan. Keys are per-account, not per-user do not expose them in client-side JavaScript.

Rate Limits

Rate limits are applied per API key, per day (rolling 24h window). When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Starter API

requests / day

Standard API

requests / day

Professional API

10k

requests / day

Enterprise API

25k+

requests / day

Errors

All errors follow the same envelope format:

{
  "error": "not_found",
  "message": "No star found with id 99999",
  "status": 404
}

Code	Meaning
200	OK
400	Bad request invalid parameter value
401	Unauthorized missing or invalid API key
403	Forbidden your plan does not include this endpoint
404	Not found
429	Rate limit exceeded
500	Internal server error

Objects

GET /objects/stars/list List stars with filters

Returns a paginated list of stars matching the given filters. Default page size is 50, max 200.

Parameter	Type	Description
qopt	string	Search by name, Bayer designation, or constellation
spectopt	O,B,A,F,G,K,M	Filter by first letter of spectral class
constellationopt	string	IAU 3-letter code (Ori, UMa, Sco…)
max_magopt	float	Maximum apparent magnitude (brighter = lower)
max_dist_lyopt	float	Maximum distance in light-years
is_namedopt	bool	Only return IAU-named stars
has_exoplanetsopt	bool	Only return stars with confirmed exoplanets
sortopt	mag (default)	Sort field (default: mag)
pageopt	int	Page number (default: 1)
limitopt	int	Results per page, max 200 (default: 50)

# Example: all named K-type stars within 50 ly, sorted by brightness
GET /api/v1/objects/stars/list?spect=K&is_named=true&max_dist_ly=50&sort=mag

GET /objects/stars/:id Get a single star by ID

Returns complete data for one star by its numeric database ID.

GET /api/v1/objects/stars/1          # by numeric id

Pulsars

GET /objects/pulsars/list List all pulsars (ATNF catalogue)

Returns pulsars from the ATNF Pulsar Catalogue. Each record includes the pulse period in seconds, dispersion measure, and flux density at 400 MHz and 1400 MHz.

Parameter	Type	Description
max_periodopt	float	Maximum pulse period (seconds)
min_periodopt	float	Minimum pulse period (seconds)
constellationopt	string	IAU 3-letter code

# Millisecond pulsars (period < 0.03s)
GET /api/v1/objects/pulsars/list?max_period=0.03

Exoplanets

GET /objects/exoplanets/list List confirmed exoplanets (NASA Exoplanet Archive)

Returns confirmed exoplanets. Filter by host star, planet type, discovery method, or habitable zone.

Parameter	Type	Description
host_staropt	string	Host star name (partial match)
planet_typeopt	string	super_earth, neptune, jupiter, terrestrial
in_habitable_zoneopt	bool	Only return habitable-zone planets
discovery_methodopt	string	transit, radial_velocity, imaging, microlensing
min_discovery_yearopt	int	Filter by discovery year range

# Habitable-zone super-Earths
GET /api/v1/objects/exoplanets/list?planet_type=super_earth&in_habitable_zone=true

Constellations

GET /objects/constellations/list All 88 IAU constellations

Returns all 88 IAU constellations with name, genitive, area, quadrant, and brightest star. Append /Ori/stars to get all HYG stars within Orion.

GET /api/v1/objects/constellations/list   # all 88
GET /api/v1/objects/constellations/1     # by numeric id

Star Schema

Full field reference for a star object:

Star object JSON schema (excerpt)

{
  "id": 1,
  "source": "hyg",          // hyg | gaia | atnf | messier
  "source_id": "0",
  "name": "Sol",
  "alt_names": ["Sun"],
  "bayer": null,
  "flamsteed": null,
  "constellation": null,
  "ra": 0.0,               // J2000.0 decimal degrees
  "dec": 0.0,
  "dist_ly": 0.000016,     // light-years
  "dist_pc": 4.848e-9,     // parsecs
  "mag_apparent": -26.74,
  "mag_absolute": 4.83,
  "luminosity_sol": 1.0,
  "temperature": 5778,     // Kelvin
  "spectral_class": "G2V",
  "stellar_class": "G",
  "mass_sol": 1.0,
  "radius_sol": 1.0,
  "age_gyr": 4.6,
  "color_bv": 0.656,
  "pm_ra": -3.775,         // mas/yr
  "pm_dec": -20.0,
  "radial_vel": 0.0,       // km/s
  "has_exoplanets": true,
  "planet_count": 8,
  "is_named": true,
  "is_featured": true
}

SDK

A minimal, dependency-free JavaScript client covering every endpoint on this page. Works in the browser and in Node.js 18+.

<script src="https://thestardb.org/sdk/stardb-sdk.js"></script>
const sten = new StarDB('YOUR_API_KEY');

const stars = await sten.stars.list({ spect: 'K', is_named: true, max_dist_ly: 50 });
const sirius = await sten.stars.get(32263);
const pulsars = await sten.pulsars.list({ max_period: 0.03 });
const planets = await sten.exoplanets.list({ in_habitable_zone: true });
const orion = await sten.constellations.get(1);

In Node.js: const StarDB = require('./stardb-sdk.js') after downloading the file, or fetch it directly from the URL above at build time.

API Plans

API access is included with Professional, Institution, and Academic memberships, or available as a standalone API plan.

View API pricing →