Scaling Utility Demand Response Programs with Energy API: Automating Event Triggering, Enrollment, and Settlement

Demand response (DR) is no longer a pilot program; it’s core grid infrastructure. Yet many utilities and load-serving entities still coordinate DR events with brittle spreadsheets, ad-hoc emails, and manually assembled market data. This slows down dispatch decisions, increases settlement risk, and makes it nearly impossible to scale from thousands to hundreds of thousands of enrolled devices. For developers asked to “automate DR,” the first hurdle is reliable, normalized wholesale market data that can drive triggers, optimize enrollments, and reconcile payouts without feeding the beast of custom ETL jobs across dozens of incompatible data portals.

This post shows how to build a production-grade DR automation loop using Energy API: a single REST surface that normalizes electricity, gas, oil, coal, carbon allowance, and grid carbon intensity into one consistent JSON schema. We’ll connect the dots between day-ahead curves, intraday updates, next-auction forecasts, emissions intensity, and settlement helpers—so your team can move from “we think we can do this” to a tested, observable pipeline that dispatches at the right time, enrolls the right customers, and settles the right payouts.

We will focus on practical developer workflows: event triggering from price thresholds, recruitment targeting via carbon intensity and expected value, and automated settlement with reproducible, timestamped market references. All examples use direct HTTP calls against a unified base URL and produce consistent JSON across electricity and related commodities. By the end, you’ll be ready to wire these endpoints into your DR platform, trading backend, or sustainability analytics stack and run it in 24/7 production.

Why Energy API

If you’re orchestrating DR, you need multiple market references: day-ahead curves to plan, near-real-time updates to refine, emissions intensity for ESG logic, and related commodities (gas, carbon) to calibrate expected value and dispatch logic. Traditionally, each source publishes in different formats, time zones, and schedules, forcing you to write and maintain brittle scrapers and normalization code. Energy API removes that burden in four critical ways:

• One normalized REST surface for all relevant energy categories. Instead of stitching together OMIE-like hourly curves, ENTSO-E-style feeds, or US/EU commodity references, you call a single set of endpoints with a single JSON schema and shared field semantics. That means one parser, one validator, one alerting pipeline.
• Breadth that matches your planning reality. With 39+ symbols across electricity, gas, oil, coal, carbon allowances, and grid carbon intensity, you can execute cross-commodity logic in the same call. For DR, this enables richer dispatch triggers (e.g., electricity price spike combined with contemporaneous carbon intensity or gas pressure on marginal generation).
• Intraday electricity curves and day-ahead auction results where available. You can combine day-ahead hourly or 15-minute curves for planning with intraday checks and next-auction forecasts for the very next delivery day. This is essential to trigger enrollment reminders and finalize strike windows reliably.
• Consistent operations and monitoring. Endpoints like /status help you watch provider health, while fluctuation and timeseries endpoints make it trivial to compute trend-based triggers without wrangling CSVs. Same fields, same error shape, clear validation.

From a developer perspective, the key benefit is time-to-production: one JSON schema for prices, timeseries, OHLC, volatility stats, intraday curves, and grid intensity. You spend your time on business logic—event triggers, segmentation, settlement—rather than ETL glue code.

Quick Start

The base URL for all requests is:

https://energy-api.com/api/v1

Authentication is provided via an api_key query parameter. The same approach works across all endpoints and commodities. Here’s a single call that fetches the latest prices for oil, gas, and carbon allowances—so you can make a cross-commodity DR dispatch decision with one round trip.

curl -G https://energy-api.com/api/v1/latest \
--data-urlencode "symbols=BRENT_CRUDE,TTF_GAS,EUA_CO2" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"date": "2026-06-11",
"base": "MIXED",
"rates": {
"BRENT_CRUDE": 74.82,
"TTF_GAS": 38.15,
"EUA_CO2": 67.40
},
"dates": {
"BRENT_CRUDE": "2026-06-11",
"TTF_GAS": "2026-06-11",
"EUA_CO2": "2026-06-11"
},
"currencies": {
"BRENT_CRUDE": "USD",
"TTF_GAS": "EUR",
"EUA_CO2": "EUR"
}
}

Key fields:

• success: Indicates a valid payload.
• date: The effective date for the overall response.
• rates: Symbol-to-price mapping.
• dates: Publication dates per symbol, useful for late publishing days or holidays.
• currencies: Per-symbol currency codes; currency handling is explicit and predictable.

