Hubble Network Satellite API

openapi: 3.2.0
info:
  title: Hubble Platform Satellite API
  description: 'The Hubble platform is built API-first. Use our Cloud API to manage your devices

    and access device data programmatically. We''ve designed our API following RESTful principles. Each endpoint returns standard HTTP status codes and may include JSON payloads. ---


    ## API Access

    Use API Keys to authenticate with the Hubble Cloud API for your organization. ### Generate an API Key

    Log in to your Hubble dashboard. Navigate to **Developer Tools > API Tokens** to create a new API Key. Provide a name for the token, and set an appropriate expiration date for temporary access. ### Organization ID

    You will need `org_id` to make API requests. From your Hubble dashboard, navigate to

    **Developer Tooks > API Tokens**, or **Organization Settings**, to find your Organization ID. ### Authorization Scopes

    API endpoints require specific authorization scopes to perform the intended operation. **Required Scope** is always provided in the API documentation. API Keys can be created with specific authorization scopes that control what operations the key can perform. If no scopes are specified, the key will be created with all available scopes (admin-level access). | **Scope** | **Access** |

    |------------------------------|-------------------------------------------------|

    | **read-api-keys** | View API keys and their metadata |

    | **write-api-keys** | Create, update, and delete API keys |

    | **read-users** | View user information and roles |

    | **write-users** | Add, update, and remove users from the organization |

    | **read-organization-metadata** | View organization details and settings |

    | **write-organization-metadata** | Update organization information |

    | **read-devices** | View device information and status |

    | **write-devices** | Register and manage devices |

    | **read-invitations** | View pending invitations |

    | **write-invitations** | Create and revoke user invitations |

    | **read-packets** | Access packet data and retrieval endpoints |

    | **read-platform-metrics** | View platform metrics and analytics |

    | **read-billing-usage** | View billing usage information |

    | **read-billing-invoices** | View billing invoices |

    | **read-webhooks** | View webhook configurations |

    | **write-webhooks** | Create and manage webhook endpoints |

    | **read-satellites** | View satellite ephemeris and pass data |


    **Example Scope Combinations**

    - Create a key with read-only access: `["read-api-keys", "read-users", "read-devices"]`

    - Create a key for device management: `["read-devices", "write-devices"]`

    - Create a key for user management: `["read-users", "write-users", "read-invitations", "write-invitations"]`


    **Best Practices for Data Security**

    - Create keys with the minimum required scopes for your use case

    - Regularly review and rotate API keys

    - Use descriptive names for your keys to track their purpose

    - Set appropriate expiration dates for temporary access


    ---


    ## Import API Definition

    You can quickly import the Hubble Cloud API into your preferred developer environment (such as Postman or Insomnia) using our **public OpenAPI definition**. Simply download or import the YAML file directly:


    https://hubble.com/docs/openapi.yaml


    ---


    ## Pagination

    When the number of objects requested exceeds the maximum page size for an endpoint, the API response will be paginated. This means you will receive a subset of the total results, along with a `Continuation-Token` in the Response Header that can be used to fetch subsequent subsets. To retrieve the next set of data, you must use the provided `Continuation-Token` in the Request Header of your next API call to the same endpoint. Continue using the provided token in each successive request until no `Continuation-Token` is returned, which indicates you have retrieved all available data. ---


    ## Rate Limits

    The Hubble Cloud API follows a leaky bucket approach to rate limiting. Endpoints are rate limited to three (3) requests per second. Your organization is limited to a total of 15 requests per second.'
  version: 1.0.0
