bolt Energy API
Docs Symbols MCP Pricing Blog
Log in Get API Key

API to Get the Italy Carbon Intensity Price

API to Get the Italy Carbon Intensity Price

You need a fast, reliable way to query Italy’s grid carbon intensity so your environmental dashboards, emissions accounting, or energy optimization models can run on current data. By the end of this guide you will be able to call the Energy API for the Italy Carbon Intensity symbol, interpret the fields you receive, handle catalog unavailability cleanly, and ship a production-ready integration.

Scope and prerequisites

This is a first-request guide for the Environment category symbol “Italy Carbon Intensity” (code: CARBON_INT_IT). You will learn how to query the latest value with a GET request, authenticate with an api_key, parse the relevant fields, and build resilient error handling. The examples are minimal and copy-pasteable so you can verify behavior quickly before wiring into your application.

Illustration: API to Get the Italy Carbon Intensity Price
  • Symbol name: Italy Carbon Intensity
  • Symbol code: CARBON_INT_IT
  • Unit: gCO2/kWh
  • Authentication: api_key query parameter (use YOUR_API_KEY in examples)
  • API path: GET /api/v1/latest?symbols=
  • Environment-only content: all examples and discussion focus on environmental energy metrics

Endpoint and authentication

The latest values are available from the Energy API at this endpoint:

  • Method: GET
  • URL: https://energy-api.com/api/v1/latest
  • Query parameters:
    • symbols: one or more comma-separated symbol codes. For this guide: CARBON_INT_IT.
    • api_key: your account key as a query parameter. Use YOUR_API_KEY in testing snippets below.

Do not include unneeded parameters. If you later expand your requests to include other energy symbols such as TTF_GAS or EUA_CO2, do not pass base=USD in the same call; keep your request focused on the environmental dataset you need.

You can sign up for access on the Starter plan ($19.99/mo) with a 7-day trial / 50 calls allowance to evaluate your workflow. See the Register page for details.

Make your first request (cURL)

Use this cURL command to request the Italy Carbon Intensity symbol. It encodes the query parameters correctly and uses GET with -G.

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

Paste it into your terminal. If your account is active and the symbol is present in the current catalog, you will receive a JSON object including the envelope fields described below. If the symbol is not in the catalog at request time, you will receive a structured error (see “Troubleshooting” for the exact error payload).

Understanding the response structure

The API responds with a consistent envelope that includes success, base, and per-symbol maps for rates, dates, and currencies:

  • success: boolean, indicates whether the request returned data.
  • date: server date for the envelope (not per-symbol).
  • base: the base unit context for monetary series; for environmental intensity series, base may be MIXED.
  • rates: a map keyed by symbol code with the numeric value.
  • dates: a map keyed by symbol code with the observation date string.
  • currencies: a map keyed by symbol code. For CARBON_INT_IT, this captures the unit context; the value is not a tradable currency but remains present for consistency across the catalog.
  • base_filter_note and missing_symbols: may be null or populated if filtering or missing data occurred.

For environmental intensity series, remember:

  • Units: gCO2/kWh for CARBON_INT_IT.
  • Base: may be MIXED. Do not assume a monetary currency base for non-price environmental indicators.
  • Timestamps: use dates.CARBON_INT_IT to locate the observation date tied to the numeric rate.

Official sample of a successful envelope

The following is an official sample success envelope from the live service. It demonstrates how successful responses are structured, including envelope keys and per-symbol maps. This sample uses a different symbol to illustrate a passing response format; your parsing code should be identical for CARBON_INT_IT.

{
"success": true,
"date": "2026-11-09",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 179.6694
},
"dates": {
"OMIE_ES_DA": "2026-11-09"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null,
"missing_symbols": null
}

What to note for your CARBON_INT_IT integration:

  • Replace the symbol key with CARBON_INT_IT in your code when reading maps like rates, dates, and currencies.
  • The presence of base does not alter the unit of CARBON_INT_IT (still gCO2/kWh); it is part of a unified response shape across the Energy catalog where monetary series need a currency base.
  • Always check success before attempting to read rates.CARBON_INT_IT.

