Discover models

The pd4castr API organises forecasting models into model groups. Each group contains one or more revisions of a model, allowing for the publication of new versions without breaking your existing workflows. The SDK provides methods to browse groups, list their models, and inspect model details.

All the examples on this page assume you’ve already created a client:

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

List model groups

Use get_model_groups() to retrieve every model group you have access to, including your organisation’s private groups and any public ones.

groups = client.get_model_groups()
 
for group in groups:
    print(f"{group.name} (latest revision: r{group.latest_revision})")

Each ModelGroup includes:

  • id — the unique identifier you’ll pass to other methods
  • name — a human-readable name for the group
  • latest_revision — the highest revision number available
  • public — whether the group is visible to all organisations
  • created_at — when the group was created

Browse models in a group

Once you’ve identified a group, call get_model_group_models() to list every model revision it contains. This is useful when you need a specific revision or want to see how a model has evolved over time.

models = client.get_model_group_models("your-model-group-id")
 
for model in models:
    print(f"  r{model.revision}: {model.display_name}")

Models are returned for all revisions in the group. Each model has its own unique id, which you use when fetching runs and forecast output.

Get the latest model

If you always want the most recent revision in a group, use the get_latest_model() convenience method. It fetches all models in the group and returns the one with the highest revision number.

model = client.get_latest_model("your-model-group-id")
print(f"{model.display_name} (r{model.revision})")

This is the recommended approach for automated pipelines that should always use the newest model version without manual updates.

Inspect model details

Every Model object carries rich metadata about what the model produces and how it’s configured. You can fetch a specific model by ID with get_model(), or use any model returned by the listing methods above.

model = client.get_model("your-model-id")
 
print(f"Name:              {model.display_name}")
print(f"Time horizon:      {model.horizon.name}")
print(f"Forecast variable: {model.forecast_variable.name}")
print(f"Timezone:          {model.display_timezone}")
print(f"Output format:     {model.output_file_format}")

Sensitivities

A model’s sensitivities field lists the scenario variants it supports. You can also fetch them separately with get_model_sensitivities().

for s in model.sensitivities:
    print(f"  {s.name} ({s.id})")

Output specification

The output_specification field describes the columns in the model’s forecast output, including their names and types.

for col in model.output_specification:
    print(f"  {col.name}: {col.type}")

Filter models by time horizon

If you’re only interested in models for a particular time horizon, pass the time_horizon parameter to get_models(). This returns models across all groups that match the given horizon.

day_ahead = client.get_models(time_horizon="day_ahead")
 
for model in day_ahead:
    print(f"{model.display_name} (r{model.revision})")

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

Next steps

  • Fetch latest forecast — retrieve forecast output for a model run
  • Reference — explore every method, data model, and exception in the SDK