Skip to main content

Python SDK

The official Python SDK for Snowtrail. Available on PyPI.

Installation​

pip install snowtrail

Quick Start​

from snowtrail import Snowtrail

# Initialise client
client = Snowtrail(api_key="your-api-key")

# Or use environment variable SNOWTRAIL_API_KEY
client = Snowtrail()

Product Methods​

Each product is accessed as an attribute on the client. The following examples show the correct method names for each product:

GBSI-US​

# Gas Balance Stress Index - US
df = client.gbsi_us.system_stress(date_from="2024-01-01")
df = client.gbsi_us.price_context(date_from="2024-01-01")
df = client.gbsi_us.positioning(date_from="2024-01-01")
df = client.gbsi_us.balance_momentum(date_from="2024-01-01")
df = client.gbsi_us.storage_inventory(date_from="2024-01-01")
df = client.gbsi_us.storage_surprise(date_from="2024-01-01")
df = client.gbsi_us.backtest_summary()

GBSI-EU​

# Gas Balance Stress Index - EU
df = client.gbsi_eu.system_stress(date_from="2024-01-01", country="DE")
df = client.gbsi_eu.composite(date_from="2024-01-01")
df = client.gbsi_eu.balance_momentum(date_from="2024-01-01")
df = client.gbsi_eu.storage_surprise(date_from="2024-01-01")
df = client.gbsi_eu.backtest_summary()

PEMI​

# Power Event Market Intelligence
stress = client.pemi.grid_stress(date_from="2024-01-01", bidding_zone="10YDE-RWENET---I")

GLMI​

# Global LNG Marginality Index
margins = client.glmi.marginality(date_from="2024-01-01", basin="EU")

WRSI​

# Weather Risk Stress Index
forecast = client.wrsi.forecast_stress(date_from="2024-01-01", geography="US")

WSSI-US​

# Weather Storage Shock Index
demand = client.wssi_us.demand_shock(date_from="2024-01-01", region_id="US_NATIONAL")

Point-in-Time Queries with as_of​

Use the as_of parameter to retrieve only data that was published on or before a given date. This is essential for backtest-safe analysis.

# See only what was known on March 15, 2024
df = client.gbsi_us.system_stress(
    date_from="2024-01-01",
    date_to="2024-06-30",
    as_of="2024-03-15"
)

See Point-in-Time Integrity for more details.

Pagination​

By default, SDK methods return a pandas DataFrame with all results. The SDK handles pagination automatically.

For advanced use cases requiring cursor-based pagination (e.g., iterating through large result sets), use the _get_raw() method to access the raw API response:

# Standard usage - returns a complete DataFrame
df = client.gbsi_us.system_stress(date_from="2024-01-01")

# Advanced: manual cursor-based pagination with _get_raw()
response = client._get_raw("gbsi_us/system_stress", params={"date_from": "2024-01-01", "limit": 100})
data = response["data"]

while response.get("has_more"):
    response = client._get_raw(
        "gbsi_us/system_stress",
        params={"date_from": "2024-01-01", "limit": 100, "cursor": response["next_cursor"]}
    )
    data.extend(response["data"])

Error Handling​

from snowtrail import Snowtrail, NotFoundError, RateLimitError, AuthenticationError

client = Snowtrail(api_key="your-api-key")

try:
    df = client.gbsi_us.system_stress(date_from="2024-01-01")
except NotFoundError:
    print("Resource not found")
except RateLimitError:
    print("Rate limited - SDK automatically retries with exponential backoff (3 retries, 1s initial, 30s max)")
except AuthenticationError:
    print("Invalid or missing API key")