Python example: request, parse, and guard against errors

This Python snippet calls the same endpoint used in the cURL example, checks success, and safely reads the environmental intensity value plus its observation date. It also prints a clear diagnostic when the symbol is not in the current catalog.

import os
import sys
import urllib.parse
import urllib.request
import json

def fetch_latest_carbon_intensity_it(api_key):
base_url = "https://energy-api.com/api/v1/latest"
params = {
"symbols": "CARBON_INT_IT",
"api_key": api_key
}
url = base_url + "?" + urllib.parse.urlencode(params)
req = urllib.request.Request(url, method="GET")
try:
with urllib.request.urlopen(req, timeout=15) as resp:
raw = resp.read().decode("utf-8")
data = json.loads(raw)
except Exception as e:
print("HTTP error:", e, file=sys.stderr)
sys.exit(1)

if not isinstance(data, dict) or "success" not in data:
print("Malformed response envelope", file=sys.stderr)
sys.exit(1)

if not data.get("success", False):
# Consistent error envelope
print("API reported failure:", data.get("error", "unknown error"), file=sys.stderr)
# Exit non-zero in CI to catch catalog regressions early
sys.exit(2)

# Happy path: read the environmental intensity value and date
rates = data.get("rates", {})
dates = data.get("dates", {})
currencies = data.get("currencies", {})

if "CARBON_INT_IT" not in rates:
print("Symbol CARBON_INT_IT missing in rates map.", file=sys.stderr)
sys.exit(3)

value = rates["CARBON_INT_IT"]
obs_date = dates.get("CARBON_INT_IT")
unit = "gCO2/kWh" # Fixed for CARBON_INT_IT per catalog facts
base = data.get("base") # May be MIXED; not used for unit normalization here
symbol_currency_field = currencies.get("CARBON_INT_IT") # Present for shape consistency

print("Italy carbon intensity:", value, unit)
print("Observation date:", obs_date)
print("Envelope base:", base)
print("Symbol currency field:", symbol_currency_field)

if __name__ == "__main__":
api_key = os.environ.get("ENERGY_API_KEY", "YOUR_API_KEY")
fetch_latest_carbon_intensity_it(api_key)

Behavior to expect:

  • On success, value is in gCO2/kWh. Store it as a float with a unit tag, not a currency.
  • On failure, the script prints the exact error and exits non-zero, which is useful in CI to detect catalog unavailability early.

The exact error payload when the symbol is unavailable

If the live call does not succeed because the symbol is not in the current catalog, you will receive this error envelope. Use it to implement retries, fallbacks, or surface a precise message to operators.

{"success":false,"error":"Symbol CARBON_INT_IT is not currently available. See \/api\/v1\/symbols for the current catalog."}

Actionable steps when you receive this:

  • Log the error string and alert on prolonged unavailability if your SLA requires fresh intensity data.
  • Optionally query the catalog to confirm symbol presence before attempting the latest call in scheduled jobs.
  • Avoid substituting another country's intensity; keep your environmental metrics geographically correct.

Reading only the fields you need for Environment metrics

For environmental intensity, you typically only need three fields from the successful response:

  • rates.CARBON_INT_IT: numeric intensity in gCO2/kWh.
  • dates.CARBON_INT_IT: observation date string to time-align the value with your grid or load data.
  • currencies.CARBON_INT_IT: present for structural consistency; do not treat the value as a currency for intensity series.

Envelope-level base may be MIXED for cross-catalog consistency. Do not attempt to convert gCO2/kWh by using base; unit conversions for intensity (e.g., to kgCO2/MWh) are deterministic and should be performed in your application logic.

Operational guidance: caching, time alignment, and unit handling