This shape is consistent across categories—electricity, gas, oil, coal, carbon allowances, and carbon intensity—so you can re-use the same parser and merge logic anywhere in your DR orchestration.

Core Endpoints for Demand Response Automation

Below are the endpoints most teams rely on to automate DR event triggering, customer enrollment messaging, and downstream settlement. For each, you’ll see the path, key parameters, a cURL snippet, a realistic JSON response, and how to use the data effectively in your platform.

1) Electricity intraday curves for operational timing (/electricity/hourly)

Path: GET /electricity/hourly

Purpose: Retrieve the full intraday curve (hourly or 15-minute, depending on the symbol) for a given electricity symbol and date. Use this to determine peak windows, refine triggers close to delivery, and align device-level controls with market reality.

Key params:

• symbol (required): e.g., OMIE_ES_DA (Spain day-ahead), EPEX_DE_DA (Germany).
• date (required): YYYY-MM-DD (the delivery date).

curl -G https://energy-api.com/api/v1/electricity/hourly \
--data-urlencode "symbol=OMIE_ES_DA" \
--data-urlencode "date=2026-06-12" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"symbol": "OMIE_ES_DA",
"date": "2026-06-12",
"currency": "EUR",
"frequency": "hourly",
"curve": [
{"time": "2026-06-12T00:00:00+02:00", "price": 58.10},
{"time": "2026-06-12T01:00:00+02:00", "price": 53.40},
{"time": "2026-06-12T07:00:00+02:00", "price": 74.90},
{"time": "2026-06-12T12:00:00+02:00", "price": 69.50},
{"time": "2026-06-12T19:00:00+02:00", "price": 92.30},
{"time": "2026-06-12T20:00:00+02:00", "price": 95.10}
],
"notes": "Truncated for brevity; full 24-hour curve is returned."
}

How to use it:

• curve: Your primary feed for intra-day or day-ahead scheduling. Many DR programs set strike logic like “Trigger if any hour exceeds 90 EUR/MWh,” then compute expected customer payouts based on the count and magnitude of high-price hours.
• frequency and currency: Make unit and granularity explicit in your UI and settlement logic. For multi-country portfolios, store currency per reading to avoid accidental conversions.
• time fields include timezone offsets: Persist the original offsets and convert to your operations timezone just before scheduling to prevent daylight-savings edge cases.

2) Next day-ahead auction result for planning (/forecast)

Path: GET /forecast

Purpose: Retrieve the next published day-ahead price for an auction-sourced electricity symbol. Use this to pre-stage DR events (customer notifications, opt-in confirmations) hours before final intraday tuning.

Key params:

• symbol (required): Must be an auction-based electricity symbol; returns 404 if not applicable.

curl -G https://energy-api.com/api/v1/forecast \
--data-urlencode "symbol=EPEX_DE_DA" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"symbol": "EPEX_DE_DA",
"forecast_date": "2026-06-12",
"currency": "EUR",
"expected_curve": [
{"time": "2026-06-12T00:00:00+02:00", "price": 62.45},
{"time": "2026-06-12T08:00:00+02:00", "price": 88.30},
{"time": "2026-06-12T19:00:00+02:00", "price": 97.10}
],
"status": "published"
}

How to use it:

• expected_curve: Treat this as the deterministic day-ahead schedule from the auction’s official publication. Trigger pre-event customer messaging (email, SMS, app push) using high-price windows as a preview.
• status: Confirm that the auction has been published. If your job runs continuously, switch your DR plan from “pending forecast” to “ready to dispatch” once status is published.

3) Cross-commodity latest prices for composite triggers (/latest)

Path: GET /latest

Purpose: Fetch the most recent prices for multiple symbols across categories in one request. This enables composite triggers such as “Trigger DR when electricity exceeds X AND carbon allowances indicate high marginal emissions risk” or “Avoid event when gas prices collapse and expected peak is muted.”

Key params:

• symbols (required): Comma-separated list, e.g., OMIE_ES_DA, EUA_CO2, TTF_GAS.
• base (optional): Request currency filtering if needed.

curl -G https://energy-api.com/api/v1/latest \
--data-urlencode "symbols=OMIE_ES_DA,EUA_CO2,TTF_GAS" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response (abbreviated fields explained earlier in Quick Start):

