starfyi 0.1.1

Stars, constellations and astronomy API client — starfyi.com

starfyi

Python API client and CLI for stars, constellations, exoplanets, and deep-sky objects. Access 119,602 stars with spectral classifications and magnitudes, 20 constellations with mythology and star charts, 6,128 confirmed exoplanets, and 13,305 deep-sky objects (nebulae, galaxies, clusters) — all with zero dependencies.

Extracted from StarFYI, an astronomy reference platform with 195 glossary terms, 65 educational guides, 7 spectral classes, and interactive sky maps for astronomers, astrophysics students, and developers building astronomy applications.

Explore the cosmos at starfyi.com — browse the star catalog, explore constellations, discover exoplanets, and search deep-sky objects.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Stars & Stellar Classification
  • Constellations
  • Exoplanets
  • Deep-Sky Objects
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Astronomy
• Also Available
• Science FYI Family
• FYIPedia Developer Tools
• License

Install

pip install starfyi                # Core (zero deps)
pip install "starfyi[cli]"         # + Command-line interface (typer, rich)
pip install "starfyi[mcp]"         # + MCP server for AI assistants
pip install "starfyi[api]"         # + HTTP client for starfyi.com API
pip install "starfyi[all]"         # Everything

Or run instantly without installing:

uvx --from starfyi starfyi search sirius

Quick Start

from starfyi.api import StarFYI

with StarFYI() as api:
    # Look up any star by name — 119,602 stars in the catalog
    sirius = api.get_star("sirius")
    print(sirius["name"])            # Sirius
    print(sirius["magnitude"])       # -1.44 (brightest star in the night sky)
    print(sirius["distance_ly"])     # 8.60 light-years
    print(sirius["spectral_class"])  # a (A-type main sequence)
    print(sirius["constellation"])   # canis-major

    # Browse constellations, exoplanets, deep-sky objects
    constellations = api.list_constellations()
    exoplanets = api.list_exoplanets(limit=10)
    deep_sky = api.list_deep_sky(limit=10)

What You Can Do

Stars & Stellar Classification

The star catalog contains 119,602 stars with positions, magnitudes, distances, and spectral classifications. Stars are classified using the Morgan-Keenan (MK) system, which sorts stars by surface temperature into 7 spectral classes. The famous mnemonic "Oh Be A Fine Guy/Girl, Kiss Me" helps remember the sequence from hottest to coolest.

Spectral Class	Temperature (K)	Color	Examples
O	30,000-50,000+	Blue	Naos, Mintaka (rare, <0.003% of stars)
B	10,000-30,000	Blue-white	Rigel, Spica, Regulus
A	7,500-10,000	White	Sirius, Vega, Altair, Fomalhaut
F	6,000-7,500	Yellow-white	Canopus, Procyon, Polaris
G	5,200-6,000	Yellow	Sun, Alpha Centauri A, Capella
K	3,700-5,200	Orange	Arcturus, Aldebaran, Epsilon Eridani
M	2,400-3,700	Red	Betelgeuse, Proxima Centauri (75% of stars)

Each star record includes apparent magnitude (brightness as seen from Earth), absolute magnitude (intrinsic luminosity at 10 parsecs), right ascension and declination (celestial coordinates), color index (B-V), and distance in light-years.

from starfyi.api import StarFYI

with StarFYI() as api:
    # Look up Sirius — brightest star in the night sky
    sirius = api.get_star("sirius")
    print(sirius["magnitude"])            # -1.44 (apparent magnitude)
    print(sirius["absolute_magnitude"])   # 1.45
    print(sirius["distance_ly"])          # 8.60 light-years
    print(sirius["spectral_class"])       # a (A-type)
    print(sirius["color_index"])          # 0.009 (blue-white)
    print(sirius["ra_hours"])             # 6 (right ascension)
    print(sirius["dec_degrees"])          # -16 (declination)

    # List all 7 spectral classes
    classes = api.list_spectral_classes()
    for sc in classes["results"]:
        print(sc["letter"])  # O, B, A, F, G, K, M

Learn more: Star Catalog · Spectral Classes · Astronomy Glossary

Constellations

