Celestial Objects API

The Celestial Objects API covers everything beyond satellites: planets, stars, deep sky objects (DSOs), comets, the Sun, and the Moon. Object positions are computed in real time using the Skyfield library.

Target Search

Search across all target types — satellites, celestial objects, and built-in solar system bodies. This is the primary unified search endpoint used by the target picker.

GET /api/targets/search

Query Parameters

Parameter	Type	Default	Description
q	string	""	Search query. Empty string returns browse-mode results
type	string	—	Filter by type: satellite, star, dso, comet, planet, sun, moon, meteor_shower
limit	int	50	Max results (max 200)

Tip

When q is empty, the endpoint enters browse mode and returns planets, Sun, and Moon without querying the database. Satellites are excluded from browse mode — the frontend uses /api/satellites for satellite browsing.

Response

{
  "query": "vega",
  "results": [
    {
      "name": "Vega",
      "target_type": "star",
      "target_id": "42",
      "description": "Alpha Lyrae - brightest star in Lyra",
      "magnitude": 0.03
    }
  ],
  "count": 1
}

Examples

# Browse all planets and solar system bodies
curl "https://space.warehack.ing/api/targets/search"

# Search for deep sky objects
curl "https://space.warehack.ing/api/targets/search?q=andromeda&type=dso"

# Search for comets
curl "https://space.warehack.ing/api/targets/search?q=halley&type=comet"

---

Target Position

Get the current position of any target object (computed in real time from the observer’s location).

GET /api/targets/{target_type}/{target_id}/position

Path Parameters

Parameter	Type	Description
target_type	string	One of: satellite, planet, star, dso, comet, sun, moon
target_id	string	Object identifier (NORAD ID for satellites, DB ID for celestial objects, name for planets)

Response

{
  "name": "Mars",
  "target_type": "planet",
  "target_id": "mars",
  "altitude_deg": 42.3,
  "azimuth_deg": 185.7,
  "distance_km": 225000000.0,
  "ra_hours": 14.23,
  "dec_deg": -12.45,
  "is_above_horizon": true,
  "timestamp": "2026-02-14T22:30:00Z"
}

Examples

# Current position of Mars
curl "https://space.warehack.ing/api/targets/planet/mars/position"

# Current position of the ISS
curl "https://space.warehack.ing/api/targets/satellite/25544/position"

# Current position of a star by DB ID
curl "https://space.warehack.ing/api/targets/star/42/position"

---

Related Objects

Find objects similar to a given target using cross-type vector similarity. This searches across all four embedding stores (satellites, celestial objects, frequencies, and launches) to find semantically related objects.

GET /api/targets/{target_type}/{target_id}/related

Path Parameters

Parameter	Type	Description
target_type	string	Source object type
target_id	string	Source object identifier

Query Parameters

Parameter	Type	Default	Description
limit	int	6	Max results (max 20)

Response

{
  "source_type": "satellite",
  "source_id": "25544",
  "results": [
    {
      "name": "Tiangong",
      "target_type": "satellite",
      "target_id": "48274",
      "description": null,
      "similarity": 0.8921,
      "url": "/catalog/satellite/48274"
    }
  ],
  "count": 1
}

Note

Related objects require embedding vectors to be generated by the pgai vectorizer worker. If embeddings are not yet available for the source object, this endpoint returns a 404.

Valid Target Types

satellite, planet, star, dso, comet, frequency, launch, sun, moon

---

Sky Visibility

What’s Up

List all objects currently above a minimum altitude from the observer’s location.

GET /api/sky/up

Query Parameters

Parameter	Type	Default	Description
min_alt	float	10.0	Minimum altitude in degrees

Examples

# What's visible right now above 10 degrees
curl "https://space.warehack.ing/api/sky/up"

# Lower the minimum to see more objects
curl "https://space.warehack.ing/api/sky/up?min_alt=5"

---

Tonight’s Observables

Get objects that will be observable during tonight’s dark hours.

GET /api/sky/tonight

Examples

curl "https://space.warehack.ing/api/sky/tonight"

---

Rise and Set Times

Get rise and set times for a named target.

GET /api/sky/rise-set

Query Parameters

Parameter	Type	Default	Description
target	string	—	Target name (e.g. mars, vega)
target_type	string	planet	Type of target
days	int	1	Number of days to compute (max 7)

Examples

# When does Mars rise and set today?
curl "https://space.warehack.ing/api/sky/rise-set?target=mars"

# Rise/set times for Vega over the next 3 days
curl "https://space.warehack.ing/api/sky/rise-set?target=vega&target_type=star&days=3"

---

Comets

List Comets

Retrieve all comets in the database with their orbital parameters.

GET /api/comets

Response

{
  "count": 1024,
  "comets": [
    {
      "id": 1,
      "name": "C/1995 O1 (Hale-Bopp)",
      "designation": "C/1995 O1",
      "perihelion_au": 0.914,
      "eccentricity": 0.995,
      "inclination_deg": 89.43,
      "magnitude_g": 4.0,
      "magnitude_k": 4.0,
      "perihelion_year": 1997,
      "perihelion_month": 4,
      "perihelion_day": 1.14
    }
  ]
}

---

Get Comet Detail

GET /api/comets/{comet_id}

Returns full orbital elements including argument of perihelion, longitude of ascending node, epoch, and current computed RA/Dec.

---

Comet Count

GET /api/comets/count

{
  "count": 1024
}

---

Refresh Comets

Trigger a background refresh of comet data from the Minor Planet Center (MPC).

POST /api/comets/refresh

---

Comet Images

Retrieve an image for a comet, resolved through a tiered system:

1. NASA Image Library — real comet photographs for famous comets
2. SkyView DSS2 — sky survey cutout at the comet’s computed RA/Dec
3. Transparent placeholder — returned as 404 if no image is available

GET /api/images/comet/{comet_id}

Query Parameters

Parameter	Type	Default	Description
pixels	int	300	Image size in pixels (50-800)
fov	float	0.5	Field of view in degrees (0.1-5)

Response Headers

Header	Description
X-Image-Source	nasa, skyview-coords
X-Image-Credit	Attribution string
X-Comet-RA	Computed RA in degrees (SkyView)
X-Comet-Dec	Computed Dec in degrees (SkyView)

---

SkyView Proxy

Proxy endpoint for SkyView observatory survey cutouts. This avoids browser CORS/ORB issues with SkyView’s redirect-based CGI pipeline.

GET /api/images/skyview

Query Parameters

Parameter	Type	Default	Description
name	string	—	Object name (SIMBAD-resolvable)
pixels	int	200	Image size in pixels (50-800)
fov	float	0.5	Field of view in degrees (0.01-10)

Examples

# Get a DSS2 Red survey image of M31
curl -o m31.jpg "https://space.warehack.ing/api/images/skyview?name=M31&pixels=400&fov=2.0"