{
"success": true,
"date": "2026-06-11",
"base": "MIXED",
"rates": {
"OMIE_ES_DA": 71.20,
"EUA_CO2": 67.40,
"TTF_GAS": 38.15
},
"dates": {
"OMIE_ES_DA": "2026-06-11",
"EUA_CO2": "2026-06-11",
"TTF_GAS": "2026-06-11"
},
"currencies": {
"OMIE_ES_DA": "EUR",
"EUA_CO2": "EUR",
"TTF_GAS": "EUR"
}
}

How to use it:

• Compose triggers combining electricity and related commodities. For example, require both a price threshold and a volatility increase (checked via /fluctuation below) before dispatch, to avoid noisy activations.
• Record dates and currencies per symbol for future audit, so settlement calculations match the exact reference used at trigger time.

4) Price movement over a window for volatility gating (/fluctuation)

Path: GET /fluctuation

Purpose: Calculate start/end values, absolute change, and percentage change. This is ideal for volatility gating (e.g., “Only trigger DR if week-over-week increase exceeds 20%”) or for predicting customer savings expectations as part of enrollment campaigns.

Key params:

• start (required), end (required): YYYY-MM-DD bounds.
• symbols (required): One or more; supports mixed categories.

curl -G https://energy-api.com/api/v1/fluctuation \
--data-urlencode "start=2026-06-01" \
--data-urlencode "end=2026-06-11" \
--data-urlencode "symbols=OMIE_ES_DA,EUA_CO2" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"base": "MIXED",
"period": {"start": "2026-06-01", "end": "2026-06-11"},
"fluctuations": {
"OMIE_ES_DA": {
"start_value": 56.80,
"end_value": 71.20,
"change": 14.40,
"change_pct": 25.35
},
"EUA_CO2": {
"start_value": 62.10,
"end_value": 67.40,
"change": 5.30,
"change_pct": 8.53
}
}
}

How to use it:

• change_pct helps gate events: you might avoid dispatch on “normal” days to reduce fatigue and save capacity for high-impact spikes.
• Use OMIE_ES_DA and EUA_CO2 together to estimate emissions-adjusted savings value when marketing DR enrollments during volatile weeks.

5) Historical series for backtesting and settlement audits (/timeseries)

Path: GET /timeseries

Purpose: Pull historical data across a date range and one or more symbols. Use it to backtest trigger thresholds, compute seasonal patterns, and generate settlement audit reports showing the exact reference series used per event.

Key params:

• start (required), end (required): YYYY-MM-DD.
• symbols (required): One or more symbols, mixed categories allowed.

curl -G https://energy-api.com/api/v1/timeseries \
--data-urlencode "start=2026-04-01" \
--data-urlencode "end=2026-06-11" \
--data-urlencode "symbols=OMIE_ES_DA,EUA_CO2,TTF_GAS" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response (partial):

{
"success": true,
"base": "MIXED",
"start_date": "2026-04-01",
"end_date": "2026-06-11",
"rates": {
"OMIE_ES_DA": {
"2026-06-10": 68.90,
"2026-06-11": 71.20
},
"EUA_CO2": {
"2026-06-10": 66.85,
"2026-06-11": 67.40
},
"TTF_GAS": {
"2026-06-10": 37.60,
"2026-06-11": 38.15
}
},
"frequencies": {
"OMIE_ES_DA": "daily",
"EUA_CO2": "daily",
"TTF_GAS": "daily"
},
"currencies": {
"OMIE_ES_DA": "EUR",
"EUA_CO2": "EUR",
"TTF_GAS": "EUR"
}
}

How to use it:

• rates: A date-keyed series per symbol. Use aligned dates to compute blended metrics like price x carbon intensity, or gas-to-power margin proxies, then test whether your DR triggers would have fired appropriately in the past.
• frequencies and currencies: Provide metadata for chart labeling and unit conversion pipelines when generating BI dashboards for operations and finance.

6) Grid carbon intensity for ESG-aware dispatch (/carbon-intensity)

Path: GET /carbon-intensity

Purpose: Fetch grid carbon intensity (gCO2eq/kWh) for a given country. Use it to prioritize DR events during periods of higher marginal emissions for maximum environmental impact and to populate sustainability reporting dashboards that explain why an event was called.

Key params:

• country (ISO-2): e.g., DE, ES, FR, IT.