servers:
- url: https://api.hubble.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Satellite
paths:
  /v1/org/{org_id}/satellite/ephemeris:
    get:
      tags:
      - Satellite
      operationId: get-satellite-ephemeris
      x-criticality: low
      summary: Get Satellite Ephemeris
      description: 'Retrieve ephemeris data for all operational Hubble Network satellites.


        **Required Scope:** `read-satellites`


        ## Overview

        This endpoint retrieves satellite ephemeris data for all operational satellites in the Hubble Network

        assigned to your organization. The response includes TLE (Two-Line Element) orbital data, satellite metadata,

        and optional orbital parameters compatible with the Hubble Device SDK that allow clients to perform lightweight

        satellite pass calculations without full TLE propagation.


        ## Use Case

        Ephemeris data for satellites with station keeping is projected to be constant over time. The Hubble

        Device SDK uses parameters returned by this endpoint to derive satellite transmission windows for

        efficient, local beaconing logic stored on the device itself with minimal CPU overhead.'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: Satellite ephemeris data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - satellites
                properties:
                  satellites:
                    type: array
                    description: Array of satellite ephemeris data
                    items:
                      type: object
                      required:
                      - satellite_id
                      - ephemeris
                      - ephemeris_version
                      - ephemeris_drift_rate
                      - ephemeris_datetime
                      properties:
                        satellite_id:
                          type: integer
                          format: int64
                          description: NORAD ID of the satellite.
                          example: 123
                        ephemeris:
                          type: string
                          description: TLE (Two-Line Element) orbital data string.
                          example: '1 12345U 98067A   24001.50000000  .00001234  00000-0  12345-3 0  9999

                            2 12345  51.6400 123.4567 0001234  90.1234 270.1234 15.49012345678901'
                        ephemeris_version:
                          type: integer
                          format: int64
                          description: Version number of the ephemeris data.
                          example: 1
                        ephemeris_drift_rate:
                          type: number
                          format: float
                          description: 'Drift rate of the ephemeris data. When a per-satellite value is configured,

                            that value is returned; otherwise defaults to 5.0.

                            '
                          default: 5.0
                          example: 5.0
                        ephemeris_datetime:
                          $ref: '#/components/schemas/utcTimestampInteger'
                          description: Unix timestamp when the ephemeris data was generated.
                          example: 1705320000
                        orbital_params:
                          $ref: '#/components/schemas/orbitalParams'
                          description: 'Efficient pass prediction parameters for each satellite. Omitted when not yet

                            computed for this satellite. Callers should treat its absence as a signal to

                            exclude that satellite from the set programmed on device firmware.

                            '
        '403':
          $ref: '#/components/responses/ErrorForbidden'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/satellite/passes:
    get:
      tags:
      - Satellite
      operationId: get-upcoming-satellite-passes
      x-criticality: low
      summary: Get Upcoming Satellite Passes
      description: '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.'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - name: latitude
        in: query
        required: true
        description: 'Geographic latitude in decimal degrees. In area mode, this is the south (lower) boundary.

          '
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
          example: 40.7128
      - name: longitude
        in: query
        required: true
        description: 'Geographic longitude in decimal degrees. In area mode, this is the west (left) boundary.

          '
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
          example: -74.006
      - name: to_latitude
        in: query
        required: false
        description: 'Area mode only. North (upper) boundary. Must be greater than `latitude`. Max difference from

          `latitude`: 90°. Required together with `to_longitude`.

          '
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
          example: 40.8
      - name: to_longitude
        in: query
        required: false
        description: 'Area mode only. East (right) boundary. Must differ from `longitude`. Max span: 90°. Crossing the

          antimeridian is supported (`to_longitude` may be less than `longitude`). Required together with

          `to_latitude`.

          '
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
          example: -73.9
      - name: min_altitude_angle
        in: query
        required: false
        description: 'Minimum peak elevation angle (degrees) a pass must reach to be included in the response.

          '
        schema:
          type: number
          format: float
          minimum: 0
          maximum: 89
          default: 45
          example: 45.0
      - name: days_ahead
        in: query
        required: false
        description: Number of days ahead to search for satellite passes.
        schema:
          type: integer
          minimum: 1
          maximum: 42
          default: 3
          example: 7
      responses:
        '200':
          description: Satellite passes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - passes
                properties:
                  passes:
                    type: array
                    description: Array of pass objects sorted by rise time ascending.
                    items:
                      type: object
                      required:
                      - satellite_id
                      - rise_timestamp
                      - culmination_timestamp
                      - set_timestamp
                      - time_uncertainty_seconds
                      - culmination_altitude_angle
                      - task_confirmed
                      properties:
                        satellite_id:
                          type: integer
                          format: int64
                          description: NORAD ID of the satellite.
                          example: 123
                        task_confirmed:
                          type: boolean
                          description: 'Whether this pass has been confirmed and synchronized with the satellite

                            operations system.

                            '
                          example: true
                        rise_timestamp:
                          $ref: '#/components/schemas/utcTimestampInteger'
                          description: 'Unix timestamp when the satellite rises above the horizon. For area mode, this is

                            the earliest time the satellite becomes visible from anywhere in the bounding box.

                            '
                          example: 1705323600
                        culmination_timestamp:
                          $ref: '#/components/schemas/utcTimestampInteger'
                          description: 'Unix timestamp when the satellite reaches its peak elevation. May be 0 if

                            culmination data is unavailable. For area mode, this is the peak over the region.

                            '
                          example: 1705325400
                        set_timestamp:
                          $ref: '#/components/schemas/utcTimestampInteger'
                          description: 'Unix timestamp when the satellite sets below the horizon. For area mode, this is

                            the latest time the satellite is still visible from anywhere in the bounding box.

                            '
                          example: 1705327200
                        time_uncertainty_seconds:
                          type: integer
                          format: int64
                          description: 'Predicted timing uncertainty in seconds, computed from TLE age. Grows

                            quadratically with time since the last TLE update. A value of 0 indicates very

                            recent TLE data. Defaults to a 24-hour TLE age if the satellite is not in cache.

                            '
                          example: 12
                        culmination_altitude_angle:
                          type: number
                          format: float
                          description: Peak elevation angle (degrees) the satellite reaches during this pass.
                          example: 62.4
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '403':
          $ref: '#/components/responses/ErrorForbidden'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
