Energy Information Administration Electricity API

openapi: 3.2.0
info:
  title: U.S. Energy Information Administration Open Data CO2 Emissions Electricity API
  description: The U.S. Energy Information Administration (EIA) Open Data API v2 provides free programmatic access to EIA's open energy data, including time-series datasets organized by energy category. The API uses a hierarchical route structure where each route corresponds to a category or dataset, and metadata about child routes, available facets, frequencies, and data columns is returned by querying any parent route. An API key, obtained via free registration at https://www.eia.gov/opendata/register.php, is required on every request and must be supplied as a URL query parameter.
  version: '2.1'
  contact:
    name: EIA Open Data
    url: https://www.eia.gov/opendata/
    email: EIA-OpenData@eia.gov
  license:
    name: EIA Copyrights and Reuse Policy
    url: https://www.eia.gov/about/copyrights_reuse.php
servers:
- url: https://api.eia.gov/v2
  description: EIA Open Data API v2 production server
security:
- apiKeyQuery: []
tags:
- name: Electricity
  description: Electricity generation, retail sales, and balancing authority data.
paths:
  /electricity:
    get:
      operationId: getElectricityRoutes
      summary: List electricity child routes
      description: Returns the available child routes under the electricity category, such as retail sales, generation, and balancing authority data.
      tags:
      - Electricity
      responses:
        '200':
          description: Electricity routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /electricity/retail-sales/data:
    get:
      operationId: getElectricityRetailSales
      summary: Query electricity retail sales time series
      description: Returns electricity retail sales time-series data filtered by state, sector, frequency, and date range.
      tags:
      - Electricity
      parameters:
      - $ref: '#/components/parameters/Frequency'
      - $ref: '#/components/parameters/DataArray'
      - $ref: '#/components/parameters/Start'
      - $ref: '#/components/parameters/End'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Length'
      - $ref: '#/components/parameters/Out'
      responses:
        '200':
          description: Time-series response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
components:
  schemas:
    SeriesResponse:
      type: object
      description: Time-series data response.
      properties:
        response:
          type: object
          properties:
            total:
              type: integer
              description: Total rows available for the query.
            dateFormat:
              type: string
            frequency:
              type: string
            data:
              type: array
              items:
                type: object
                additionalProperties: true
        request:
          type: object
        apiVersion:
          type: string
    RouteMetadata:
      type: object
      description: Metadata about a route, including its child routes, facets, and frequencies.
      properties:
        response:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            description:
              type: string
            routes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  description:
                    type: string
            frequency:
              type: array
              items:
                type: object
            facets:
              type: array
              items:
                type: object
            data:
              type: object
        request:
          type: object
        apiVersion:
          type: string
  parameters:
    Offset:
      name: offset
      in: query
      description: Pagination offset (zero-based row index).
      required: false
      schema:
        type: integer
        minimum: 0
    Start:
      name: start
      in: query
      description: Inclusive start of the date range (format depends on frequency, e.g. YYYY-MM-DD).
      required: false
      schema:
        type: string
    Length:
      name: length
      in: query
      description: Maximum number of rows to return (5,000 max for JSON, 300 max for XML).
      required: false
      schema:
        type: integer
        maximum: 5000
    DataArray:
      name: data[]
      in: query
      description: Columns to include in the response (repeat for multiple columns).
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
    Out:
      name: out
      in: query
      description: Output format.
      required: false
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
    End:
      name: end
      in: query
      description: Inclusive end of the date range (format depends on frequency, e.g. YYYY-MM-DD).
      required: false
      schema:
        type: string
    Frequency:
      name: frequency
      in: query
      description: Periodicity of returned data (annual, monthly, quarterly, daily).
      required: false
      schema:
        type: string
        enum:
        - annual
        - quarterly
        - monthly
        - weekly
        - daily
        - hourly
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Free API key obtained at https://www.eia.gov/opendata/register.php. Must be supplied on every request as the api_key URL parameter.