curl -G https://energy-api.com/api/v1/carbon-intensity \
--data-urlencode "country=DE" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"country": "DE",
"unit": "gCO2eq/kWh",
"date": "2026-06-11",
"intensity": 402
}

How to use it:

• intensity provides a clear environmental signal. Combine with electricity prices to build a score: score = normalize(price) + normalize(intensity). Trigger events when the score exceeds a threshold to maximize both savings and decarbonization.

7) Retail reference and customer messaging calibration (/electricity/pvpc)

Path: GET /electricity/pvpc

Purpose: Retrieve hourly Spanish PVPC reference prices. Useful for translating wholesale-driven DR events into messages that make sense to retail customers (“Tonight 20:00–21:00 is one of the most expensive hours this month”).

Key params:

• date (required): YYYY-MM-DD.

curl -G https://energy-api.com/api/v1/electricity/pvpc \
--data-urlencode "date=2026-06-12" \
--data-urlencode "api_key=YOUR_API_KEY"

Example response (partial):

{
"success": true,
"date": "2026-06-12",
"currency": "EUR",
"frequency": "hourly",
"hours": [
{"time": "2026-06-12T20:00:00+02:00", "price": 0.214},
{"time": "2026-06-12T21:00:00+02:00", "price": 0.219}
]
}

How to use it:

• Translate wholesale triggers into retail-facing communication that references the same time blocks customers will see on their bills or apps, improving trust and opt-in rates.

8) Pre-check provider health before scheduling jobs (/status)

Path: GET /status

Purpose: Inspect last fetch status per provider category—vital for production reliability. Before you schedule a DR event based on the latest auction or intraday curve, verify that upstream fetches are healthy to avoid acting on stale data.

curl -G https://energy-api.com/api/v1/status \
--data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"providers": [
{"name": "electricity", "last_fetch": "2026-06-11T13:10:00Z", "status": "ok"},
{"name": "gas", "last_fetch": "2026-06-11T13:05:00Z", "status": "ok"},
{"name": "carbon", "last_fetch": "2026-06-11T13:07:00Z", "status": "ok"}
]
}

How to use it:

• Check status is ok and last_fetch is within your freshness SLO (e.g., 30 minutes) before running trigger evaluation or publishing event notifications.
• If status is degraded, pause dispatch automation and alert an operator; fail-safe to previously published schedules and communicate clearly with customers.

9) Simple settlement helper (/cost-estimate)

Path: POST /cost-estimate

Purpose: Calculate a simple monthly wholesale electricity cost estimate (latest price × kWh/month). While real DR settlement is more nuanced, this gives finance and CX teams a quick reference to estimate customer impacts and set expectations.

Body params:

• symbol OR country (one required)
• kwh_per_month (required)

curl -X POST https://energy-api.com/api/v1/cost-estimate \
-H "Content-Type: application/json" \
-d '{
"symbol": "OMIE_ES_DA",
"kwh_per_month": 350
}' \
--get --data-urlencode "api_key=YOUR_API_KEY"

Example response:

{
"success": true,
"symbol": "OMIE_ES_DA",
"kwh_per_month": 350,
"latest_price": 71.20,
"currency": "EUR",
"estimated_monthly_cost": 24,920
}

How to use it:

• estimated_monthly_cost can seed your customer-facing calculators and internal planning docs. Make clear this excludes taxes, network charges, and hourly profile effects; then tie final settlement to precise hourly prices from /electricity/hourly.

Building a DR Automation Loop with Energy API

To operationalize DR at scale, you’ll want an event loop that ingests market data, evaluates triggers, coordinates enrollment messaging, executes dispatch commands, and performs settlement—all with observability. Here’s a reference pattern many teams implement using the endpoints above:

• Job scheduler and health gate:
  • Every 5 minutes, check /status. If any critical category is stale or failing, skip downstream jobs and raise an alert.
• Day-ahead planning:
  • At auction publication, call /forecast for your delivery regions (e.g., EPEX_DE_DA, OMIE_ES_DA). Identify candidate peak windows and pre-stage event notices with opt-out links.
• Intraday refinement:
  • On event day, retrieve /electricity/hourly. If realized prices deviate, update dispatch windows and device setpoints accordingly. For ESG overlays, also fetch /carbon-intensity for jurisdictions and compute a composite score.
• Composite triggers and volatility gating:
  • Combine /latest across electricity, TTF_GAS, and EUA_CO2 with /fluctuation over recent days to ensure you only call events during materially impactful periods. This improves customer satisfaction and grid value.
