Images API

The Images API provides contextual imagery for celestial objects and satellites. Each endpoint uses a tiered resolution strategy, starting with curated photo archives and falling back through progressively more general sources. All image responses include an X-Image-Source header indicating which tier served the result, and X-Image-Credit where attribution is available.

SkyView Proxy

Proxies NASA SkyView observatory cutouts (DSS2 Red survey) to the client, avoiding browser CORS and Opaque Response Blocking (ORB) issues. SkyView uses a 302-redirect CGI pipeline that returns HTML on name-resolution failures — which triggers Chrome’s ORB protection when fetched directly from the browser.

GET /api/images/skyview

Parameters

Parameter	Type	Default	Range	Description
name	string	—	min 1 char	Target name, SIMBAD-resolvable (e.g. “M31”, “Vega”, “NGC 7000”)
pixels	integer	200	50 – 800	Image size in pixels
fov	float	0.5	0.01 – 10.0	Field of view in degrees

Response

Returns a JPEG image with the following headers:

Header	Value
Content-Type	image/jpeg
Cache-Control	public, max-age=604800, immutable (1 week)
X-Image-Source	skyview

On failure (unresolvable name, timeout), returns a transparent 1x1 PNG with status 404 and a 1-hour cache TTL.

Tip

SkyView resolves target names through SIMBAD. Any standard astronomical catalog name works — Messier (M31), NGC (NGC 7000), or common star names (Vega, Sirius). For deep-sky objects, increase fov to 1.0–2.0 degrees; for compact targets, 0.1–0.3 degrees gives tighter framing.

---

Comet Image

Tiered comet image resolution. The endpoint attempts three sources in order to find the best available image for a given comet.

GET /api/images/comet/{comet_id}

Parameter	Type	Description
comet_id	integer	Internal comet ID (path parameter)

Query Parameters

Parameter	Type	Default	Range	Description
pixels	integer	300	50 – 800	Image size in pixels
fov	float	0.5	0.1 – 5.0	Field of view in degrees

Resolution Tiers

1. NASA Image Library — Searches for real comet photographs by extracting the common name from the MPC designation (e.g. “Hale-Bopp” from C/1995 O1 (Hale-Bopp)). Returns actual photos for roughly 100 well-known comets.

2. SkyView DSS2 cutout — Computes the comet’s current RA/Dec position using Skyfield orbital mechanics (Kepler’s third law from MPC orbital elements), then fetches the DSS2 Red star field at those coordinates. The image shows the sky region where the comet currently sits.

3. Transparent placeholder — Returns a 1x1 transparent PNG with status 404 when both tiers above fail.

Response Headers

Header	Values	Description
X-Image-Source	nasa or skyview-coords	Which tier served the image
X-Image-Credit	NASA or SkyView/NASA GSFC (DSS2)	Attribution string
X-Comet-RA	e.g. 187.2340	Right ascension in degrees (tier 2 only)
X-Comet-Dec	e.g. -12.4560	Declination in degrees (tier 2 only)

Note

The NASA Image Library search applies relevance validation — the result’s title or description must mention the comet’s common name or its MPC designation (e.g. C/2023 A3). This prevents false positives where a generic search like “McNaught comet” returns an unrelated image.

Tip

Survey/telescope discoverer names that are too generic for meaningful image search (SOHO, LINEAR, NEAT, PANSTARRS, Spacewatch, WISE, Catalina, and others) are excluded from NASA lookups automatically. These comets fall through to the SkyView tier.

Cache Behavior

Tier	Cache TTL
NASA photo hit	1 week
SkyView cutout hit	24 hours
Placeholder miss	1 hour
NASA search result	24 hours

---

Satellite Image

Tiered satellite image resolution. Every satellite gets a meaningful image — there are no transparent placeholders in the success path. If curated sources fail, the endpoint generates a unique orbital diagram from the satellite’s TLE data.

GET /api/images/satellite/{norad_id}

Parameter	Type	Description
norad_id	integer	NORAD catalog number (path parameter)

Resolution Tiers

1. Wikipedia / Wikimedia Commons — Searches Wikipedia for a matching article, validates that it describes a space object (keyword matching against terms like “satellite”, “spacecraft”, “telescope”, “probe”), and extracts the article’s lead thumbnail. Covers roughly 1000+ named satellites.

2. NASA Image Library — Searches for spacecraft photography. Results undergo relevance validation: the title or description must mention the search term. Covers roughly 200+ well-known spacecraft.

3. Generated orbital diagram — A unique SVG visualization computed from the satellite’s TLE line 2 data. The diagram shows the orbit’s shape, altitude, inclination, and a deterministic starfield seeded from the NORAD ID for visual consistency across requests.

Response Headers

Header	Values
X-Image-Source	wikipedia, nasa, or orbital-diagram
X-Image-Credit	Wikimedia Commons, NASA, or Craft (TLE)

Response

Content-Type: image/jpeg       (tiers 1 and 2)
Content-Type: image/svg+xml    (tier 3 — orbital diagram)

Tip

The satellite name cleaning pipeline strips parenthetical suffixes (ISS (ZARYA) → ISS), debris designators (COSMOS 2251 DEB → COSMOS 2251), rocket body tags (CZ-2C R/B → CZ-2C), and constellation numbers (STARLINK-5234 → STARLINK) before searching. This improves hit rates dramatically for catalog entries with operational suffixes.

Note

A curated name mapping overrides the catalog name for 20+ well-known satellites where the standard designation does not search well. This includes the International Space Station (NORAD 25544), Hubble Space Telescope (20580), James Webb Space Telescope (50463), GOES and NOAA weather satellites, Landsat missions, and AMSAT OSCAR 7 (7530) among others.

Orbital Diagram Details

When tiers 1 and 2 fail, the SVG diagram is generated entirely from TLE line 2 orbital elements:

TLE Parameter	Visual Effect
Inclination	Projected orbit tilt and ellipse height
Eccentricity	Orbit shape (circular → elongated)
Mean anomaly	Satellite position along the orbit path
Mean motion	Semi-major axis via Kepler’s third law → altitude classification

Orbit classification by altitude:

Altitude	Classification	Color
< 2,000 km	LEO	Blue
2,000 – 20,200 km	MEO	Green
20,200 – 37,000 km	GEO	Amber
> 37,000 km	HEO	Red

Cache Behavior

Tier	Cache TTL
Wikipedia photo	1 week
NASA photo	1 week
Orbital SVG	24 hours
Image search result	24 hours