Eia
========================

.. py:module:: gridstatus.eia


Module Contents
---------------

Classes Summary
~~~~~~~~~~~~~~~

.. autoapisummary::

   gridstatus.eia.EIA





Attributes Summary
~~~~~~~~~~~~~~~~~~~

.. autoapisummary::

   gridstatus.eia.DATASET_HANDLERS


Contents
~~~~~~~~~~~~~~~~~~~
.. py:data:: DATASET_HANDLERS

   

.. py:class:: EIA(api_key=None)

   
   Initialize EIA API object

   :param api_key: EIA API key.
                   If not provided, will look for EIA_API_KEY environment variable.
   :type api_key: str, optional


   **Attributes**

   .. list-table::
      :widths: 15 85
      :header-rows: 0

      * - **BASE_URL**
        - https://api.eia.gov/v2/


   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.eia.EIA.get_coal_spots
      gridstatus.eia.EIA.get_daily_spots_and_futures
      gridstatus.eia.EIA.get_dataset
      gridstatus.eia.EIA.get_grid_monitor
      gridstatus.eia.EIA.list_routes

   .. py:method:: get_coal_spots(verbose=False)

      Retrieve weekly coal commodity spot prices.
      TODO: add functionality to grab historicals from
      https://www.eia.gov/coal/markets/coal_markets_archive_json.php


   .. py:method:: get_daily_spots_and_futures(verbose=False)

      Retrieves daily spots and futures for select energy products.

      Includes Wholesale Spot and Retail Petroleum, Natural Gas.
      Prompt-Month Futures, broken on EIA side,
      for Crude, Gasoline, Heating Oil, Natural Gas, Coal, Ethanol.

      They are published daily and not persisted, so this should be run once daily.

      :returns: dictionary of DataFrames for each table of values.
      :rtype: d


   .. py:method:: get_dataset(dataset, start, end, n_workers=1, verbose=False)

      Get data from a dataset

      Only supports "electricity/rto/interchange-data" dataset for now.

      :param dataset: Dataset path
      :type dataset: str
      :param start: Start date
      :type start: str or pd.Timestamp
      :param end: End date
      :type end: str or pd.Timestamp
      :param n_workers: Number of
                        workers to use for fetching data. Defaults to 1.
      :type n_workers: int, optional
      :param verbose: Whether
                      to print progress. Defaults to False.
      :type verbose: bool, optional

      :returns: Dataframe with data from the dataset
      :rtype: pd.DataFrame


   .. py:method:: get_grid_monitor(area_id=None, area_type=None, n_workers=4, verbose=False)

      Retrieves grid monitor data including generation and emissions.

      This function cannot filter by time and fetches all available data. It may
      be slow if fetching data for all areas.

      :param area_id: ID of area to fetch data for. If provided,
                      fetches data for this area only, ignoring area_type. If both are
                      not provided, fetches data for all areas. Defaults to None.
      :type area_id: str, optional
      :param area_type: Type of areas ('Region' or 'BA') to fetch
                        data for. Used only if area_id is not provided. If provided,
                        fetches data for all areas of given type. If both are not
                        provided, fetches data for all areas. Defaults to None.
      :type area_type: str, optional
      :param n_workers: Number of workers to use for fetching data. Only
                        used if multiple areas are being fetched. Defaults to 4.
      :type n_workers: int, optional
      :param verbose: If True, prints progress. Defaults to False.
      :type verbose: bool, optional

      :returns: Grid monitor data for specified area(s).
      :rtype: dict


   .. py:method:: list_routes(route='/')

      List all available routes