• Settlement and audit:
  • Persist all fetched curves and snapshot responses with timestamps. For customer-level settlement, intersect device participation intervals with the exact hourly prices and intensity values. Use /timeseries for historical lookbacks and reporting.

Throughout, store the per-symbol currency and effective dates that come in every response; this is critical for downstream finance controls, cross-currency reporting, and regulator or PUC audits.

Implementation Examples: cURL, Python, and JavaScript

Below are compact examples for quickly integrating Energy API into your DR orchestration stack. All examples assume you pass an api_key as a query parameter.

Example: Identify next-day peak windows (cURL + JSON)

curl -G https://energy-api.com/api/v1/forecast \
--data-urlencode "symbol=OMIE_ES_DA" \
--data-urlencode "api_key=YOUR_API_KEY"

Parse expected_curve, sort by price descending, and take the top N hours as candidate event windows. Persist the forecast_date and prices for audit.

Example: Intraday refinement and carbon-aware score (Python)

import requests
from datetime import date

BASE = "https://energy-api.com/api/v1"
API_KEY = "YOUR_API_KEY"

def get_hourly(symbol, d):
r = requests.get(f"{BASE}/electricity/hourly", params={"symbol": symbol, "date": d, "api_key": API_KEY})
r.raise_for_status()
return r.json()

def get_intensity(country):
r = requests.get(f"{BASE}/carbon-intensity", params={"country": country, "api_key": API_KEY})
r.raise_for_status()
return r.json()

def composite_score(price, intensity):
# Example normalization; calibrate for your portfolio
return (price / 100.0) + (intensity / 500.0)

if __name__ == "__main__":
d = date.today().isoformat()
hourly = get_hourly("OMIE_ES_DA", d)
ci = get_intensity("ES") # grid intensity for Spain
intensity_val = ci["intensity"]

enriched = []
for pt in hourly["curve"]:
score = composite_score(pt["price"], intensity_val)
enriched.append({"time": pt["time"], "price": pt["price"], "intensity": intensity_val, "score": score})

# Pick hours above a threshold for DR event
candidates = [x for x in enriched if x["score"] > 1.5]
for c in candidates:
print(c)

Example: Backtest trigger thresholds over the last 90 days (JavaScript/Node)

import fetch from "node-fetch";

const BASE = "https://energy-api.com/api/v1";
const API_KEY = "YOUR_API_KEY";

async function fetchTimeseries(start, end, symbols) {
const url = new URL(`${BASE}/timeseries`);
url.searchParams.set("start", start);
url.searchParams.set("end", end);
url.searchParams.set("symbols", symbols.join(","));
url.searchParams.set("api_key", API_KEY);
const res = await fetch(url.toString());
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return await res.json();
}

(async () => {
const json = await fetchTimeseries("2026-03-13", "2026-06-11", ["OMIE_ES_DA", "EUA_CO2"]);
const elec = json.rates["OMIE_ES_DA"];
const days = Object.keys(elec).sort();
let triggers = 0;
for (const day of days) {
const price = elec[day];
const co2 = json.rates["EUA_CO2"][day];
const score = price / 100 + (co2 / 500);
if (score > 1.6) triggers++;
}
console.log({ days: days.length, triggers });
})();

Data Modeling and Field Semantics

Energy API delivers a consistent schema across categories:

• Top-level success boolean and explicit error payload on failures.
• Per-symbol currencies and frequencies to guard against incorrect assumptions.
• Date- or time-indexed structures that are easy to traverse in any language.
• Deterministic types: numeric prices, ISO dates, and offset-aware timestamps for hourly curves.

A simple rule-of-thumb for DR developers: persist every response with a checksum and the retrieval timestamp. For hourly curves, store the array in the original order and timezone. This reduces reconciliation risk when showing regulators or internal audit how a particular dispatch window was chosen and settled.

Advanced Planning with Additional Endpoints

While the endpoints above cover 90% of DR automation, several others add useful depth for developers building robust systems:

/symbols: Discoverability and metadata

Use /symbols to enumerate available markets and metadata such as category, currency, frequency, and country code. This supports dynamic UI selection and automated portfolio expansion when your DR program enters a new region.

curl -G https://energy-api.com/api/v1/symbols \
--data-urlencode "category=electricity" \
--data-urlencode "api_key=YOUR_API_KEY"

