Skip to main content
This guide will help you make your first query to the ESIOS API using python-esios. We’ll fetch historical electricity price data and display it as a pandas DataFrame.
Before starting, make sure you’ve installed python-esios and configured your API token.

​
Your First Query

Let’s fetch PVPC electricity prices (indicator 600) for a specific date range: 
from esios import ESIOSClient

client = ESIOSClient()

# Get indicator data as DataFrame
handle = client.indicators.get(600)  # PVPC price
df = handle.historical("2025-01-01", "2025-01-31")

print(df.head())
This code:
  1. Creates an ESIOSClient instance (automatically uses your configured token)
  2. Gets a handle for indicator 600 (PVPC prices)
  3. Fetches historical data for January 2025
  4. Returns the data as a pandas DataFrame

​
Using the Context Manager

For better resource management, use the client as a context manager: 
from esios import ESIOSClient

with ESIOSClient() as client:
    df = client.indicators.get(600).historical("2025-01-01", "2025-01-07")
    print(df)
The context manager automatically closes the HTTP connection when done.

​
Common Operations

​
Search for Indicators

Find indicators by keyword: 
from esios import ESIOSClient

client = ESIOSClient()

# Search for price-related indicators
results = client.indicators.search("precio")

for indicator in results:
    print(f"{indicator['id']}: {indicator['name']}")

​
Download Archive Files

Download I90 settlement files: 
from esios import ESIOSClient

client = ESIOSClient()

# Download archive type 1 for a date range
client.archives.download(
    archive_id=1,
    start="2025-01-01",
    end="2025-01-31",
    output_dir="./data"
)

​
Export Data to CSV

Save indicator data to a CSV file: 
from esios import ESIOSClient

client = ESIOSClient()

df = client.indicators.get(600).historical("2025-01-01", "2025-01-31")
df.to_csv("prices.csv", index=False)

​
Using the CLI

python-esios includes a powerful command-line interface for quick queries:
1

Search for indicators

esios indicators search "precio"
2

Download historical data

esios indicators history 600 --start 2025-01-01 --end 2025-01-31
3

Export to CSV

esios indicators history 600 -s 2025-01-01 -e 2025-01-31 --format csv --output prices.csv

​
List Available Archives

esios archives list

​
Download Archive Files

esios archives download 1 --start 2025-01-01 --end 2025-01-31

​
Check Cache Status

esios cache status

​
Client Configuration

Customize the client behavior with additional parameters: 
from esios import ESIOSClient

client = ESIOSClient(
    token="YOUR_TOKEN",          # Optional if using env var or config file
    timeout=30.0,                 # Request timeout in seconds (default: 30)
    cache=True,                   # Enable caching (default: True)
    cache_dir="./my_cache",       # Custom cache directory
    cache_recent_ttl=48           # TTL for recent data in hours (default: 48)
)
The client automatically caches historical data to reduce API calls. Recent data (within cache_recent_ttl hours) is refreshed on each request, while older data is cached indefinitely.

​
Async Support

For async applications, use AsyncESIOSClient: 
import asyncio
from esios import AsyncESIOSClient

async def fetch_data():
    async with AsyncESIOSClient() as client:
        df = await client.indicators.get(600).historical("2025-01-01", "2025-01-07")
        print(df)

asyncio.run(fetch_data())

​
Error Handling

Handle common exceptions: 
from esios import ESIOSClient
from esios import (
    ESIOSError,
    AuthenticationError,
    APIResponseError,
    NetworkError
)

try:
    client = ESIOSClient()
    df = client.indicators.get(600).historical("2025-01-01", "2025-01-31")
except AuthenticationError:
    print("Invalid API token. Check your configuration.")
except APIResponseError as e:
    print(f"API returned an error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")
except ESIOSError as e:
    print(f"General error: {e}")

​
Next Steps

Now that you’ve made your first query, explore more features:

Indicators API

Learn about querying electricity market indicators

Archives API

Download settlement files and market archives

Caching

Understand how caching works and how to configure it

API Reference

Browse the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us