Skip to main content
For the complete documentation index, see llms.txt.

Hubble Network developer documentation: integrate Bluetooth devices with terrestrial and satellite connectivity.

Get Upcoming Satellite Passes

GET 
/v1/org/:org_id/satellite/passes

Retrieve upcoming satellite passes for a location or geographic area.

Required Scope: read-satellites

Overview​

This endpoint calculates upcoming satellite passes based on current TLE (Two-Line Element) orbital data for operational satellites in the Hubble constellation assigned to your organization. The timestamps returned in the array may be used for satellite transmission on Hubble Network.

Location Mode​

Request passes for your location using one of these two modes:

  • Use Point mode when you need to know exactly when a satellite will be visible from a fixed ground station or device location, for example device install_location.
  • Use Area mode when you want to know whether any satellite will have line-of-sight over a region. For example, to determine whether a fleet of BLE scanners spread across a geographic area can expect satellite coverage within a given time window.

Conditions where no pass data is returned:

  • Passes where the satellite's peak elevation does not reach the provided or default min_altitude_angle threshold.
  • Passes for satellites undergoing maintenance, which are excluded from these results.

Point Mode vs. Area Mode​

Point mode: Provide only latitude and longitude. Pass prediction is computed for that exact coordinate using the satellite TLE. The rise, culmination, and set timestamps all refer to that specific location.

Area mode: Provide latitude, longitude, to_latitude, and to_longitude to define a rectangular bounding box (south-west corner to north-east corner). rise_timestamp and set_timestamp bound the window during which the satellite is above the threshold somewhere in the box, and culmination_timestamp is when the satellite reaches peak elevation over the region. Because visibility is evaluated across the whole bounding box rather than a single point, these times will generally be wider than a point-mode pass for a location inside the same area.

Responses​

  • Maximum lookahead window: 42 days (default: 3 days).
  • Responses are cached for 1 hour, keyed by rounded coordinates (1 decimal place), altitude angle, and days ahead.

Time Uncertainty Seconds​

A time_uncertainty_seconds field is included on every pass, corresponding to how the satellite's TLE data is extrapolated over time, and can be used as a buffer in transmission timing.

Task Confirmation​

Every pass is predicted from orbital data alone, but not every pass is guaranteed to have the satellite actively listening. The task_confirmed field tells you whether Hubble has scheduled and synchronized a tasking window with the satellite operations system for that specific pass:

  • true: The satellite has been tasked to listen during this window. Devices transmitting within the pass timestamps can expect the satellite to be receiving.
  • false: This pass has not yet been confirmed with the satellite operator (for example, it is further in the future than tasking currently reaches, or scheduling has not completed). The satellite may not be listening during this window.

For a pass that has already happened, downlink_completed tells you whether the satellite contact succeeded and its data has been received:

  • true: The pass was tasked, the contact occurred, and data was downlinked successfully.
  • false: Either the pass was never tasked, the contact hasn't happened yet, or the contact occurred but data has not (yet, or ever) been received.

Satellite Maintenance​

A satellite that is undergoing maintenance is excluded from this endpoint's calculation, even though that satellite will still appear in the Get Satellite Ephemeris response.

Request​

Responses​

Satellite passes retrieved successfully