{
"success": true,
"count": 3,
"symbols": [
{
"symbol": "OMIE_ES_DA",
"name": "Spain Day-Ahead Electricity",
"category": "electricity",
"country_code": "ES",
"currency_code": "EUR",
"frequency": "daily",
"description": "Official day-ahead auction result."
}
]
}

/gas/latest and /emissions/latest: Fast composite signals

If your trigger logic often references gas and carbon, the category endpoints provide quick lookups:

curl -G https://energy-api.com/api/v1/gas/latest \
--data-urlencode "api_key=YOUR_API_KEY"

curl -G https://energy-api.com/api/v1/emissions/latest \
--data-urlencode "api_key=YOUR_API_KEY"

These are ideal for cron-triggered signals that augment electricity prices with production-cost proxies and emissions costs.

/ohlc: Volatility snapshots for risk controls

For weekly or monthly program reviews, /ohlc provides canonical candles for volatility analysis and reporting. For example, assess whether your DR events aligned with multi-week stress periods or were triggered by short-lived noise.

curl -G https://energy-api.com/api/v1/ohlc \
--data-urlencode "symbols=OMIE_ES_DA" \
--data-urlencode "period=monthly" \
--data-urlencode "start=2026-01-01" \
--data-urlencode "end=2026-06-11" \
--data-urlencode "api_key=YOUR_API_KEY"

The response is an array of open, high, low, close per period for each symbol—great for compliance dashboards and post-mortem reviews.

Operational Best Practices

DR systems must be reliable, observable, and auditable. The following practices help productionize quickly:

• Freshness SLOs:
  • Gate critical jobs on /status. Require last_fetch within a tolerance (e.g., 30 minutes) and status ok before evaluating triggers or publishing events.
• Retry and backoff:
  • Implement exponential backoff and idempotent retries for transient network failures. If an endpoint responds with a structured 422 (validation) or 404 (not applicable), surface a clear operator message rather than retrying blindly.
• Timezones and DST:
  • Persist original timestamps with offsets from /electricity/hourly and /electricity/pvpc. Convert to operational timezones at the schedule-execution boundary, not before.
• Unit safety:
  • Always use the currencies map or currency field from responses. Do not assume EUR or USD; mixed portfolios are common and easy to mis-handle without explicit unit checks.
• Audit and reproducibility:
  • Store raw JSON responses alongside derived metrics (e.g., thresholds crossed). Include a hash of the payload and your computation version; this makes settlement disputes easy to resolve.
• Backtesting and drift detection:
  • Use /timeseries and /fluctuation to routinely revalidate trigger thresholds. If your triggers are firing too often or too rarely, programmatically tune thresholds based on recent price and volatility profiles.
• Portfolio expansion:
  • Programmatically discover new symbols with /symbols when entering additional markets. Keep your trigger logic generic and inject symbols and countries as data, not code branches.

End-to-End Example: Trigger, Enroll, Settle

This example outlines a minimal but complete loop using Energy API endpoints. Replace queues and databases with your platform choices.

1. Gate and preload:
   • Check /status. If ok, fetch /forecast for next day (EPEX_DE_DA and OMIE_ES_DA). Identify top-3 hours per market for candidate dispatch.
2. Enroll and notify:
   • Notify customers in relevant geos about candidate hours. Translate to local time zones. If in Spain, optionally include /electricity/pvpc references to contextualize expected retail impact.
3. Event-day refinement:
   • Pull /electricity/hourly at T–1 hour and compute composite score with /carbon-intensity. Adjust windows up to T–15 minutes subject to program rules.
4. Dispatch:
   • Send device commands for enrolled assets during final windows. Archive all fetched JSON, decision logs, and commands with timestamps.
5. Settlement:
   • Reconstruct each participant’s event intervals and multiply by the settled hourly price series from /electricity/hourly for the delivery date and symbol. For reports, include /timeseries snapshots to show context before/after the event window, plus change_pct from /fluctuation over the week.

With this loop, you get fully automated event selection backed by traceable market references. The decision-making remains transparent to regulators and customers alike.

Real-World Use Cases

Portfolio-wide price alerting and DR triggers

