openapi: 3.1.0
info:
  title: U.S. Energy Information Administration Open Data CO2 Emissions Discovery 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: Discovery
  description: Browse the API tree to discover available routes, facets, and metadata.
paths:
  /:
    get:
      operationId: getRoot
      summary: List top-level data categories
      description: Returns metadata for the top-level routes available in the API, including descriptions and child route identifiers.
      tags:
      - Discovery
      responses:
        '200':
          description: Root metadata response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /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:
      - Discovery
      responses:
        '200':
          description: Electricity routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /natural-gas:
    get:
      operationId: getNaturalGasRoutes
      summary: List natural gas child routes
      description: Returns child routes for natural gas datasets.
      tags:
      - Discovery
      responses:
        '200':
          description: Natural gas routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /petroleum:
    get:
      operationId: getPetroleumRoutes
      summary: List petroleum child routes
      description: Returns child routes for petroleum datasets.
      tags:
      - Discovery
      responses:
        '200':
          description: Petroleum routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /coal:
    get:
      operationId: getCoalRoutes
      summary: List coal child routes
      description: Returns child routes for coal datasets.
      tags:
      - Discovery
      responses:
        '200':
          description: Coal routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /nuclear-outages:
    get:
      operationId: getNuclearOutagesRoutes
      summary: List nuclear outage child routes
      description: Returns child routes for nuclear plant generator outages.
      tags:
      - Discovery
      responses:
        '200':
          description: Nuclear outages routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
  /international:
    get:
      operationId: getInternationalRoutes
      summary: List international child routes
      description: Returns child routes for international energy statistics.
      tags:
      - Discovery
      responses:
        '200':
          description: International routes metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteMetadata'
components:
  schemas:
    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
  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.