EIA

EIA AEO API

Access to Annual Energy Outlook Data

GitHub OpenAPI

Operations 6

GET /v2/aeo/{route1}
GET /v2/aeo/{route1}/facet
GET /v2/aeo/{route1}/facet/{facet_id}
GET /v2/aeo/{route1}/data
POST /v2/aeo/{route1}/data Return AEO Data
GET /v2/aeo

Documentation

📖
Documentation
https://www.eia.gov/opendata/documentation.php
📖
APIReference
https://www.eia.gov/opendata/browser/
📖
Authentication
https://www.eia.gov/opendata/register.php
📖
Documentation
https://www.eia.gov/opendata/qb.php
📖
GettingStarted
https://www.eia.gov/opendata/documentation.php
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/eia/refs/heads/main/rate-limits/eia-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/eia/refs/heads/main/openapi/eia-aeo-api-openapi.yml

Other Resources

🔗
Portal
https://www.eia.gov/opendata/
🔗
SignUp
https://www.eia.gov/opendata/register.php
🔗
TermsOfService
https://www.eia.gov/opendata/register.php
🔗
Console
https://www.eia.gov/opendata/browser/
🔗
PrivacyPolicy
https://www.eia.gov/about/privacy_security_policy.php
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/eia/refs/heads/main/examples/eia-api-v2-examples.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/eia/refs/heads/main/data-model/eia-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/eia-aeo-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

eia-aeo-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: EIA APIv2 AEO API
  description: Swagger UI interface for EIA's APIv2.  You can also explore EIA's API using the [Opendata Query Browser](https://www.eia.gov/opendata/browser/).  For this UI, you must use your EIA `api key` to apply filters and return data. You can register for an API Key at [https://www.eia.gov/opendata/](https://www.eia.gov/opendata/)
  version: 2.1.0
servers:
- url: https://api.eia.gov
security:
- api_key: []
tags:
- name: AEO
  description: Access to Annual Energy Outlook Data
paths:
  /v2/aeo/{route1}:
    parameters:
    - $ref: '#/components/parameters/route1'
    get:
      tags:
      - AEO
      parameters:
      - name: route1
        in: path
        description: Available AEO year data route
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/final-route'
  /v2/aeo/{route1}/facet:
    parameters:
    - $ref: '#/components/parameters/route1'
    get:
      tags:
      - AEO
      responses:
        '400':
          description: Invalid input
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/facets'
  /v2/aeo/{route1}/facet/{facet_id}:
    parameters:
    - $ref: '#/components/parameters/route1'
    - $ref: '#/components/parameters/facetId'
    get:
      tags:
      - AEO
      responses:
        '400':
          description: Invalid input
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/facet'
  /v2/aeo/{route1}/data:
    parameters:
    - $ref: '#/components/parameters/route1'
    get:
      tags:
      - AEO
      description: API data with query params
      parameters:
      - $ref: '#/components/parameters/data'
      - $ref: '#/components/parameters/facets'
      - $ref: '#/components/parameters/frequency'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/length'
      - $ref: '#/components/parameters/offset'
      responses:
        '400':
          description: Invalid input
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/data'
    post:
      tags:
      - AEO
      summary: Return AEO Data
      requestBody:
        $ref: '#/components/requestBodies/dataParams'
      responses:
        '400':
          description: Invalid input
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/data'
  /v2/aeo:
    get:
      tags:
      - AEO
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/route'
components:
  responses:
    route:
      description: List of API data sets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RouteResponseContainer'
    facets:
      description: List of facet options
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FacetOptionListContainer'
    final-route:
      description: List of API data sets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FinalRouteResponseContainer'
    facet:
      description: Facet details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FacetDetailsContainer'
    data:
      description: API Data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataResponseContainer'
  schemas:
    DataResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/DataResponse'
      type: object
    FacetDetails:
      properties:
        totalFacets:
          type: integer
        facets:
          type: array
          items:
            $ref: '#/components/schemas/Facet'
      type: object
    FacetDetailsContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/FacetDetails'
      type: object
    Frequency:
      properties:
        id:
          type: string
        description:
          type: string
        format:
          type: string
        query:
          type: string
      type: object
    RouteResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/RouteResponse'
      type: object
    DataParams:
      properties:
        data:
          type: array
          items:
            type: string
        facets:
          type: object
        frequency:
          type: string
        start:
          type: string
        end:
          type: string
        sort:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
        length:
          type: integer
        offset:
          type: integer
      type: object
    FacetOptionListContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/FacetOptionList'
      type: object
    FinalRoute:
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        frequency:
          type: array
          items:
            $ref: '#/components/schemas/Frequency'
        facets:
          type: array
          items:
            $ref: '#/components/schemas/FacetMetaData'
        data: {}
        startPeriod:
          type: string
        endPeriod:
          type: string
        defaultDateFormat:
          type: string
        defaultFrequency:
          type: string
      type: object
    DataResponse:
      properties:
        data: {}
        dateFormat:
          type: string
        description:
          type: string
        frequency:
          type: string
        total:
          type: integer
      type: object
    Sort:
      properties:
        column:
          type: string
        direction:
          type: string
      type: object
    FacetMetaData:
      properties:
        id:
          type: string
        description:
          type: string
      type: object
    RouteResponse:
      properties:
        response:
          $ref: '#/components/schemas/Routes'
        request:
          $ref: '#/components/schemas/RouteRequest'
      type: object
    Routes:
      properties:
        routes:
          type: array
          items:
            type: string
        id:
          type: string
        name:
          type: string
        description:
          type: string
      type: object
    FinalRouteResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/FinalRouteResponse'
      type: object
    FacetOptionList:
      properties:
        totalFacetOptions:
          type: integer
        facetOptions:
          type: array
          items:
            type: string
      type: object
    Facet:
      properties:
        id:
          type: string
        name:
          type: string
        alias:
          type: string
      type: object
    RouteRequest:
      properties:
        command:
          type: array
          items:
            type: string
        params: {}
      type: object
    FinalRouteResponse:
      properties:
        response:
          $ref: '#/components/schemas/FinalRoute'
        request:
          $ref: '#/components/schemas/RouteRequest'
      type: object
  parameters:
    end:
      name: end
      in: query
      description: End date to filter by
      required: false
      schema:
        type: string
    facets:
      name: facets
      in: query
      description: Facets to filter by
      required: false
      schema:
        type: object
    length:
      name: length
      in: query
      description: Max length of returned data
      required: false
      schema:
        type: integer
    facetId:
      name: facet_id
      in: path
      description: Facet ID
      required: true
      schema:
        type: string
    data:
      name: data
      in: query
      description: Data columns to filter by
      required: false
      schema:
        type: array
        items:
          type: string
    offset:
      name: offset
      in: query
      description: Offset of returned data
      required: false
      schema:
        type: integer
    start:
      name: start
      in: query
      description: Start date to filter by
      required: false
      schema:
        type: string
    frequency:
      name: frequency
      in: query
      description: Frequency to filter by
      required: false
      schema:
        type: string
    route1:
      name: route1
      in: path
      description: First level Sub route
      required: true
      schema:
        type: string
    sort:
      name: sort
      in: query
      description: How to sort returned data
      required: false
      schema:
        $ref: '#/components/schemas/Sort'
  requestBodies:
    dataParams:
      description: Parameters for data call
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataParams'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query
externalDocs:
  description: EIA's API Technical Documentation
  url: https://www.eia.gov/opendata/documentation.php