Explore 20 major constellations with mythology, notable stars, deep-sky objects, and observation guides. The 88 modern constellations recognized by the International Astronomical Union (IAU) divide the celestial sphere into regions, with these 20 being the most prominent and widely recognized.

Constellation	Season	Notable Stars	Key Objects
Orion	Winter	Betelgeuse, Rigel, Bellatrix	Orion Nebula (M42)
Ursa Major	Year-round (N)	Dubhe, Merak, Alioth	Big Dipper asterism
Scorpius	Summer	Antares, Shaula, Sargas	Butterfly Cluster (M6)
Leo	Spring	Regulus, Denebola	Leo Triplet galaxies
Cygnus	Summer	Deneb, Albireo	North America Nebula
Cassiopeia	Year-round (N)	Schedar, Caph	Heart and Soul Nebulae
Sagittarius	Summer	Kaus Australis, Nunki	Galactic center, M8 Lagoon
Lyra	Summer	Vega	Ring Nebula (M57)
Crux	Year-round (S)	Acrux, Mimosa	Jewel Box Cluster
Taurus	Winter	Aldebaran	Pleiades (M45), Crab Nebula

from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 20 constellations
    constellations = api.list_constellations()
    for c in constellations["results"]:
        print(c["slug"])  # orion, ursa-major, scorpius, ...

    # Get constellation detail with star lists and mythology
    orion = api.get_constellation("orion")
    print(orion)

Learn more: Constellations · Astronomy Guides

Exoplanets

StarFYI catalogs 6,128 confirmed exoplanets — planets orbiting stars beyond our solar system. Since the first confirmed detection in 1992 (PSR B1257+12 system) and the first around a Sun-like star in 1995 (51 Pegasi b), exoplanet science has revealed that planetary systems are common throughout the Milky Way.

Detection methods include transit photometry (Kepler, TESS), radial velocity (Doppler spectroscopy), direct imaging, gravitational microlensing, and astrometry. The majority of known exoplanets have been discovered by the Kepler space telescope and its successor TESS.

from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 6,128 confirmed exoplanets
    exoplanets = api.list_exoplanets(limit=10)
    print(exoplanets["count"])  # 6128

    # Get exoplanet detail
    detail = api.get_exoplanet("kepler-442-b")
    print(detail)

Learn more: Exoplanet Catalog · Astronomy Glossary

Deep-Sky Objects

Explore 13,305 deep-sky objects — nebulae, galaxies, star clusters, and other extended astronomical objects beyond the solar system. The catalog includes objects from the Messier catalog (110 objects), the New General Catalogue (NGC, 7,840 objects), and the Index Catalogue (IC, 5,386 objects).

Type	Description	Famous Examples
Emission Nebula	Ionized gas emitting light	Orion Nebula (M42), Eagle Nebula (M16)
Planetary Nebula	Expelled stellar atmosphere	Ring Nebula (M57), Helix Nebula (NGC 7293)
Reflection Nebula	Dust reflecting starlight	Witch Head, Pleiades haze
Open Cluster	Young, loosely bound stars	Pleiades (M45), Hyades
Globular Cluster	Ancient, densely packed stars	Omega Centauri, M13 (Hercules)
Spiral Galaxy	Rotating disk with arms	Andromeda (M31), Whirlpool (M51)
Elliptical Galaxy	Smooth, featureless profile	M87 (Virgo A), M32

from starfyi.api import StarFYI

with StarFYI() as api:
    # Browse 13,305 deep-sky objects
    dso = api.list_deep_sky(limit=10)
    print(dso["count"])  # 13305

    # Get deep-sky object detail
    detail = api.get_deep_sky("m42")
    print(detail)

Learn more: Deep-Sky Objects · Astronomy Guides

Command-Line Interface

pip install "starfyi[cli]"

starfyi search sirius               # Search stars by name
starfyi search "orion nebula"        # Search deep-sky objects
starfyi search kepler                # Search exoplanets

MCP Server (Claude, Cursor, Windsurf)

Add astronomy lookup tools to any AI assistant that supports Model Context Protocol.

pip install "starfyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "starfyi": {
            "command": "uvx",
            "args": ["--from", "starfyi[mcp]", "python", "-m", "starfyi.mcp_server"]
        }
    }
}