A utility runs a background service that calls /latest for OMIE_ES_DA, EUA_CO2, and TTF_GAS every five minutes and /fluctuation for the last 7–10 days each hour. Alerts are only raised when price exceeds a configured threshold AND weekly change_pct is above a volatility floor. This reduces nuisance events and protects customer satisfaction while focusing interventions on high-impact periods. Endpoints: /latest, /fluctuation, /status.

ESG-aware enrollment targeting

A sustainability product team builds a segmentation model that combines hourly electricity curves with national grid carbon intensity. Customers in regions and time windows with high intensity get proactive enrollment nudges (“Shift 19:00–21:00 today to avoid peak emissions”). Peak windows come from /electricity/hourly or /forecast; carbon signals from /carbon-intensity. Endpoints: /electricity/hourly, /forecast, /carbon-intensity.

Post-event settlement and analytics

A DR aggregator computes per-customer settlement by intersecting asset telemetry with the published hourly curve for the delivery day, appending an audit trail that includes exact symbol currency and publication timestamps. Trend charts in the backoffice reference /timeseries to give finance and compliance a month-over-month view. Endpoints: /electricity/hourly, /timeseries, /symbols.

Error Handling and Troubleshooting

Energy API returns explicit HTTP status codes and a consistent error body:

• 401: Missing or invalid api_key.
• 404: No data for the given symbols or date (e.g., using /forecast with a non-auction symbol).
• 422: Validation error (missing required params, invalid formats, unsupported values).
• 429: Rate limit exceeded; implement exponential backoff with jitter and retry later.

All error responses follow:

{
"success": false,
"error": "Human-readable message."
}

Troubleshooting checklist:

• Parameter validation: Confirm symbol names (e.g., OMIE_ES_DA, EPEX_DE_DA, PVPC_ES_2TD) and date formats (YYYY-MM-DD).
• Time alignment: For hourly series, ensure your app respects timezone offsets returned in time fields. Avoid converting times twice when storing and scheduling.
• Currency consistency: Prices are returned in their native currencies per symbol; ensure any aggregations convert appropriately or present multi-currency values explicitly.
• Provider freshness: Query /status when data appears stale; verify last_fetch and status before assuming a publishing delay.

FAQ

How often do electricity prices update, and can I get intraday curves?

Yes. When sources publish them, /electricity/hourly returns hourly or 15-minute intraday curves for a given symbol and date. For planning before delivery, /forecast returns the next published day-ahead auction result for auction-based symbols. Many teams poll /electricity/hourly near event time to refine dispatch windows.

Can I fetch multiple commodities in one call?

Yes. /latest, /timeseries, and /fluctuation support multiple symbols across categories in a single request. This is ideal for composite DR triggers that combine electricity, gas, and carbon signals without multiple round trips.

Do responses include currencies and frequencies so I can avoid unit mistakes?

Yes. Every response includes currency information per symbol (and frequency where relevant). Always read and persist those fields to ensure safe conversions and correct chart labeling across mixed portfolios.

How do I backtest DR triggers before I go live?

Use /timeseries to pull historical data for electricity symbols and related commodities. Combine it with /fluctuation for change_pct metrics, then simulate your thresholds across weeks or months. Store the exact symbol metadata and dates so your results are reproducible.

What happens if there’s no data for a symbol on a given date?

/historical returns the most recent value before the requested date when a publishing day is missing, while other endpoints may return 404 for unsupported lookups. Always check the HTTP code and the error field in the response to handle edge cases gracefully.

Conclusion + CTA

Scaling a modern demand response program requires more than just device control—it demands the right data at the right time, in a reliable and normalized form. With a single REST surface that spans electricity curves, day-ahead forecasts, cross-commodity references, and carbon intensity, Energy API turns weeks of ETL work into a few hours of implementation. Your team can focus on dispatch logic, enrollment strategy, and settlement accuracy, not chasing down CSVs and reconciling incompatible schemas.

Whether you’re orchestrating megawatt-scale events across multiple countries or piloting a neighborhood battery program, the architecture stays the same: gate on provider health, plan with day-ahead curves, refine intraday, apply ESG overlays, and settle with auditable hourly series. Each step maps cleanly to an endpoint, and every response includes the metadata you need to avoid unit and timezone pitfalls.

If you’re ready to move from brittle scripts to a robust DR automation loop, start building with Energy API. Explore the endpoints, wire up your triggers, and ship faster than you thought possible—then iterate with confidence as your portfolio grows. Try Energy API for free and turn reliable market data into scalable demand response.