Support

Public data API

Use the same public JSON endpoints that supply the site’s data. No API key or signup is required.

Start here

Start by checking the survey dates and latest data updates:

curl https://gridlines.energy/api/v1/meta

Get a state’s generation mix, operating generators, and announced projects:

curl https://gridlines.energy/api/v1/mix/IA
curl https://gridlines.energy/api/v1/fleet/IA
curl https://gridlines.energy/api/v1/projects/IA

The endpoints

/api/v1/mix
Current generation mix for every state and the national total.
/api/v1/mix/:state
A state's generation mix, fuel breakdown, and 13-month trend.
/api/v1/projects/:state?year=
Announced generators and retirements on that state's drawing board.
/api/v1/fleet/:state
Operating generators, largest first, with capacity in MW.
/api/v1/board
Announced capacity by project stage for every state and D.C.
/api/v1/board/projects/:fuel
All announced generators for one fuel across the country.
/api/v1/projections/:state
Projected generation through 2031, with the projects contributing to each year.
/api/v1/history/:entity?from=
Monthly generation since 2014, by state or for the country.
/api/v1/news
The clippings feed. Filter by fuel, state, topic, source or lens; cursor-paginated.
/api/v1/meta
Survey periods, latest data updates, and source status.
/api/v1/markets/spreads
Monthly spark spreads and breakeven gas prices for seven power hubs, against the U.S. delivered gas-cost benchmark.
GET /api/v1/feature-requests
Reviewed suggestions from the Feature Board — planned, shipped and not planned.
POST /api/v1/feature-requests
Suggest a feature. Held for review before it appears; rate-limited.

What to expect

  • Endpoints are versioned under /api/v1/. New fields may be added. Renaming or removing fields requires a new API version.
  • Check the response metadata for dates and units. For generation data, read meta.latestPeriod. Surveys typically lag by one to two months. An empty date means the survey period is unavailable.
  • Generation is reported in GWh; capacity is reported in MW. Fleet and board endpoints report capacity. Check meta.units before using the figures.
  • Responses are cached for one hour, or five minutes for news. Feature requests are not cached. Public endpoints support requests from other websites, so you can call them directly from a browser.
  • A 503 response means the data service is unavailable. The response includes an error message. Public endpoints require no authentication, and all but the feature-request submission are read-only.

The full API reference, including fields, types, and guarantees, is in docs/CONTRACTS.md in the repository. About the data explains the sources, calculations, and limitations.

Using it

You can use the data freely. The energy figures come from public federal surveys, EIA-923 and EIA-860M. Gridlines Energy adds the compilation, projections, and labels. A link back is appreciated but optional.

When publishing figures, include the survey date and label projections clearly. Projections use announced projects and completion assumptions described in the methodology.

For scheduled requests, follow the cache headers. Energy surveys are imported weekly, and news updates more often.

← Back to the Atlas · About the data →