{"id":23293201,"url":"https://github.com/philsv/myeia","last_synced_at":"2025-08-22T00:33:04.716Z","repository":{"id":57444355,"uuid":"465421240","full_name":"philsv/myeia","owner":"philsv","description":"Python wrapper for the U.S. Energy Information Administration (EIA) API v2","archived":false,"fork":false,"pushed_at":"2024-10-21T00:35:42.000Z","size":394,"stargazers_count":14,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-21T11:18:35.650Z","etag":null,"topics":["eia","eia-api","energy","python","statistics"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/myeia/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philsv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-02T18:19:24.000Z","updated_at":"2024-10-21T00:32:11.000Z","dependencies_parsed_at":"2023-11-07T20:49:24.184Z","dependency_job_id":"d797f14f-bcfa-4a55-b39c-ab45a1122e1e","html_url":"https://github.com/philsv/myeia","commit_stats":{"total_commits":98,"total_committers":2,"mean_commits":49.0,"dds":"0.33673469387755106","last_synced_commit":"47b279ab42db848682b81c1d5e6f6ed93078fdef"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philsv%2Fmyeia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philsv%2Fmyeia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philsv%2Fmyeia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philsv%2Fmyeia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philsv","download_url":"https://codeload.github.com/philsv/myeia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230542272,"owners_count":18242333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eia","eia-api","energy","python","statistics"],"created_at":"2024-12-20T06:14:00.244Z","updated_at":"2025-08-22T00:33:04.703Z","avatar_url":"https://github.com/philsv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# myeia\n\n[![PyPI version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=py\u0026r=r\u0026ts=1683906897\u0026type=6e\u0026v=0.4.8\u0026x2=0)](https://badge.fury.io/py/myeia)\n[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://github.com/philsv/myeia/blob/main/LICENSE)\n[![Weekly Downloads](https://static.pepy.tech/personalized-badge/myeia?period=week\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads/week)](https://pepy.tech/project/myeia)\n[![Monthly Downloads](https://static.pepy.tech/personalized-badge/myeia?period=month\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads/month)](https://pepy.tech/project/myeia)\n[![Downloads](https://static.pepy.tech/personalized-badge/myeia?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads)](https://pepy.tech/project/myeia)\n\nmyeia 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.\n\n## Installation\n\n```ini\npip install myeia\n```\n\n## Requirements\n\n- backoff\n- pandas\n- python-dateutil\n- python-dotenv\n- requests\n\n## eia OPEN DATA Registration\n\nTo obtain an API Key you need to register on the [EIA website](https://www.eia.gov/opendata/register.php).\n\n## eia API Query Browser\n\nTo find all EIA Datasets visit [API Dashboard](https://www.eia.gov/opendata/browser/).\n\n## How to use\n\n```python\nfrom myeia import API\n\neia = API()\n```\n\n## Environment Variables\n\n```bash\n# Create a .env file in your projects root directory\ntouch .env\n```\n\nBy default the `API` class will look for your `EIA_TOKEN`.\n\nIf you have registered for an API key you can set it in your `.env` file.\n\n```ini\nEIA_TOKEN=YOUR_TOKEN_HERE\n```\n\n## Get Series\n\nLets look at an example of how to get the _EIA Natural Gas Futures_.\nYou 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`.\n\n```python\ndf = eia.get_series(series_id=\"NG.RNGC1.D\")\n\ndf = eia.get_series_via_route(\n    route=\"natural-gas/pri/fut\",\n    series=\"RNGC1\",\n    frequency=\"daily\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n            Natural Gas Futures Contract 1 (Dollars per Million Btu)\nDate\n2022-09-13                                              8.284\n2022-09-12                                              8.249\n2022-09-09                                              7.996\n2022-09-08                                              7.915\n2022-09-07                                              7.842\n...                                                       ...\n```\n\n## Different Facets\n\nLets 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`.\n\n```python\ndf = eia.get_series(series_id=\"STEO.PAPR_OPEC.M\")\n\ndf = eia.get_series_via_route(\n    route=\"steo\",\n    series=\"PAPR_OPEC\",\n    frequency=\"monthly\",\n    facet=\"seriesId\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n            Total OPEC Petroleum Supply\nDate\n2023-12-01                    34.517314\n2023-11-01                    34.440397\n2023-10-01                    34.376971\n2023-09-01                    34.416242\n2023-08-01                    34.451823\n...                                 ...\n```\n\n## Filter by multiple facets\n\nYou 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`.\nThe difference here is that both facet columns are present in the dataframe, unlike the previous examples where only one facet was present.\n\n```python\ndf = eia.get_series_via_route(\n    route=\"international\",\n    series=[\"ARE\", 55],\n    frequency=\"monthly\",\n    facet=[\"countryRegionId\", \"productId\"],\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n           countryRegionId productId  Crude oil, NGPL, and other liquids\nDate\n2024-03-01             ARE        55                         4132.394334\n2024-02-01             ARE        55                         4132.394334\n2024-01-01             ARE        55                         4142.394334\n2023-12-01             ARE        55                         4082.394334\n2023-11-01             ARE        55                         4082.394334\n...                    ...       ...                                 ...\n```\n\n## Get Multiple Series\n\nFor multiple series you have to loop through the series and append the data to a list.\n\n```python\ndata = []\nfor item in [\"RNGC1\", \"RNGC2\"]:\n    df = eia.get_series_via_route(\n    route=\"natural-gas/pri/fut\",\n    series=item,\n    frequency=\"daily\",\n    facet=\"series\",\n    )\n    data.append(df)\n\ndf = pd.concat(data, axis=1)\ndf.head()\n```\n\nOutput Example:\n\n```ini\n            Natural Gas Futures Contract 1 (Dollars per Million Btu)  Natural Gas Futures Contract 2 (Dollars per Million Btu)\nDate\n2023-08-29                                              2.556                                                     2.662\n2023-08-28                                              2.579                                                     2.665\n2023-08-25                                              2.540                                                     2.657\n2023-08-24                                              2.519                                                     2.636\n2023-08-23                                              2.497                                                     2.592\n...                                                       ...                                                       ...\n```\n\n## Define a Start and End Date\n\nYou can define a start and end date for your query.\n\n```python\ndf = eia.get_series(\n    series_id=\"NG.RNGC1.D\",\n    start_date=\"2021-01-01\",\n    end_date=\"2021-01-31\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n            Natural Gas Futures Contract 1 (Dollars per Million Btu)\nDate\n2021-01-29                                              2.564\n2021-01-28                                              2.664\n2021-01-27                                              2.760\n2021-01-26                                              2.656\n2021-01-25                                              2.602\n...                                                       ...\n```\n\nThis also works for the `get_series_via_route` method.\n\n```python\ndf = eia.get_series_via_route(\n    route=\"natural-gas/pri/fut\",\n    series=\"RNGC1\",\n    frequency=\"daily\",\n    start_date=\"2021-01-01\",\n    end_date=\"2021-01-31\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n            Natural Gas Futures Contract 1 (Dollars per Million Btu)\nDate\n2021-01-29                                              2.564\n2021-01-28                                              2.664\n2021-01-27                                              2.760\n2021-01-26                                              2.656\n2021-01-25                                              2.602\n...                                                       ...\n```\n\n## Contributing\n\nWe love your input! We want to make contributing to this project as easy and transparent as possible.\nRead our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilsv%2Fmyeia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilsv%2Fmyeia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilsv%2Fmyeia/lists"}