Overview

This document explains how to perform forecasting and pricing using the Factor APIs instead of the UI, and how to retrieve the results.

The forecasting and pricing API requires the following key inputs to operate correctly:

1. Details of the prediction algorithm used to forecast energy consumption or generation data.

2. Connection configuration data, such as distribution and transmission loss factors or multipliers.

3. A set of pricing constructs or charges calculated from meter usage data. These are typically synchronized with Factor continuously but can also be created immediately before a forecast if custom prices apply.

4. Historical metering data.

Note that a single forecasting and pricing request can be executed for multiple connections or service points, each with its own connection configuration and pricing.

Prerequisites

Before integrating with the APIs, you must configure your first OAuth2 token in the Factor application. Refer to the following article for detailed instructions:

📄 Creating an OAuth2 Client

Key entities

Partitions

📄 Understanding Partitions, Temporal expressions and their purpose

Partitions can be created, updated, and retrieved via the API, although using the AI features in the UI may be more convenient.

Partitions have unique identifiers and part names, both of which are referenced only in temporal rates.

Loss factors

Loss factor files can be uploaded via the API. Loss values can then be referenced in forecast payloads. Loss factors apply only to rates that have loss types defined.

Rate sets

📄 Understanding Rate Sets and their purpose

Rate sets can be created, updated, and retrieved via the API. Each rate set has a unique identifier referenced in the forecast API payload. A Rate set contains one or more rates - where each rate specifies the type of calculation to be performed, its associated configuration, and the price / amount.

Price indices

📄 Understanding Price Indices

Price curves can be created and updated via the API. Each price curve has a unique identifier referenced when defining the curve. Note to use a price index - you must reference it on a rate within a rateset.

Consumption / Generation data

📄 Supported Consumption File Formats

Consumption and generation data can be imported via the API. The upload process returns a reference for each file, which is then included in the forecast API payload.

Forecasting and pricing

The forecasting and pricing APIs utilise the following reference data:

• Rate sets

• Consumption and generation data

The following configurations are included in the forecast payload:

• Forecast metadata

• Loss factor codes

• Forecast type (e.g., forecast, rating only, battery load forecast)

• Battery configuration, including capacity, draw, charging, and discharging schedules

Error handling

Synchronous errors

• If a rate or partition is created that does not comply with the API definition, the API returns an immediate error.

• If a forecast is created that either does not meet the API definition or includes an invalid configuration (e.g., a non-existent rate set), the API returns an immediate error.

Asynchronous errors

• Uploading consumption/generation data, loss files, and price indices requires processing. The status of file uploads must be checked via an API call.

• Forecast requests generate a unique identifier used to retrieve forecast results and initiate the forecasting process in Factor. If downstream errors occur during processing, they are returned when retrieving the forecast results via the API.