components:
  schemas:
    orgId:
      type: string
      format: uuid
      description: The ID for an organization
    errorResponse:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code
        description:
          type: string
          description: 'A description for the error.

            For user errors, we attempt to be as descriptive as possible to help with diagnosing the issue.

            For internal errors, the error description is only indicates that a retry should occur but we log the full error so that we can diagnose it.

            Error descriptions can change over time and should not be programmed against.

            '
        name:
          type: string
          enum:
          - Bad Request
          - Unauthorized
          - Not Found
          - Request Entity Too Large
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    orbitalParams:
      type: object
      description: 'Orbital parameters derived from recent TLE history.

        These parameters enable lightweight client-side satellite pass prediction.

        '
      required:
      - t0
      - n0
      - ndot
      - raan0
      - raandot
      - aop0
      - aopdot
      - inclination
      - eccentricity
      properties:
        t0:
          type: integer
          format: int64
          description: Reference epoch as a Unix timestamp (seconds since 1970-01-01T00:00:00Z).
          example: 1770934465
        n0:
          type: number
          format: double
          description: Mean motion at the reference epoch (orbits per second).
          example: 0.0001781
        ndot:
          type: number
          format: double
          description: First derivative of mean motion (orbits per second squared).
          example: 6.23e-14
        raan0:
          type: number
          format: double
          description: Right Ascension of Ascending Node (RAAN) at the reference epoch (radians).
          example: 2.484
        raandot:
          type: number
          format: double
          description: Rate of change of RAAN (radians per second).
          example: 2.04e-07
        aop0:
          type: number
          format: double
          description: Argument of Periapsis at the reference epoch (radians).
          example: 3.404
        aopdot:
          type: number
          format: double
          description: Rate of change of Argument of Periapsis (radians per second).
          example: -5.13e-07
        inclination:
          type: number
          format: double
          description: Orbital inclination (degrees).
          example: 97.4
        eccentricity:
          type: number
          format: double
          description: Orbital eccentricity (dimensionless).
          example: 0.0001
    utcTimestampInteger:
      type: integer
      format: int64
      description: An UTC second-precision timestamp formatted as an integer
  responses:
    ErrorForbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 403
            description: The authenticated principal is not allowed to perform this operation.
            name: Forbidden
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 400
            description: The request could not be understood by the server due to malformed syntax.
            name: Bad Request
    ErrorInternalServer:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 500
            description: An unknown error has occurred.
            name: Unknown
  parameters:
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Hubble Network
  source: https://hubble.com/docs/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)