Observer & Frequencies API

Observer Location

The observer location is the ground station position used for all positional calculations — pass prediction, azimuth/elevation computation, rise/set times, and “what’s up” queries.

Get Observer

GET /api/observer

Returns the currently active observer location. If none exists in the database, a default is created from the environment configuration (OBSERVER_LAT, OBSERVER_LON, OBSERVER_ALT, OBSERVER_GRID).

Response

{
  "id": 1,
  "name": "Home QTH",
  "latitude": 39.7392,
  "longitude": -104.9903,
  "altitude_m": 1609.0,
  "grid_square": "DM79",
  "is_active": true
}

Update Observer

Update the active observer location. Only provided fields are updated.

PUT /api/observer

Request Body

{
  "name": "Remote Observatory",
  "latitude": 35.0844,
  "longitude": -106.6504,
  "altitude_m": 1520.0,
  "grid_square": "DM65"
}

Field	Type	Description
`name`	`string\|null`	Location name
`latitude`	`float\|null`	Latitude in decimal degrees
`longitude`	`float\|null`	Longitude in decimal degrees
`altitude_m`	`float\|null`	Altitude above sea level in meters
`grid_square`	`string\|null`	Maidenhead grid locator

Error Responses

Status	Description
`404`	No active observer

Frequencies

The Frequencies API provides access to known radio frequencies for satellites and other tracked objects. Frequency data includes modulation type and bandwidth, and supports real-time Doppler shift correction.

Frequency Catalog

List all targets that have frequency data, along with a count of how many frequencies each target has.

GET /api/frequencies/catalog

Response

{
  "satellites": [
    {
      "target_type": "satellite",
      "target_id": "25544",
      "name": "ISS (ZARYA)",
      "frequency_count": 12
    },
    {
      "target_type": "satellite",
      "target_id": "7530",
      "name": "AMSAT-OSCAR 7",
      "frequency_count": 4
    }
  ],
  "count": 2
}

Get Frequencies for a Target

GET /api/frequencies/{target_type}/{target_id}

Path Parameters

Parameter	Type	Description
`target_type`	`string`	e.g. `satellite`
`target_id`	`string`	e.g. `25544`

Response

[
  {
    "id": 1,
    "target_type": "satellite",
    "target_id": "25544",
    "description": "Voice repeater downlink",
    "frequency_mhz": 437.800,
    "modulation": "FM",
    "bandwidth_khz": 25.0
  },
  {
    "id": 2,
    "target_type": "satellite",
    "target_id": "25544",
    "description": "APRS digipeater",
    "frequency_mhz": 145.825,
    "modulation": "FM-AFSK",
    "bandwidth_khz": 12.5
  }
]

Examples

# Get ISS frequencies
curl "https://space.warehack.ing/api/frequencies/satellite/25544"

# Get NOAA-18 frequencies
curl "https://space.warehack.ing/api/frequencies/satellite/28654"

Doppler Shift Calculation

Compute the current Doppler-corrected frequency for all known frequencies of a target. This accounts for the relative velocity between the observer and the target.

GET /api/frequencies/{target_type}/{target_id}/doppler

Response

[
  {
    "base_frequency_mhz": 145.825,
    "corrected_frequency_mhz": 145.8284,
    "shift_hz": 3400.0,
    "range_rate_km_s": -7.02,
    "timestamp": "2026-02-14T22:30:00Z"
  }
]

Doppler Fields

Field	Type	Description
`base_frequency_mhz`	`float`	Nominal (rest) frequency
`corrected_frequency_mhz`	`float`	Doppler-corrected receive frequency
`shift_hz`	`float`	Frequency shift in Hz (positive = approaching)
`range_rate_km_s`	`float`	Range rate in km/s (negative = approaching)
`timestamp`	`string`	Computation time

Examples

# Get current Doppler correction for ISS frequencies
curl "https://space.warehack.ing/api/frequencies/satellite/25544/doppler"