Skip to main content

GRID Python SDK

A Python SDK to simplify integration with GRID services.

Website: https://gridgs.com
PyPI: https://pypi.org/project/gridgs-sdk/

Installation

pip install gridgs-sdk

Note: This SDK is currently in beta. Please expect potential changes (we'll try to maintain backward compatibility where possible).

Main Components

  • GridAuthClient (gridgs.sdk.auth.Client) - Handles authorization with GRID SSO server
  • GridApiClient (gridgs.sdk.api.Client) - Client for GRID REST API to work with main GRID entities
  • GridEventSubscriber (gridgs.sdk.event.Subscriber) - Subscriber to receive real-time events about session changes (creation, deletion, starting, etc.)
  • GridMQTTClient (gridgs.sdk.mqtt.Client) - Client for GRID MQTT API, useful for real-time communication (receiving downlink frames and sending uplink frames)

Usage Examples

GridAuthClient

from keycloak import KeycloakOpenID
from gridgs.sdk.auth import Client as GridAuthClient

keycloak_openid = KeycloakOpenID(
    server_url="https://login.gridgs.com", 
    client_id="grid-api", 
    realm_name="grid"
)
grid_auth_client = GridAuthClient(
    open_id_client=keycloak_openid, 
    username="user@gridgs.com", 
    password="userpass", 
    logger=logging.getLogger('grid_auth_client')
)

GridApiClient

from gridgs.sdk.api import Client as GridApiClient

grid_api_client = GridApiClient(
    base_url="https://api.gridgs.com",
    auth_client=grid_auth_client, 
    logger=logging.getLogger('grid_api_client')
)

Get Sessions

from gridgs.sdk.api import SortOrder, SessionQueryParams, SessionSortField

params = SessionQueryParams(
    satellite=1,
    ground_station=13,
    status=Session.STATUS_SUCCESS,
    offset=0, 
    limit=3, 
    sort_by=SessionSortField.END_DATE, 
    sort_order=SortOrder.ASC
)
sessions_result = grid_api_client.find_sessions(params)

print(f'Total: {sessions_result.total}')

Iterate All Sessions

Iterates through all sessions in chunks (default chunk size: 500) based on query parameters.

from gridgs.sdk.api import SortOrder, SessionQueryParams, SessionSortField

params = SessionQueryParams(
    offset=0, 
    limit=1000000,
    satellite=1,
    ground_station=13,
    status=Session.STATUS_SUCCESS,
    sort_by=SessionSortField.END_DATE, 
    sort_order=SortOrder.ASC
)

for session in grid_api_client.iterate_sessions(params):
    print(session)

Get Session by ID

session = grid_api_client.find_session(session_uuid)

Predict Sessions

Maximum: 100 sessions

from gridgs.sdk.api import NonPaginatedSessionQueryParams

params = NonPaginatedSessionQueryParams(
    satellite=1, 
    ground_station=13,
    date_from=datetime.fromisoformat("2025-01-01 00:00:00"),
    date_to=datetime.fromisoformat("2025-01-02 00:00:00"),
    min_tca_elevation=20,
)
sessions = grid_api_client.predict_sessions(params)

Create Session

session = Session()  # A session from get_predicted_sessions
session = grid_api_client.create_session(session)

Delete Session

grid_api_client.delete_session(session_uuid)

Get Frames

from gridgs.sdk.api import SortOrder, FrameSortField, FrameQueryParams

params = FrameQueryParams(
    satellite=2, 
    ground_station=13, 
    date_from=datetime.fromisoformat("2025-02-07 00:00:00"), 
    date_to=datetime.fromisoformat("2025-02-07 00:48:00"), 
    offset=0, 
    limit=5, 
    sort_by=FrameSortField.CREATED_AT, 
    sort_order=SortOrder.ASC
)

frames_result = grid_api_client.find_frames(params)
print(f'Total: {frames_result.total}')

Iterate All Frames

Iterates through all frames in chunks (default chunk size: 500) based on query parameters.

from gridgs.sdk.api import SortOrder, FrameSortField, FrameQueryParams

params = FrameQueryParams(
    offset=0, 
    limit=1000000, 
    satellite=1,
    ground_station=13,
    date_from=datetime.fromisoformat("2025-02-07 00:00:00"), 
    date_to=datetime.fromisoformat("2025-02-07 00:48:00"), 
    sort_by=FrameSortField.CREATED_AT, 
    sort_order=SortOrder.ASC
)

for frame in grid_api_client.iterate_frames(params):
    print(frame)

SSL/TLS Configuration

For GridEventSubscriber and GridMQTTClient:

from gridgs.sdk.ssl import Settings as SslSettings

ssl_settings = SslSettings(version=ssl.PROTOCOL_TLSv1_2, verify=True)

Note: When using SSL/TLS settings, use port 8883. Arguments have default values.

GridEventSubscriber

Receive session status events for satellite:

from gridgs.sdk.entity import SessionEvent
from gridgs.sdk.event import Subscriber as GridEventSubscriber

grid_event_subscriber = GridEventSubscriber(
    host="api.gridgs.com", 
    port=1883, 
    auth_client=grid_auth_client,
    satellite_id=2,
    ssl_settings=None, 
    logger=logging.getLogger('grid_event_subscriber')
)

def on_event(event: SessionEvent):
    session = event.session
    event_type = event.type  # Create, Update, Delete

grid_event_subscriber.on_event(on_event)
grid_event_subscriber.run()

GridMQTTClient

from gridgs.sdk.entity import Frame
from gridgs.sdk.mqtt import Client as GridMQTTClient

grid_mqtt_client = GridMQTTClient(
    host="api.gridgs.com", 
    port=1883, 
    auth_client=grid_auth_client, 
    ssl_settings=None, 
    logger=logging.getLogger('grid_mqtt_client')
)

def on_downlink_frame(frame: Frame):
    pass

grid_mqtt_client.on_downlink(on_downlink_frame)
grid_mqtt_client.connect(session)

Sending a Frame

grid_mqtt_client.send(b'Uplink frame data')

Metadata

Release files for gridgs-sdk 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gridgs-sdk 1.1.1
File Size Uploaded Provenance Actions
gridgs_sdk-1.1.1.tar.gz 14.8 kB Without provenance Details for gridgs_sdk-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gridgs-sdk 1.1.1
File Interpreter ABI Platform Actions
gridgs_sdk-1.1.1-py3-none-any.whl Python 3 none any Details for gridgs_sdk-1.1.1-py3-none-any.whl

Total release size: 36.4 kB

Release files / gridgs_sdk-1.1.1.tar.gz

Download URL gridgs_sdk-1.1.1.tar.gz
Size 14.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e6a46cfc78e2a40d256573a321b45c170f40fade32fb5b327163e14c4ab8142d
BLAKE2b-256 checksum
How to use checksums
0ce67a190e4a7c84ee7842e10a21a11aa81f1b4eaa260ad261e86511ea73668e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / gridgs_sdk-1.1.1-py3-none-any.whl

Download URL gridgs_sdk-1.1.1-py3-none-any.whl
Size 21.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
401806fd228fe4298bc8fe1d0e91de5972bddc487bcf9137f520a4671f264795
BLAKE2b-256 checksum
How to use checksums
91a594e297bd00151d22113d0b6556bc3415bac2b26051318b12a3cdfd34da1a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for gridgs-sdk 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page