---
name: ember-data-api-ingestion
description: "How to get Ember Data API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load Ember yearly generation into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/ember-data-api
Provider: https://api.ember-energy.org/v1/docs
Checked against the provider's documentation: 2026-11-01

## Access
- Request a free API key from Ember's API signup page.
- Set the key in the EMBER_API_KEY environment variable; do not place it in source code.

## Request
```bash
curl 'https://api.ember-energy.org/v1/electricity-generation/yearly?entity_code=BRA&is_aggregate_series=false&start_date=2000&api_key=YOUR_API_KEY'
```

## Format
JSON response with generation observations and metadata for geography, fuel or aggregate series, year, unit and value, plus query statistics.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""Brazil yearly Ember electricity generation -> pandas -> Parquet."""
import os
import requests
import pandas as pd

URL = "https://api.ember-energy.org/v1/electricity-generation/yearly"
params = {
    "entity_code": "BRA",
    "is_aggregate_series": "false",
    "start_date": 2000,
    "api_key": os.environ["EMBER_API_KEY"],
}
response = requests.get(URL, params=params, timeout=60)
response.raise_for_status()
payload = response.json()
data = payload.get("data", payload)
df = pd.json_normalize(data)
df.to_parquet("ember_brazil_yearly_generation.parquet", index=False)
print(len(df), "generation observations")
```
Not run: it needs a free API key.

## Limits
- Rate limit: No rate limiting restrictions at present.
- Every dataset query requires an API key.
- Endpoint periods and geography coverage vary; use the options endpoints to inspect available values and dates.

## Quirks
- The api_key is a query parameter, so avoid logging complete request URLs.
- Yearly and monthly endpoints expose similar parameter names, but the underlying series and available ranges differ.
- Recent annual values can be derived from shorter-lag monthly data and later revised.

## Terms and attribution
- API data is CC BY 4.0 and Ember must be cited as the source.
- The licence permits personal and commercial use and prohibits adding further legal or technical restrictions.
- Terms page: https://api.ember-energy.org/v1/openapi.json

## Sources
- https://api.ember-energy.org/v1/openapi.json: "Query parameters with the exception of the api_key are optional."
- https://api.ember-energy.org/v1/openapi.json: "At present, there are no rate limiting restrictions for the API."
- https://api.ember-energy.org/v1/openapi.json: "Our data is published using the CC-BY-4.0 license."
- https://ember-energy.org/data/monthly-electricity-data/: "The latest monthly data on electricity generation, emissions, and demand from Ember for 88 geographical areas."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.