Analysis

POST/analysis/doppler

POST/analysis/elements

POST/analysis/footprint

Purpose

Three per-satellite analyses that return detailed sample data rather than aggregate statistics. Where /coverage answers “how well is this region served”, these answer “what exactly is this satellite doing”.

POST /analysis/doppler

Computes the Doppler profile between one satellite and one ground station across the window.

Parameter	Type	Unit	Default	Required	Description
`constellation_id`	string	n/a	—	Yes	Identifier of an existing constellation.
`satellite_id`	string	n/a	—	Yes	Satellite within that constellation, for example `demo-s0-p00-sat00`.
`ground_station`	object	n/a	—	Yes	The observing station. Singular, unlike `/link` which takes `ground_stations`.
`frequency_hz`	number	Hz	—	Yes	Carrier frequency. Note the unit: Hz, not GHz as elsewhere.
`start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Analysis start epoch.
`duration_hours`	number	h	`6`	No	Window length.
`step_seconds`	number	s	`60`	No	Sampling step.
`propagation_model`	string	n/a	`two_body`	No	Propagation model.

Two naming traps on this endpoint alone. The station field is ground_station, singular, where /link takes ground_stations, plural. And the frequency is frequency_hz in hertz, where /link uses frequency_ghz in gigahertz.

Both are required, so both fail loudly with a 422 rather than silently defaulting. That is the good case.

Example


curl -s -X POST http://127.0.0.1:8080/analysis/doppler \
  -H 'content-type: application/json' \
  -d '{
        "constellation_id": "demo",
        "duration_hours": 2.0,
        "satellite_id": "demo-s0-p00-sat00",
        "frequency_hz": 2200000000.0,
        "ground_station": {
          "id": "m", "name": "Madrid",
          "latitude_deg": 40.43, "longitude_deg": -3.7, "altitude_km": 0.6
        }
      }'


{
  "satellite_id": "demo-s0-p00-sat00",
  "ground_station_id": "m",
  "frequency_hz": 2200000000.0,
  "start": "2026-01-01T00:00:00Z",
  "samples": [
    {
      "time_s": 0.0,
      "range_km": 9835.567605972657,
      "range_rate_km_s": -4.5264526674238335,
      "doppler_hz": 33216.96594626285
    },
    {
      "time_s": 60.0,
      "range_km": 9559.452408392053,
      "range_rate_km_s": -4.676555462348115,
      "doppler_hz": 34318.0
    }
  ]
}

Response elided after two samples.

Reading the samples

A negative range_rate_km_s means the satellite is closing, and the corresponding doppler_hz is positive:

f_d = -\frac{\dot{r}}{c} f_c

The sign convention is that approach raises the received frequency. Every pass therefore starts positive, crosses zero at closest approach, and ends negative.

The first sample here shows a range of 9836 km, far beyond the horizon for a 550 km orbit. This endpoint reports the geometric Doppler across the whole window, including intervals when the satellite is not visible. Filter on elevation, or use a contact list, if you only want in-view samples.

POST /analysis/elements

Returns osculating Keplerian elements for every satellite at one sample index.


curl -s -X POST http://127.0.0.1:8080/analysis/elements \
  -H 'content-type: application/json' \
  -d '{"constellation_id":"demo"}'


{
  "constellation_id": "demo",
  "sample_index": 0,
  "sample_count": 361,
  "time_s": 0.0,
  "satellites": [
    {
      "satellite_id": "demo-s0-p00-sat00",
      "semi_major_axis_km": 6928.137000000002,
      "eccentricity": 3.7050165289361004e-16,
      "inclination_deg": 53.0
    }
  ]
}

Response elided.

The eccentricity of 3.7e-16 is floating-point zero, not a slightly elliptical orbit. A Walker constellation is generated circular, and that residual is the numerical noise of converting between element sets. Treat anything below about 1e-12 as exactly circular.

Use sample_index to inspect elements at a later point in the timeline, which is how you observe J2 driving nodal regression and apsidal rotation over a run.

POST /analysis/footprint

Returns the ground footprint of a satellite’s sensor: the region it can see, as a polygon suitable for overlay.

The footprint depends on altitude, field of view, and any off-nadir pointing, and it grows faster than linearly with altitude because the Earth curves away beneath it.