Retrieve upcoming satellite passes for a location or geographic area.

Required Scope: read-satellites

Overview

This endpoint predicts 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.

:::warning 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 whose set_timestamp is in the past (filtered after computation).
• Estimated passes more than 42 days in the future. :::

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, so transmissions are not guaranteed to be received.

{
  "passes": [
    {
      "satellite_id": 123,
      "task_confirmed": true,
      "time_uncertainty_seconds": 12,
      "culmination_altitude_angle": 62.4
    }
  ]
}