openapi: 3.0.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:
  schemas:
    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
    Routes:
      properties:
        routes:
          type: array
          items:
            type: string
        id:
          type: string
        name:
          type: string
        description:
          type: string
      type: object
    DataResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/DataResponse'
      type: object
    Facet:
      properties:
        id:
          type: string
        name:
          type: string
        alias:
          type: string
      type: object
    FacetMetaData:
      properties:
        id:
          type: string
        description:
          type: string
      type: object
    Frequency:
      properties:
        id:
          type: string
        description:
          type: string
        format:
          type: string
        query:
          type: string
      type: object
    DataResponse:
      properties:
        data: {}
        dateFormat:
          type: string
        description:
          type: string
        frequency:
          type: string
        total:
          type: integer
      type: object
    FinalRouteResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/FinalRouteResponse'
      type: object
    FacetOptionListContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/FacetOptionList'
      type: object
    Sort:
      properties:
        column:
          type: string
        direction:
          type: string
      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
    FinalRouteResponse:
      properties:
        response:
          $ref: '#/components/schemas/FinalRoute'
        request:
          $ref: '#/components/schemas/RouteRequest'
      type: object
    FacetOptionList:
      properties:
        totalFacetOptions:
          type: integer
        facetOptions:
          type: array
          items:
            type: string
      type: object
    RouteResponseContainer:
      properties:
        apiVersion:
          type: string
        request:
          $ref: '#/components/schemas/RouteRequest'
        response:
          $ref: '#/components/schemas/RouteResponse'
      type: object
    RouteResponse:
      properties:
        response:
          $ref: '#/components/schemas/Routes'
        request:
          $ref: '#/components/schemas/RouteRequest'
      type: object
    RouteRequest:
      properties:
        command:
          type: array
          items:
            type: string
        params: {}
      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
  responses:
    final-route:
      description: List of API data sets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FinalRouteResponseContainer'
    data:
      description: API Data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataResponseContainer'
    facets:
      description: List of facet options
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FacetOptionListContainer'
    facet:
      description: Facet details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FacetDetailsContainer'
    route:
      description: List of API data sets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RouteResponseContainer'
  parameters:
    end:
      name: end
      in: query
      description: End date to filter by
      required: false
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: Offset of returned data
      required: false
      schema:
        type: integer
    route1:
      name: route1
      in: path
      description: First level Sub route
      required: true
      schema:
        type: string
    length:
      name: length
      in: query
      description: Max length of returned data
      required: false
      schema:
        type: integer
    start:
      name: start
      in: query
      description: Start date to filter by
      required: false
      schema:
        type: string
    facets:
      name: facets
      in: query
      description: Facets to filter by
      required: false
      schema:
        type: object
    data:
      name: data
      in: query
      description: Data columns to filter by
      required: false
      schema:
        type: array
        items:
          type: string
    facetId:
      name: facet_id
      in: path
      description: Facet ID
      required: true
      schema:
        type: string
    sort:
      name: sort
      in: query
      description: How to sort returned data
      required: false
      schema:
        $ref: '#/components/schemas/Sort'
    frequency:
      name: frequency
      in: query
      description: Frequency to filter by
      required: false
      schema:
        type: string
  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