myeia 0.4.8
Python Wrapper for the U.S. Energy Information Administration (EIA) APIv2.
License: MIT
Keywords: eia, eia-api, open-data, python

# myeia
        
        [![PyPI version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=py&r=r&ts=1683906897&type=6e&v=0.4.8&x2=0)](https://badge.fury.io/py/myeia)
        [![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://github.com/philsv/myeia/blob/main/LICENSE)
        [![Weekly Downloads](https://static.pepy.tech/personalized-badge/myeia?period=week&units=international_system&left_color=grey&right_color=blue&left_text=downloads/week)](https://pepy.tech/project/myeia)
        [![Monthly Downloads](https://static.pepy.tech/personalized-badge/myeia?period=month&units=international_system&left_color=grey&right_color=blue&left_text=downloads/month)](https://pepy.tech/project/myeia)
        [![Downloads](https://static.pepy.tech/personalized-badge/myeia?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads)](https://pepy.tech/project/myeia)
        
        myeia is a simple Python wrapper for the U.S. Energy Information Administration (EIA) APIv2. It is designed to be simple to use and to provide a consistent interface for accessing EIA data.
        
        ## Installation
        
        ```ini
        pip install myeia
        ```
        
        ## Requirements
        
        - backoff
        - pandas
        - python-dateutil
        - python-dotenv
        - requests
        
        ## eia OPEN DATA Registration
        
        To obtain an API Key you need to register on the [EIA website](https://www.eia.gov/opendata/register.php).
        
        ## eia API Query Browser
        
        To find all EIA Datasets visit [API Dashboard](https://www.eia.gov/opendata/browser/).
        
        ## How to use
        
        ```python
        from myeia import API
        
        eia = API()
        ```
        
        ## Environment Variables
        
        ```bash
        # Create a .env file in your projects root directory
        touch .env
        ```
        
        By default the `API` class will look for your `EIA_TOKEN`.
        
        If you have registered for an API key you can set it in your `.env` file.
        
        ```ini
        EIA_TOKEN=YOUR_TOKEN_HERE
        ```
        
        ## Get Series
        
        Lets look at an example of how to get the _EIA Natural Gas Futures_.
        You can use the simpler v1 API method where you only need to pass the `series_id` or you can use the newer v2 API method where you need to pass the `route`, `series`, and `frequency`.
        
        ```python
        df = eia.get_series(series_id="NG.RNGC1.D")
        
        df = eia.get_series_via_route(
            route="natural-gas/pri/fut",
            series="RNGC1",
            frequency="daily",
        )
        
        df.head()
        ```
        
        Output Example:
        
        ```ini
                    Natural Gas Futures Contract 1 (Dollars per Million Btu)
        Date
        2022-09-13                                              8.284
        2022-09-12                                              8.249
        2022-09-09                                              7.996
        2022-09-08                                              7.915
        2022-09-07                                              7.842
        ...                                                       ...
        ```
        
        ## Different Facets
        
        Lets look at another example the _Total OPEC Petroleum Supply_ where the facet is available as `seriesId`. By Default it is set as `series` but we can define the facet as `seriesId`.
        
        ```python
        df = eia.get_series(series_id="STEO.PAPR_OPEC.M")
        
        df = eia.get_series_via_route(
            route="steo",
            series="PAPR_OPEC",
            frequency="monthly",
            facet="seriesId",
        )
        
        df.head()
        ```
        
        Output Example:
        
        ```ini
                    Total OPEC Petroleum Supply
        Date
        2023-12-01                    34.517314
        2023-11-01                    34.440397
        2023-10-01                    34.376971
        2023-09-01                    34.416242
        2023-08-01                    34.451823
        ...                                 ...
        ```
        
        ## Filter by multiple facets
        
        You can also filter by multiple facets. Lets look at the _UAE Crude oil, NGPL, and other liquids_ where the facets we choose are `countryRegionId` and `productId`.
        The difference here is that both facet columns are present in the dataframe, unlike the previous examples where only one facet was present.
        
        ```python
        df = eia.get_series_via_route(
            route="international",
            series=["ARE", 55],
            frequency="monthly",
            facet=["countryRegionId", "productId"],
        )
        
        df.head()
        ```
        
        Output Example:
        
        ```ini
                   countryRegionId productId  Crude oil, NGPL, and other liquids
        Date
        2024-03-01             ARE        55                         4132.394334
        2024-02-01             ARE        55                         4132.394334
        2024-01-01             ARE        55                         4142.394334
        2023-12-01             ARE        55                         4082.394334
        2023-11-01             ARE        55                         4082.394334
        ...                    ...       ...                                 ...
        ```
        
        ## Get Multiple Series
        
        For multiple series you have to loop through the series and append the data to a list.
        
        ```python
        data = []
        for item in ["RNGC1", "RNGC2"]:
            df = eia.get_series_via_route(
            route="natural-gas/pri/fut",
            series=item,
            frequency="daily",
            facet="series",
            )
            data.append(df)
        
        df = pd.concat(data, axis=1)
        df.head()
        ```
        
        Output Example:
        
        ```ini
                    Natural Gas Futures Contract 1 (Dollars per Million Btu)  Natural Gas Futures Contract 2 (Dollars per Million Btu)
        Date
        2023-08-29                                              2.556                                                     2.662
        2023-08-28                                              2.579                                                     2.665
        2023-08-25                                              2.540                                                     2.657
        2023-08-24                                              2.519                                                     2.636
        2023-08-23                                              2.497                                                     2.592
        ...                                                       ...                                                       ...
        ```
        
        ## Define a Start and End Date
        
        You can define a start and end date for your query.
        
        ```python
        df = eia.get_series(
            series_id="NG.RNGC1.D",
            start_date="2021-01-01",
            end_date="2021-01-31",
        )
        
        df.head()
        ```
        
        Output Example:
        
        ```ini
                    Natural Gas Futures Contract 1 (Dollars per Million Btu)
        Date
        2021-01-29                                              2.564
        2021-01-28                                              2.664
        2021-01-27                                              2.760
        2021-01-26                                              2.656
        2021-01-25                                              2.602
        ...                                                       ...
        ```
        
        This also works for the `get_series_via_route` method.
        
        ```python
        df = eia.get_series_via_route(
            route="natural-gas/pri/fut",
            series="RNGC1",
            frequency="daily",
            start_date="2021-01-01",
            end_date="2021-01-31",
        )
        
        df.head()
        ```
        
        Output Example:
        
        ```ini
                    Natural Gas Futures Contract 1 (Dollars per Million Btu)
        Date
        2021-01-29                                              2.564
        2021-01-28                                              2.664
        2021-01-27                                              2.760
        2021-01-26                                              2.656
        2021-01-25                                              2.602
        ...                                                       ...
        ```
        
        ## Contributing
        
        We love your input! We want to make contributing to this project as easy and transparent as possible.
        Read our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.