Tutorial

Give Claude Code access to U.S. energy data

Install the python-eia CLI and drop a skill file so Claude Code can explore, fetch, and analyze EIA data from the terminal.

If you work with U.S. energy data — electricity generation, petroleum prices, natural gas supply — you’ve probably written scripts to pull data from the EIA API. What if your AI coding assistant could do that directly from the terminal?

python-eia ships with a CLI and a Claude Code skill file — a markdown document that teaches Claude how to use the CLI. Drop it into your project, and Claude can explore the EIA API tree, fetch data with facet filters, run pandas expressions, and export results without you writing a single line of code.

What’s a Claude Code skill?

A skill is a markdown file that Claude Code reads automatically when it’s relevant to your question. It contains instructions, command references, and conventions — everything Claude needs to use a tool correctly.

The python-eia skill teaches Claude:

The full CLI command reference (eia routes, meta, facets, get, exec)
Common EIA routes (electricity generation, petroleum prices, natural gas)
Facet conventions (key=value filtering)
Output formats (table, CSV, JSON)
The Python library API for more complex workflows

Setup

1. Install the library

pip install python-eia

2. Set your API key

Option A — persistent config (recommended):

eia config set api-key your-key-here

This stores the key in ~/.config/eia/config.toml so you don’t need to export it every session.

Option B — environment variable:

export EIA_API_KEY=your-key-here

3. Add the skill to your project

Copy the skill file into your project’s .claude/skills/ directory:

mkdir -p .claude/skills/eia
curl -o .claude/skills/eia/SKILL.md \
  https://raw.githubusercontent.com/datons/python-eia/main/skills/eia/SKILL.md

That’s it. Next time you open Claude Code in this project, it will automatically discover the skill.

What Claude can do now

Explore the API tree

The EIA API is organized as a tree of routes. Claude can navigate it to find the right data endpoint:

You: “What electricity data is available in the EIA API?”

Claude runs:

eia routes electricity

Inspect a data endpoint

You: “What facets and frequencies does the fuel-type generation endpoint have?”

eia meta electricity/rto/fuel-type-data

Fetch data

You: “Download CAISO’s hourly generation by fuel type for the first week of June 2024”

eia get electricity/rto/fuel-type-data \
  --start 2024-06-01 --end 2024-06-08 \
  --frequency hourly \
  --facet respondent=CISO \
  --data value

Run pandas expressions

This is the power move. The exec command fetches data and evaluates any pandas expression — no script needed:

You: “What’s the average generation by fuel type for CAISO last June?”

eia exec electricity/rto/fuel-type-data \
  --start 2024-06-01 --end 2024-06-30 \
  --frequency hourly \
  --facet respondent=CISO --data value \
  -x "df.groupby('fueltype')['value'].mean().sort_values(ascending=False).round(0)"

You: “Export it to CSV”

eia get electricity/rto/fuel-type-data \
  --start 2024-06-01 --end 2024-06-30 \
  --frequency hourly \
  --facet respondent=CISO --data value \
  --format csv --output generation.csv

Real workflow: analyzing petroleum prices

Here’s what a real conversation looks like. You ask one question, Claude handles the rest:

You: “Compare WTI crude oil spot prices across the first half of 2024. Show me monthly averages and the month-over-month change.”

Claude:

Discovers the endpoint:

eia meta petroleum/pri/spt
eia facets petroleum/pri/spt series

Fetches and analyzes:

eia exec petroleum/pri/spt \
  --start 2024-01-01 --end 2024-06-30 \
  --facet series=RWTC --data value \
  -x "df.set_index('period').resample('M')['value'].mean().round(2)"

Summarizes the findings with real numbers from the data.

No script. No notebook. Just a question and an answer backed by real data.

The route-based approach

Unlike other energy APIs with fixed indicator catalogs, the EIA API is a tree of routes. Each route can have child routes or be a data endpoint with its own set of facets and frequencies.

The CLI mirrors this structure:

eia routes — navigate the tree
eia meta — inspect a data endpoint
eia facets — list values for a specific facet
eia get — fetch data with filters
eia exec — fetch + pandas expression

This generic approach means any new route added to the EIA API works automatically — no library update needed.

Tips for writing good prompts

Name the route if you know it: “electricity/rto/fuel-type-data” saves exploration steps
Specify dates explicitly: “June 2024” is better than “last month”
Ask for exports: Claude will use --format csv --output automatically
Chain analysis: “fetch generation data, group by fuel type, compute daily averages” — Claude will use exec

Conclusions

With the python-eia skill, Claude Code becomes a U.S. energy data analyst:

eia routes — navigate the entire EIA API tree
eia meta — inspect endpoints, facets, frequencies
eia facets — discover available filter values
eia get — fetch data with facet filters
eia exec — run pandas expressions without writing scripts

The skill file is the bridge: it gives Claude the knowledge to use these commands correctly, with the right routes, facets, and conventions.

Resources

GitHub: datons/python-eia
PyPI: python-eia
python-eia library tutorial — Python API overview
EIA API documentation
Claude Code skills documentation