To keep your environmental analytics reliable while minimizing calls:

  • Caching: cache the latest CARBON_INT_IT for an interval appropriate to your application (e.g., hourly) unless you require sub-hourly refresh. Invalidate on catalog updates if your pipeline tracks catalog metadata.
  • Time alignment: use dates.CARBON_INT_IT to align intensity with your energy consumption intervals. If your load data is hourly and the intensity is daily, note the granularity mismatch in your model.
  • Units: the canonical unit is gCO2/kWh. Convert to kgCO2/MWh by multiplying by 1 (since 1 g/kWh equals 1 kg/MWh), or to tCO2/MWh by dividing by 1000. Keep the original value stored with unit metadata.
  • Retries: if you hit the unavailability error, implement exponential backoff and surface a clear operational alert rather than silently substituting stale data.

Troubleshooting: known behaviors and defensive coding

When you are integrating environmental metrics into production pipelines, handle the following cases explicitly.

1) Symbol temporarily unavailable in the catalog

You will receive this exact envelope (quoted here again for quick reference):

{"success":false,"error":"Symbol CARBON_INT_IT is not currently available. See \/api\/v1\/symbols for the current catalog."}

Recommended handling:

  • Treat this as non-retryable for a short window and alert operators.
  • If you must present a value, label it as “stale” and include the date of the last successful observation in your UI or logs.

2) Successful envelope shape, different symbol in examples

In documentation or sandbox testing you may see a successful envelope for another energy symbol. The structure is the same you will parse for CARBON_INT_IT. Validate your parser against the sample below to ensure robust field handling:

{
"success": true,
"date": "2026-11-09",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 179.6694
},
"dates": {
"OMIE_ES_DA": "2026-11-09"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null,
"missing_symbols": null
}

Once your parsing is verified, switch the symbol parameter back to CARBON_INT_IT in both cURL and code.

3) Mixed base context

For environmental symbols like CARBON_INT_IT, base may be MIXED. This is expected and does not affect the unit of the intensity series. Do not attempt monetary conversions on intensity values.

Production checklists for Environment integrations

  • Input validation: enforce symbols=CARBON_INT_IT for your endpoint wrapper to prevent accidental inclusion of unrelated series.
  • Error logging: capture success, error, and missing_symbols for diagnostics.
  • Observability: record the returned dates.CARBON_INT_IT and an internal ingestion timestamp to audit freshness.
  • Backfills: if you store historical intensities, gate write operations on success to avoid inserting error envelopes.
  • Unit safety: tag stored values explicitly as gCO2/kWh. Perform downstream conversions in view/model layers, not at ingestion.

Quick reference: the cURL you will use in CI and cron

Use the same cURL command from above in your scheduled jobs and health checks. Exit non-zero if success is false to catch catalog regressions promptly:

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

FAQ

Q1: What unit will CARBON_INT_IT return?
A1: gCO2/kWh. Store it with the unit and convert explicitly if needed (e.g., to kgCO2/MWh).

Q2: Which fields should I read for environmental intensity?
A2: rates.CARBON_INT_IT for the numeric value, dates.CARBON_INT_IT for the observation date, and optionally currencies.CARBON_INT_IT for a consistent response shape.

Q3: How do I authenticate?
A3: Provide your api_key as a query parameter. The examples use YOUR_API_KEY as a placeholder. Avoid mixing unrelated parameters; keep requests minimal and symbol-focused.

Q4: What if the symbol is not currently available?
A4: You will receive this error payload and success will be false. Handle it by alerting and optionally retrying later: 

{"success":false,"error":"Symbol CARBON_INT_IT is not currently available. See \/api\/v1\/symbols for the current catalog."}

Q5: Does the base field affect environmental intensity?
A5: No. base may be MIXED in envelopes that contain non-price series. Do not treat base as a currency for CARBON_INT_IT.

Next step

Register for an API key and run the exact cURL and Python examples against your environment. Start with a simple health check around success and expand into your emissions pipeline once you confirm field parsing and unit handling. Get started here: Register. For endpoint details and catalog references, see the Documentation.

Keywords
API development Italy carbon intensity energy API carbon intensity price emissions data query

Ready to get started?

Get your API key and start querying energy commodity prices in minutes.

Get API Key