Esios

ESIOS Data Assistant

You have access to the python-esios CLI and library for querying the Spanish electricity market (ESIOS/REE).

CLI Reference

Indicators

# List all indicators
esios indicators list

# Search by name
esios indicators search "precio"

# Show metadata (unit, granularity, geographies)
esios indicators meta 600

# Historical data
esios indicators history 600 --start 2025-01-01 --end 2025-01-31
esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format csv --output data.csv
esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format parquet --output data.parquet

# Filter by geography (ID or name)
esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --geo España
esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --geo 3

# Ad-hoc pandas expressions on fetched data
esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --expr "df.describe()"
esios indicators exec 600 -s 2025-01-01 -e 2025-01-31 --expr "df.resample('D').mean()"

Archives

esios archives list
esios archives download 1 --start 2025-01-01 --end 2025-01-31 --output ./data

Cache Management

esios cache status    # Path, size, geos registry, catalog info
esios cache geos      # Global geo_id → geo_name registry
esios cache path      # Print cache directory
esios cache clear     # Clear indicator cache
esios cache clear --all  # Clear everything (indicators, archives, geos, catalog)
esios cache clear --indicator 600  # Clear one indicator

Configuration

esios config set token <API_KEY>
esios config show

Common Indicator IDs

Use esios indicators search "query" to find more. Use esios indicators meta <id> to see full metadata including geographies and units.

Multi-Geo Indicators

Some indicators (e.g. 600) return data for multiple countries. The output is pivoted so each geography becomes a column:

datetime                España  Portugal  Francia  Alemania  Bélgica  Países Bajos
2025-01-01 00:00:00     63.50    63.50     72.10    58.20     58.20     58.20
2025-01-01 01:00:00     55.80    55.80     60.30    48.90     48.90     48.90

Filter to specific geos with --geo:

esios indicators history 600 -s 2025-01-01 -e 2025-01-07 --geo España --geo Portugal

Geography Reference

The --geo flag accepts both IDs and names (case-insensitive substring match):

• --geo 3 or --geo España or --geo españa
• --geo "Países Bajos" or --geo 8828

Python Library

from esios import ESIOSClient

client = ESIOSClient()  # reads config file, then ESIOS_API_KEY env var

# Get indicator handle
handle = client.indicators.get(600)

# Historical data as DataFrame
df = handle.historical("2025-01-01", "2025-01-31")

# Filter by geo
df = handle.historical("2025-01-01", "2025-01-31", geo_ids=[3])  # España only

# Inspect geographies
handle.geos             # List of {"geo_id": int, "geo_name": str}
handle.geos_dataframe() # DataFrame with geo_id and geo_name columns
handle.resolve_geo("España")  # Returns 3

# Search and compare
results = client.indicators.search("precio")
df = client.indicators.compare([600, 10034, 10035], "2025-01-01", "2025-01-07")

I90 Settlement Files

from esios.processing import I90Book

book = I90Book("path/to/I90DIA_20250101.xls")
sheet = book["3.1"]       # Access specific sheet
df = sheet.df             # Preprocessed DataFrame with datetime index
print(sheet.frequency)    # "hourly" or "hourly-quarterly"

Caching Behavior

• Data is cached locally as parquet files (~/.cache/esios/)
• Each indicator gets its own directory: indicators/{id}/data.parquet
• Indicator metadata cached in indicators/{id}/meta.json (7-day TTL)
• Indicator catalog cached in indicators/catalog.json (24h TTL)
• Global geo registry at geos.json (persisted forever, grows incrementally)
• Data older than 48h is considered final (won't be re-fetched)
• Recent data (last 48h) is re-fetched on each request (electricity market corrections)
• Cache is per-column sparse: fetching --geo España only caches that column

Key Conventions

• All timestamps are in Europe/Madrid timezone
• Date ranges > 3 weeks are auto-chunked into smaller API requests
• Archives support skip-existing (won't re-download cached files)
• I90 sheets detect hourly vs quarter-hourly frequency automatically
• API token resolution: config file (~/.config/esios/config.toml) > ESIOS_API_KEY env var
• Custom exceptions: ESIOSError, AuthenticationError, APIResponseError, NetworkError