Quick start

The pd4castr Python SDK lets you query forecast models and user information from the pd4castr API in just a few lines of Python. This guide walks you through installation, credentials, and your first API call.

Prerequisites

• Python 3.11 or later
• A pd4castr client ID and client secret (see Authentication for how to obtain these)

Install the SDK

Install the package from PyPI:

pip install pd4castr-api-sdk

This automatically installs the required dependencies (httpx and pydantic).

Create a client

Import the Client class and initialize it with your credentials:

from pd4castr_api_sdk import Client
 
client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

The SDK handles authentication automatically. On the first API call, it exchanges your credentials for an access token and caches it for subsequent requests.

Make your first API call

Once you have a client, you can start querying the API.

List models

Retrieve all models you have access to, including your organisation’s private models and any public models:

models = client.get_models()
for model in models:
    print(f"{model.displayName} (r{model.revision})")

You can filter by time horizon:

day_ahead = client.get_models(time_horizon="day_ahead")

Valid time horizon values are "day_ahead", "week_ahead", "quarterly", and "historical".

Get a specific model

Fetch a single model by its ID:

model = client.get_model("your-model-id")
print(model.name, model.horizon.name)

Get the current user

Retrieve the authenticated user’s profile and organisation details:

user = client.get_current_user()
print(user.email, user.organisation.displayName)

Close the client

When you’re done, close the underlying HTTP connection:

client.close()

Alternatively, use a context manager to close the client automatically:

with Client(client_id="your-client-id", client_secret="your-client-secret") as client:
    models = client.get_models()
    print(f"Found {len(models)} models")

Environment variable overrides

You can override default endpoints using environment variables. This is useful for testing against a staging environment.

Constructor arguments always take precedence over environment variables.

Next steps

• Authentication — learn how the OAuth 2.0 flow works and how to manage credentials securely
• Reference — explore every method, data model, and exception in the SDK