REST API Client

pip install "starfyi[api]"

from starfyi.api import StarFYI

with StarFYI() as api:
    stars = api.list_stars()                    # GET /api/v1/stars/
    sirius = api.get_star("sirius")            # GET /api/v1/stars/sirius/
    constellations = api.list_constellations()  # GET /api/v1/constellations/
    exoplanets = api.list_exoplanets()          # GET /api/v1/exoplanets/
    deep_sky = api.list_deep_sky()              # GET /api/v1/deep-sky/
    results = api.search("betelgeuse")          # GET /api/v1/search/?q=betelgeuse

Example

curl -s "https://starfyi.com/api/v1/stars/sirius/"

{
  "name": "Sirius",
  "slug": "sirius",
  "constellation": "canis-major",
  "spectral_class": "a",
  "spectral_class_letter": "A",
  "magnitude": "-1.44",
  "absolute_magnitude": "1.45",
  "distance_ly": "8.60",
  "color_index": "0.009",
  "ra_hours": 6,
  "dec_degrees": -16,
  "is_featured": true
}

Full API documentation at starfyi.com/developers/.

API Reference

Method	Description
list_stars(**params)	List 119,602 stars with pagination
get_star(slug)	Get star detail with position and spectral data
list_constellations(**params)	List 20 constellations
get_constellation(slug)	Get constellation detail with mythology and stars
list_exoplanets(**params)	List 6,128 confirmed exoplanets
get_exoplanet(slug)	Get exoplanet detail
list_deep_sky(**params)	List 13,305 deep-sky objects
get_deep_sky(slug)	Get deep-sky object detail
list_spectral_classes(**params)	List 7 spectral classes (O, B, A, F, G, K, M)
get_spectral_classe(slug)	Get spectral class detail
list_comparisons(**params)	List star comparisons
get_comparison(slug)	Get side-by-side comparison
list_glossary(**params)	List 195 astronomy glossary terms
get_term(slug)	Get glossary term definition
list_guides(**params)	List 65 educational guides
get_guide(slug)	Get guide content
search(query)	Search across all astronomy content

Learn More About Astronomy

• Browse: Star Catalog · Constellations · Exoplanets · Deep-Sky Objects
• Classification: Spectral Classes
• Reference: Astronomy Glossary
• Guides: Educational Guides
• API: REST API Docs · OpenAPI Spec

Also Available

Platform	Install	Link
npm	npm install starfyi	npm
MCP	uvx --from "starfyi[mcp]" python -m starfyi.mcp_server	Config

Science FYI Family

Part of the FYIPedia open-source developer tools ecosystem — physical sciences, chemistry, geology, astronomy, and materials.

Package	PyPI	npm	Description
chemfyi	PyPI	npm	Periodic table, 500 compounds, 371 reactions — chemfyi.com
alloyfyi	PyPI	npm	765 metal alloys, 12 families, compositions — alloyfyi.com
gemfyi	PyPI	npm	442 gemstones, Mohs scale, grading — gemfyi.com
starfyi	PyPI	npm	119,602 stars, 6,128 exoplanets, 13,305 deep-sky objects — starfyi.com
mineralfyi	PyPI	npm	6,215 minerals, 7 crystal systems — mineralfyi.com

FYIPedia Developer Tools

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies — colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,953 emojis — emojifyi.com
symbolfyi	PyPI	npm	Symbol encoding in 11 formats — symbolfyi.com
unicodefyi	PyPI	npm	Unicode lookup with 17 encodings — unicodefyi.com
fontfyi	PyPI	npm	Google Fonts metadata & CSS — fontfyi.com
distancefyi	PyPI	npm	Haversine distance & travel times — distancefyi.com
timefyi	PyPI	npm	Timezone ops & business hours — timefyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements — namefyi.com
unitfyi	PyPI	npm	Unit conversion, 220 units — unitfyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation — holidayfyi.com
cocktailfyi	PyPI	—	Cocktail ABV, calories, flavor — cocktailfyi.com
fyipedia	PyPI	—	Unified CLI: fyi star info sirius — fyipedia.com
fyipedia-mcp	PyPI	—	Unified MCP hub for AI assistants — fyipedia.com

License

MIT