API Documentation

TheStarDB REST API

Query 500,000+ stellar objects - stars, pulsars, black holes, neutron stars, and exoplanets - via a clean, versioned REST API. All responses are JSON. All endpoints are read-only.

500k+

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 Authorization header.

Authorization: Bearer YOUR_API_KEY

API keys are available on Education, Institution, and standalone API plans. Get your key from your account dashboard. 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

50k

requests / day

Institution / Enterprise

100k+

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

Stars

GET /stars 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
stellar_classopt	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,dist,name,temp	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/stars?stellar_class=K&is_named=true&max_dist_ly=50&sort=mag

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

Returns complete data for one star. The :id can be the numeric database ID, the HYG source ID (hyg:12345), or a Gaia source ID (gaia:DR3_1234).

GET /api/v1/stars/1          # by DB id
GET /api/v1/stars/hyg:0      # Sol by HYG id

Pulsars

GET /exotic?type=pulsar 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/exotic?type=pulsar&max_period=0.03

Exoplanets

GET /exoplanets 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/exoplanets?planet_type=super_earth&in_habitable_zone=true

Constellations

GET /constellations 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/constellations             # all 88
GET /api/v1/constellations/Ori         # Orion details
GET /api/v1/constellations/Ori/stars   # stars in Orion

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
}

API Plans

API access is included in Education and Institution membership tiers, or available as a standalone API plan.

View API pricing →