Query stars in a rectangular region with pagination. Returns full star details (RA, Dec, magnitude, parallax, color).

Parameter	Type	Description
ra_min required	f64	Minimum Right Ascension (0-360°)
ra_max required	f64	Maximum Right Ascension (0-360°)
dec_min required	f64	Minimum Declination (-90 to 90°)
dec_max required	f64	Maximum Declination (-90 to 90°)
max_mag required	f32	Maximum magnitude filter (brighter = lower)
offset required	usize	Skip first N results
limit required	usize	Maximum results to return

Example

curl "https://lumen.deepskies.observer/api/query/paginated?ra_min=180&ra_max=181&dec_min=0&dec_max=1&max_mag=15&offset=0&limit=10"

Response

{
  "success": true,
  "data": {
    "stars": [
      {
        "source_id": 3698956337898276352,
        "ra": 180.0526,
        "dec": 0.0042,
        "magnitude": 13.99,
        "parallax": 1.02,
        "bp_rp": 0.84
      }
    ],
    "total_count": 4187,
    "offset": 0,
    "has_more": true
  }
}

Binary endpoint for efficient bulk data transfer. Returns raw bytes optimized for GPU upload. Same parameters as /api/query/paginated.

Binary Format

Header (12 bytes):
  - star_count:  u32 LE (4 bytes)
  - total_count: u32 LE (4 bytes)
  - has_more:    u8     (1 byte)
  - padding:     3 bytes

Per Star (28 bytes):
  - source_id:  u64 LE (8 bytes)
  - ra:         f32 LE (4 bytes)
  - dec:        f32 LE (4 bytes)
  - magnitude:  f32 LE (4 bytes)
  - parallax:   f32 LE (4 bytes)
  - bp_rp:      f32 LE (4 bytes)

Example (JavaScript)

const response = await fetch('/api/query/binary?ra_min=180&ra_max=181&dec_min=0&dec_max=1&max_mag=15&offset=0&limit=1000');
const buffer = await response.arrayBuffer();
const view = new DataView(buffer);

const starCount = view.getUint32(0, true);
const totalCount = view.getUint32(4, true);
const hasMore = view.getUint8(8) === 1;

for (let i = 0; i < starCount; i++) {
    const offset = 12 + i * 28;
    const sourceId = view.getBigUint64(offset, true);
    const ra = view.getFloat32(offset + 8, true);
    const dec = view.getFloat32(offset + 12, true);
    const mag = view.getFloat32(offset + 16, true);
    // ...
}

Count stars in a region without returning data. Fast way to check query size before fetching.

Parameter	Type	Description
ra_min	f64	Minimum RA
ra_max	f64	Maximum RA
dec_min	f64	Minimum Dec
dec_max	f64	Maximum Dec

curl "https://lumen.deepskies.observer/api/count?ra_min=0&ra_max=360&dec_min=-90&dec_max=90"
{"success": true, "data": 1347293721}

Count stars with magnitude filter.

Parameter	Type	Description
ra_min, ra_max, dec_min, dec_max	f64	Region bounds
max_mag	f32	Maximum magnitude

curl "https://lumen.deepskies.observer/api/count/filtered?ra_min=180&ra_max=181&dec_min=0&dec_max=1&max_mag=15"
{"success": true, "data": 20}

Find K nearest stars to a point.

Parameter	Type	Description
ra required	f64	Right Ascension (0-360°)
dec required	f64	Declination (-90 to 90°)
k	usize	Number of nearest stars (default: 10)

curl "https://lumen.deepskies.observer/api/nearest?ra=180&dec=0&k=5"

Get index statistics including entry count and memory usage.

curl "https://lumen.deepskies.observer/api/stats"
{
  "success": true,
  "data": {
    "num_entries": 1347293721,
    "morton_bytes": 6245881660,
    "source_id_bytes": 10701874505,
    "magnitude_bytes": 1347293721,
    "parallax_bytes": 2694587442,
    "color_bytes": 1347293721,
    "total_bytes": 22336931049
  }
}

Health check endpoint.

curl "https://lumen.deepskies.observer/api/ping"
{"success": true, "data": "pong"}