Skip to main content
POST
Lists when imaging satellites were or will be over a point; only published orbits are covered. observed is the satellite and orbit the source published; every pass figure is derived by SGP4 (rise_at, culminate_at, set_at, max_elevation_deg, daynight, cut_by_window, track_distance_km, in_swath). in_swath true means the sensor could have seen the point; it does not mean an image was taken or released. Orbital elements courtesy of CelesTrak (celestrak.org), from US government sources. The pass times are computed by OneShot, not published by CelesTrak.

​
Authentication

Requires x402 payment in the payment-signature header.

​
Request Body

​
number
required
Latitude in decimal degrees, for example 34.05. From -90 to 90.
​
number
required
Longitude in decimal degrees (west is negative), for example -118.25. From -180 to 180.
​
string
Start of the window, ISO 8601 UTC such as 2026-10-28T00:00:00Z or 2026-10-28; default 24 hours before the call.
​
string
End of the window, ISO 8601 UTC, at most 48 hours after from and within 3 days of the call; default 24 hours after the call.
​
string
imaging: every satellite below geosynchronous orbit in the catalogues read that carries an imager; all: those plus the altimetry, GNSS and ionosphere missions listed beside them. One of imaging, all. Defaults to "imaging".
​
number
Elevation above the horizon at the point that defines rise and set. From 0 to 90. Defaults to 10.
​
integer
Most passes to return. From 1 to 200. Defaults to 25.

​
Response (200 OK)

Top-level envelope: success (boolean) and data (object). All fields below are nested under data.
​
string
Durable job ID for audit and lookup
​
string
Job status: completed
​
string
Always place_satellite_passes
​
object
The answer, described under Result below
​
object
Where the answer came from and when
​
string
The public body the data comes from. Always CelesTrak.
​
string
public when the data comes from a public body, commercial otherwise
​
string
When the lookup was made, as an ISO 8601 UTC time
​
string | null
The newest element epoch among the satellites considered, when the source last measured an orbit the answer uses; null when none was listed.

​
Result

Nested under data.result.
​
object
Coverage.
​
string
Start of the window, ISO 8601 UTC.
​
string
End of the window, ISO 8601 UTC.
​
string
Kind.
​
string[]
The catalogues read.
​
object[]
Every satellite whose orbit was propagated over the window.
​
string
Satellite.
​
integer
Norad id.
​
string
The element epoch, ISO 8601 UTC: when the orbit was last measured.
​
string | null
The imaging sensor from the swath table, or null for a satellite whose swath is not tabled.
​
number | null
The sensor swath on the ground, or null when not tabled.
​
object[]
Swath-table satellites the source did not list, so their passes are unknown.
​
string
Satellite.
​
integer
Norad id.
​
integer
Passes left out because they lie more than 3 days from the element epoch.
​
integer
Satellites in the catalogues read that do not pass over a point (geosynchronous and higher).
​
integer
Passes in the window, including any beyond limit.
​
integer
Returned.
​
boolean
True when passes beyond limit were left out.
​
object[]
In time order of rise_at.
​
object
What the source published about the satellite: its identity and the orbit the pass is computed from.
​
string
The satellite name as the catalogue spells it.
​
integer
The satellite catalogue number.
​
string
The element epoch, ISO 8601 UTC: when the source last measured this orbit.
​
number
Revolutions per day, as the element set states.
​
number
Orbital inclination in degrees, as the element set states.
​
object
Every value OneShot computes from the published orbit; each names its rule and the fields it reads.
​
object
When the satellite rose above min_elevation_deg at the point, ISO 8601 UTC, computed by SGP4; from when the pass was in progress at from.
​
string
Value.
​
string
Rule.
​
string[]
From.
​
object
When it was highest in the sky at the point, ISO 8601 UTC, computed by SGP4.
​
string
Value.
​
string
Rule.
​
string[]
From.
​
object
When it dropped below min_elevation_deg, ISO 8601 UTC, computed by SGP4; to when the pass was still in progress at to.
​
string
Value.
​
string
Rule.
​
string[]
From.
​
object
Elevation above the horizon at culmination, in degrees, computed by SGP4.
​
number
Value.
​
string
Rule.
​
string[]
From.
​
object
day when the Sun was above the horizon at the point at culmination, otherwise night.
​
string
Value.
​
string
Rule.
​
string[]
From.
​
object
True when the pass was in progress at from or at to, so rise_at or set_at is the window edge.
​
boolean
Value.
​
string
Rule.
​
string[]
From.
​
object
The least kilometres from the point to the ground track anywhere in the pass, to 0.1 km; null when the orbit could not be propagated over the pass.
​
number | null
Value. null when the source gives no value.
​
string
Rule.
​
string[]
From.
​
object
True when the unrounded least track distance is within half the sensor swath, false when outside it, null for a satellite whose swath is not in the sensor table or without a track distance.
​
boolean | null
Value. null when the source gives no value.
​
string
Rule.
​
string[]
From.
See Pricing for this tool’s price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers 200.

​
Notes

  • Nothing in a pass is measured. observed is what the source published about the satellite and its orbit; every time and figure under derived is computed from that orbit by SGP4 and carries value, rule and from. Accuracy falls with distance from the element epoch, so a pass more than 3 days from its epoch is left out and counted in coverage.too_far_from_epoch. daynight is day when the Sun is above the horizon at the point at culmination.
  • derived.track_distance_km is the least distance from the point to the ground track anywhere in the pass as reported, to 0.1 km. derived.in_swath compares that distance, before rounding, with half the sensor swath from a fixed table: VIIRS (Suomi NPP, NOAA-20, NOAA-21) 3,000 km, MODIS (Terra, Aqua) 2,330 km, Landsat 8 and 9 OLI 185 km, Sentinel-2A, 2B and 2C MSI 290 km, Sentinel-1A, 1C and 1D IW 250 km. It is null for an imaging satellite whose swath is not in the table, such as WorldView-3 or Sentinel-3A: the pass is reported, whether the point was in its swath is not known.
  • Reading coverage: coverage.satellites lists each satellite considered with its element epoch and, when tabled, its sensor and swath. Empty passes with satellites listed and too_far_from_epoch zero means the orbits were computed and none rose above min_elevation_deg: looked, saw nothing. Empty passes with coverage.satellites empty, or with every pass in too_far_from_epoch, means no evidence either way. coverage.not_published lists swath-table satellites the source did not list.
  • from and to are ISO 8601 UTC (a date alone is midnight UTC), at most 48 hours apart and within 3 days of the call either way; defaults are 24 hours before and after the call. A pass in progress at from or at to is cut at the window edge and marked cut_by_window. min_elevation_deg defaults to 10. limit defaults to 25, at most 200; total, returned and truncated report the list.
  • kind imaging (default) considers every satellite below geosynchronous orbit in the Earth resources and weather catalogues and the Sentinel-1 family, the 12-hour Molniya orbit of ARKTIKA-M included, except the missions that carry no imager (altimeters, GNSS reflectometry and occultation constellations, ionosphere probes, data relays); kind all considers those too. Geosynchronous and higher orbits do not pass over a point and are counted in coverage.high_orbit_left_out. Imaging satellites whose orbits are not published are not in the source.
  • Three catalogue reads per call, kept in this process for 2 hours as the source asks and shared by every caller in that time, a fresh call included; evidence.calls carry the time the element sets were fetched.
  • Results return inline. The finished job stays available at /v1/requests/{request_id}