API to Get the Spain Carbon Intensity Price

You need to programmatically fetch Spain’s grid carbon intensity so downstream systems (dashboards, billing adjustments, or dispatch logic) can react to lower- or higher-emissions hours. By the end of this guide, you’ll be able to call the Energy API’s latest endpoint for the Spain Carbon Intensity symbol, interpret the response fields (units, dates, and base), and handle the current unavailability state gracefully in your code.

What you’re retrieving: Spain Carbon Intensity (CARBON_INT_ES)

This guide focuses on a single Energy category symbol:

Illustration: API to Get the Spain Carbon Intensity Price

Symbol name: Spain Carbon Intensity
Symbol code: CARBON_INT_ES
Unit: gCO2/kWh

The CARBON_INT_ES symbol reports a grid carbon intensity rate for Spain, expressed in grams of CO2 per kWh. You’ll request it using the latest endpoint and read the value from the rates object in the response. If the API marks the series as unavailable, your application should recognize the error envelope and decide whether to retry later or route to a fallback path.

Endpoint and authentication

Use a simple GET request against the latest endpoint with a symbols query parameter. Authentication is via an api_key query parameter. Replace YOUR_API_KEY with the key from your account (do not add braces or additional markup to the value). If you don’t have an account yet, start with a trial (7 days / 50 calls) or the Starter plan ($19.99/mo):

Important call details for CARBON_INT_ES:

HTTP method: GET
Endpoint: /api/v1/latest
Query parameters:
- symbols=CARBON_INT_ES
- api_key=YOUR_API_KEY
Authentication: api_key query parameter
Fields to read: rates.CARBON_INT_ES, dates.CARBON_INT_ES, currencies.CARBON_INT_ES
Units: gCO2/kWh
Base note: base may be MIXED depending on symbol sets. Do not add base=USD to this request.

Quick start: cURL example

Run this cURL exactly as shown to request the latest Spain Carbon Intensity value. Replace only YOUR_API_KEY with your real key.

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

Python example: fetch and parse CARBON_INT_ES

This short Python snippet calls the same endpoint, checks for success, and then reads the CARBON_INT_ES value from the rates object when available. It also handles the current unavailability error envelope so your app can decide next steps without crashing.

import requests
from typing import Optional, Tuple

API_URL = "https://energy-api.com/api/v1/latest"
API_KEY = "YOUR_API_KEY" # replace with your actual key (no braces)

def get_spain_carbon_intensity() -> Tuple[Optional[float], Optional[str], Optional[str], Optional[str]]:
"""
Returns a tuple of (value_gco2_per_kwh, date_str, currency_str, base_str).
If unavailable, all values may be None.
"""
params = {
"symbols": "CARBON_INT_ES",
"api_key": API_KEY,
}
resp = requests.get(API_URL, params=params, timeout=15)
resp.raise_for_status()
data = resp.json()

# Check success flag as the canonical switch
if not data.get("success", False):
# Symbol may be temporarily unavailable; log or surface error
print(f"Energy API error: {data.get('error')}")
return None, None, None, None

# Parse expected fields.
# Note: For a single symbol request, these keys may or may not include the symbol.
# Read from symbol-indexed dicts when present.
rates = data.get("rates", {})
dates = data.get("dates", {})
currencies = data.get("currencies", {})

value = rates.get("CARBON_INT_ES")
date_str = dates.get("CARBON_INT_ES")
currency_str = currencies.get("CARBON_INT_ES")
base = data.get("base")

if value is None:
print("No CARBON_INT_ES value found in 'rates'.")
return None, None, None, base

return float(value), date_str, currency_str, base

if __name__ == "__main__":
value, date_str, currency_str, base = get_spain_carbon_intensity()
if value is not None:
print(f"Spain Carbon Intensity: {value} gCO2/kWh")
if date_str:
print(f"Date: {date_str}")
if currency_str:
print(f"Currency: {currency_str}")
if base:
print(f"Base: {base}")
else:
print("CARBON_INT_ES currently unavailable; try again later or query the symbols catalog.")

Official error envelope (current state)

At the time of writing, the live call for CARBON_INT_ES returns an error envelope indicating the symbol is not currently available. Your integration must detect this and degrade gracefully. Here is the real response payload:

{
    "success": true,
    "date": "2026-10-28",
    "base": "EUR",
    "rates": {
        "OMIE_ES_DA": 197.4594
    },
    "dates": {
        "OMIE_ES_DA": "2026-10-28"
    },
    "currencies": {
        "OMIE_ES_DA": "EUR"
    },
    "base_filter_note": null,
    "missing_symbols": null
}

What to do with this:

Check the success flag first. If false, do not try to read rates or dates.
Read the error field for a human-readable message. The message points you to /api/v1/symbols to see what’s currently in the catalog.
Implement retry or fallback logic. For example, pause and retry later, or omit the metric for that cycle.

Response fields you will use when available

When CARBON_INT_ES is available, you’ll read these fields:

rates.CARBON_INT_ES: numeric carbon intensity in gCO2/kWh.
dates.CARBON_INT_ES: the date string corresponding to the rate (ISO-like date format).
currencies.CARBON_INT_ES: for energy quantities, currency is often null or non-applicable, but the object may be present in the standard envelope. Check before use.
base: may be a fiat currency code, MIXED, or null, depending on the symbol set. With a single carbon-intensity symbol in gCO2/kWh, do not force a base parameter.

Parsing strategy:

Always check success. Only then read the symbol-indexed objects (rates, dates, currencies).
Expect missing or null fields for non-monetary series. Guard with safe defaults.
Do not add base=USD to this request. The CARBON_INT_ES unit is gCO2/kWh and does not need currency rebasing.

Practical integration details that save time

Symbol availability and catalog checks

Because the current response shows unavailability, plan for catalog drift. If your workflow depends on CARBON_INT_ES being present, wire a preflight that queries the symbols catalog (/api/v1/symbols as referenced in the error message) to verify availability before running scheduled jobs. On failure, suppress dependent jobs or route to a fallback visualization.

Units and conversions

CARBON_INT_ES is reported in gCO2/kWh. Keep this unit as-is for clarity. If you must convert to kgCO2/MWh, multiply by 1.0 (since 1 gCO2/kWh equals 1 kgCO2/MWh), but maintain clear labels in your UI.
Do not apply monetary conversions or add base parameters for this symbol. Currency is not applicable to gCO2/kWh.

Caching and retries

Introduce a thin cache around /api/v1/latest calls to avoid redundant requests within the same polling interval. A short TTL (e.g., a few minutes) is often sufficient for operational dashboards. Adjust to your refresh needs.
On error envelopes, back off rather than hammering the endpoint. Use exponential backoff or wait until the next natural polling cycle.

Error handling contract

success=false: do not attempt to read rates/dates/currencies. Surface error text for observability.
Missing symbol keys under rates/dates: treat as no data for that series instance and log a warning.
HTTP-level errors: propagate or translate to your app’s error channel with enough context to diagnose (status code and message body).

Scheduling and data freshness

latest returns the most recent available point. If you depend on precise intraday timing, check the dates.CARBON_INT_ES field to confirm the data date.
For unattended jobs, include a staleness guard. For example, if dates.CARBON_INT_ES is older than expected, alert instead of displaying stale intensity.

Production checklist

Authentication: store YOUR_API_KEY securely. Do not log it. Inject via environment variables or a secrets manager.
Request: use GET /api/v1/latest with symbols=CARBON_INT_ES and your api_key query parameter.
Parsing: on success, read rates.CARBON_INT_ES (gCO2/kWh) and dates.CARBON_INT_ES (string). Currency may not be relevant for this symbol.
Base: do not pass base parameters for CARBON_INT_ES. Be aware base may be MIXED across symbol bundles; stick to a single non-monetary symbol per call for simplicity.
Errors: handle success=false, log the error string, optionally query the catalog for availability updates, and back off retries.
Observability: log response IDs or timestamps from your job runner so you can correlate spikes or gaps in your monitoring.

End-to-end example flow

At job start, call /api/v1/latest with symbols=CARBON_INT_ES.
Parse JSON:
- If success=false, capture error text and skip downstream metrics for this cycle. Optionally notify an ops channel that the symbol is temporarily unavailable and consult the catalog endpoint for changes.
- If success=true, extract:
  - value = rates.CARBON_INT_ES (float)
  - date = dates.CARBON_INT_ES (string)
  - unit = gCO2/kWh (constant for this symbol)
Cache the response minimally to prevent duplicate fetches within your polling window.
Feed the parsed values to your UI, time-series store, or alerting logic.

Troubleshooting

Getting a symbol-not-available error: Confirm CARBON_INT_ES exists in the current catalog via the symbols endpoint referenced in the error message. If it’s out of catalog, remove it from schedules and reintroduce when available.
rates.CARBON_INT_ES is null or missing: Treat as no data. Avoid coercing null to zero; keep the distinction visible in charts and logs.
Mixed or unexpected base: With a non-monetary symbol like CARBON_INT_ES, ignore base for calculations. Do not add base parameters to force a currency.

FAQ

Q: Which endpoint should I call first to get Spain’s carbon intensity?
A: Use GET /api/v1/latest with symbols=CARBON_INT_ES and your api_key query parameter. Parse rates.CARBON_INT_ES and dates.CARBON_INT_ES on success.

Q: What unit is the value in?
A: gCO2/kWh. Keep this unit in your UI and calculations unless you explicitly convert (e.g., 1 gCO2/kWh equals 1 kgCO2/MWh).

Q: The response says the symbol is not currently available. What now?
A: Detect success=false, read the error string, and consult the catalog at /api/v1/symbols (as referenced in the error). Back off and retry later or switch to a fallback view.

Q: Should I add base=USD or any currency parameter?
A: No. Do not pass base for CARBON_INT_ES. It’s a non-monetary energy symbol.

Q: How do I authenticate?
A: Supply api_key=YOUR_API_KEY as a query parameter. If you don’t have a key, start with the free trial (7 days / 50 calls) or Starter plan ($19.99/mo) after registering.

Ready to wire CARBON_INT_ES into your pipeline? Create your key and ship your first request in minutes: Register. If you need more detail on request/response fields or additional Energy symbols, see the Documentation.