Stars API

Frequently Asked Questions

• Can I use the Stars API for commercial purposes?

  Yes, but you must have a premium subscription. Commercial use of the Stars API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

• How do I get an API key and start using the Stars API?

  Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

• What happens if I exceed my quota for the month?

  Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.

• What happens if a request to the Stars API fails?

  The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

• How do I look up a specific star or all stars in a constellation?

  Pass the name parameter to find a star by name (note that many star names contain Greek characters), or use the constellation parameter to return stars belonging to a given constellation; at least one parameter (other than offset) is required on each request. For related celestial data, check out the Planets API.

• What fields does the Stars API return for each star?

  Each star object includes its name, constellation, celestial coordinates (right_ascension and declination), brightness as apparent_magnitude and absolute_magnitude, distance_light_year from Earth, and its spectral_class. If a request is unsuccessful, an error is returned instead, which you can decode using our error codes reference.

• Can I filter stars by brightness or distance from Earth?

  Yes, you can narrow results using min_apparent_magnitude/max_apparent_magnitude, min_absolute_magnitude/max_absolute_magnitude, and min_distance_light_year/max_distance_light_year to target specific brightness or distance ranges. Browse the full set of available tools in our API catalog.

• How many results does the Stars API return, and how do I get more?

  Each request to the /v1/stars endpoint returns at most 30 star objects, so to retrieve additional matches use the offset parameter across multiple API calls for pagination. For higher usage volumes, check our pricing plans.