| Name | EIAOpenData JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | https://github.com/urazakgul/EIAOpenData |
| Summary | EIAOpenData is a Python package that provides easy access to various energy-related data obtained from the Energy Information Administration (EIA) API. |
| upload_time | 2023-09-11 20:15:15 |
| maintainer | |
| docs_url | None |
| author | Uraz Akgül |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# EIAOpenData v0.1.1
## Description
`EIAOpenData` is a Python package that provides easy access to various energy-related data obtained from the Energy Information Administration (EIA) API.
*** WARNING ***
To get your API key, please visit: https://www.eia.gov/opendata/
### Supported Categories
This package provides access to a wide range of energy-related data categories, including:
* Coal
* Crude Oil Imports
* Electricity
* International
* Natural Gas
* Nuclear Outages
* Petroleum
* State Energy Data System (SEDS)
* Short Term Energy Outlook
* Densified Biomass
* Total Energy
* Annual Energy Outlook
* International Energy Outlook
* State CO2 Emissions
## Installation
Follow the steps below to use the library:
1. Install Python on your system: https://www.python.org/downloads/
2. Open the terminal and run the following command to install the package:
```bash
pip install EIAOpenData
```
If you want to install a specific version, you can run the command as in the example below.
```bash
pip install EIAOpenData==0.1.1
```
You can find the version of the installed package with the following command.
```bash
pip show EIAOpenData
```
## Usage
### Importing the Library
```python
from EIAOpenData import EIAOpenData
```
### The EIAOpenData Class and Its Methods:
#### `EIAOpenData`
This class is designed for retrieving data from the EIA (Energy Information Administration) API.
* Description: Initializes the EIAOpenData class with your EIA API key.
* Parameters:
* `api_key` (str): Your EIA API key. It is required to make API requests.
`get_data(route, data_param, frequency=None, start_date=None, end_date=None, facet_name=None, facet_values=None)`
* Description: Fetches data from the API.
* Parameters:
* `route` (str): The target route for the API request (e.g., "petroleum/crd/crpdn").
* `data_param` (str): The data parameter to include in the URL (e.g., "value").
* `frequency` (str, optional): The frequency parameter to include in the URL (e.g., "monthly").
* `start_date` (str, optional): The start date in a valid date format (e.g., "2005-03").
* `end_date` (str, optional): The end date in a valid date format (e.g., "2022-11").
* `facet_name` (str, optional): The facet name to filter the data (e.g., "product").
* `facet_values` (list, optional): The facet values to filter the data (e.g., ["EPC0"]).
* Returns: DataFrame.
`filter_and_select_columns(df, filter_columns=None, filter_values=None, selected_columns=None)`
* Description: Filters a DataFrame by specific columns and their corresponding values, and selects columns.
* Parameters:
* `df` (Pandas DataFrame): DataFrame to filter.
* `filter_columns` (list, optional): List of column names to filter.
* `filter_values` (list, optional): List of filter values corresponding to the filter_columns.
* `selected_columns` (list, optional): List of column names to select.
* Returns: Filtered DataFrame with selected columns.
`save_to_excel(df, file_name)`
* Description: Saves a DataFrame to an Excel file with a .xlsx extension.
* Parameters:
* `df` (Pandas DataFrame): DataFrame to save.
* `file_name` (str): Name of the Excel file (without the .xlsx extension).
* Returns: True if the DataFrame is saved successfully, False otherwise.
### Examples
```python
my_api_key = 'your_api_key' # Replace 'your_api_key' with your actual API key.
eia = EIAOpenData(my_api_key) # Initialize EIAOpenData with your API key.
# Visit the EIA Open Data API Dashboard: https://www.eia.gov/opendata/
# Select your desired dataset and parameters from the API Dashboard.
# For example, let's choose "Petroleum/Imports/Exports And Movements/Weekly Imports & Exports."
# Examine the URL of the selected dataset. An example URL might look like this:
# https://www.eia.gov/opendata/browser/petroleum/move/wkly?frequency=weekly&data=value;&sortColumn=period;&sortDirection=desc;
# By inspecting the URL, you can determine the appropriate values for 'route' and 'data_param.'
# In the example URL above:
# - 'route' can be set to 'petroleum/move/wkly' based on the path in the URL.
# - 'data_param' can be set to 'value' based on the 'data' parameter in the URL.
# Optionally, you can further customize your data retrieval by specifying:
# - 'frequency' to set the desired data frequency (e.g., 'weekly', 'monthly', 'annual').
# - 'start_date' to specify the beginning date for the data you want to retrieve.
# - 'end_date' to specify the end date for the data you want to retrieve.
# - 'facet_name' to define the facet by which you want to filter the data.
# - 'facet_values' to specify the values within the chosen facet by which to filter the data.
# Define the API route for fetching data related to weekly petroleum imports and exports.
# Adjust this value according to the dataset path from the URL.
# You can add a "/" at the beginning and/or end.
route = 'petroleum/move/wkly'
# Define the data parameter that specifies what type of data to retrieve.
# Adjust this value based on the 'data' parameter from the URL.
data_param = 'value'
# Specify the data retrieval parameters.
frequency='four-week-average' # Data frequency.
start_date='2018-01-01' # Start date for data retrieval.
end_date='2023-08-25' # End date for data retrieval.
# Specify the facet parameters for data filtering.
facet_name = 'product' # Name of the facet to filter by.
facet_values = ['EPC0','EPJK'] # Values to filter within the facet.
# Fetch data from the EIA API
my_data = eia.get_data(
route,
data_param,
frequency=frequency,
start_date=start_date,
end_date=end_date,
facet_name=facet_name,
facet_values=facet_values
)
# Save the retrieved data to an Excel file named 'my_data'
eia.save_to_excel(my_data, 'my_data')
# Filter the data to select only records where 'product-name' is 'Crude Oil'
# and select columns 'period', 'product-name', and 'value'
my_new_data = eia.filter_and_select_columns(
my_data,
filter_columns=['product-name'],
filter_values=['Crude Oil'],
selected_columns=['period', 'product-name', 'value']
)
# Save the filtered and selected data to an Excel file named 'my_new_data'
eia.save_to_excel(my_new_data, 'my_new_data')
```
## Notes
* The EIAOpenData library relies on data from the Energy Information Administration (EIA). To ensure the accuracy and continuity of the data, please check the relevant website: [The U.S. Energy Information Administration Open Data](https://www.eia.gov/opendata/). You can visit the EIA's official website to verify the data and stay updated on any changes or updates to their datasets.
* I welcome your feedback for the development and improvement of the library. Contribute to the GitHub repo: [GitHub Repo](https://github.com/urazakgul/EIAOpenData)
* Please report any issues or suggestions by opening a new issue in the "Issue" section of the GitHub repo: [GitHub Issues](https://github.com/urazakgul/EIAOpenData/issues)
## Release Notes
### v0.1.0 - 02/09/2023
* First version released.
### v0.1.1 - 12/09/2023
* Added the ability to customize data retrieval by specifying `facet_name` and `facet_values` parameters for more precise filtering of dataset facets.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/urazakgul/EIAOpenData",
"name": "EIAOpenData",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Uraz Akg\u00fcl",
"author_email": "urazdev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/79/75378414318860b7627a3f901c37717e01497f676bcc4f1c0c0aead83b40/EIAOpenData-0.1.1.tar.gz",
"platform": null,
"description": "# EIAOpenData v0.1.1\r\n\r\n## Description\r\n\r\n`EIAOpenData` is a Python package that provides easy access to various energy-related data obtained from the Energy Information Administration (EIA) API.\r\n\r\n*** WARNING ***\r\n\r\nTo get your API key, please visit: https://www.eia.gov/opendata/\r\n\r\n### Supported Categories\r\n\r\nThis package provides access to a wide range of energy-related data categories, including:\r\n\r\n* Coal\r\n* Crude Oil Imports\r\n* Electricity\r\n* International\r\n* Natural Gas\r\n* Nuclear Outages\r\n* Petroleum\r\n* State Energy Data System (SEDS)\r\n* Short Term Energy Outlook\r\n* Densified Biomass\r\n* Total Energy\r\n* Annual Energy Outlook\r\n* International Energy Outlook\r\n* State CO2 Emissions\r\n\r\n## Installation\r\n\r\nFollow the steps below to use the library:\r\n\r\n1. Install Python on your system: https://www.python.org/downloads/\r\n2. Open the terminal and run the following command to install the package:\r\n\r\n```bash\r\npip install EIAOpenData\r\n```\r\n\r\nIf you want to install a specific version, you can run the command as in the example below.\r\n\r\n```bash\r\npip install EIAOpenData==0.1.1\r\n```\r\n\r\nYou can find the version of the installed package with the following command.\r\n\r\n```bash\r\npip show EIAOpenData\r\n```\r\n\r\n## Usage\r\n\r\n### Importing the Library\r\n\r\n```python\r\nfrom EIAOpenData import EIAOpenData\r\n```\r\n\r\n### The EIAOpenData Class and Its Methods:\r\n\r\n#### `EIAOpenData`\r\n\r\nThis class is designed for retrieving data from the EIA (Energy Information Administration) API.\r\n\r\n* Description: Initializes the EIAOpenData class with your EIA API key.\r\n* Parameters:\r\n * `api_key` (str): Your EIA API key. It is required to make API requests.\r\n\r\n`get_data(route, data_param, frequency=None, start_date=None, end_date=None, facet_name=None, facet_values=None)`\r\n\r\n* Description: Fetches data from the API.\r\n* Parameters:\r\n * `route` (str): The target route for the API request (e.g., \"petroleum/crd/crpdn\").\r\n * `data_param` (str): The data parameter to include in the URL (e.g., \"value\").\r\n * `frequency` (str, optional): The frequency parameter to include in the URL (e.g., \"monthly\").\r\n * `start_date` (str, optional): The start date in a valid date format (e.g., \"2005-03\").\r\n * `end_date` (str, optional): The end date in a valid date format (e.g., \"2022-11\").\r\n * `facet_name` (str, optional): The facet name to filter the data (e.g., \"product\").\r\n * `facet_values` (list, optional): The facet values to filter the data (e.g., [\"EPC0\"]).\r\n* Returns: DataFrame.\r\n\r\n`filter_and_select_columns(df, filter_columns=None, filter_values=None, selected_columns=None)`\r\n\r\n* Description: Filters a DataFrame by specific columns and their corresponding values, and selects columns.\r\n* Parameters:\r\n * `df` (Pandas DataFrame): DataFrame to filter.\r\n * `filter_columns` (list, optional): List of column names to filter.\r\n * `filter_values` (list, optional): List of filter values corresponding to the filter_columns.\r\n * `selected_columns` (list, optional): List of column names to select.\r\n* Returns: Filtered DataFrame with selected columns.\r\n\r\n`save_to_excel(df, file_name)`\r\n\r\n* Description: Saves a DataFrame to an Excel file with a .xlsx extension.\r\n* Parameters:\r\n * `df` (Pandas DataFrame): DataFrame to save.\r\n * `file_name` (str): Name of the Excel file (without the .xlsx extension).\r\n* Returns: True if the DataFrame is saved successfully, False otherwise.\r\n\r\n### Examples\r\n\r\n```python\r\nmy_api_key = 'your_api_key' # Replace 'your_api_key' with your actual API key.\r\neia = EIAOpenData(my_api_key) # Initialize EIAOpenData with your API key.\r\n\r\n# Visit the EIA Open Data API Dashboard: https://www.eia.gov/opendata/\r\n\r\n# Select your desired dataset and parameters from the API Dashboard.\r\n# For example, let's choose \"Petroleum/Imports/Exports And Movements/Weekly Imports & Exports.\"\r\n\r\n# Examine the URL of the selected dataset. An example URL might look like this:\r\n# https://www.eia.gov/opendata/browser/petroleum/move/wkly?frequency=weekly&data=value;&sortColumn=period;&sortDirection=desc;\r\n\r\n# By inspecting the URL, you can determine the appropriate values for 'route' and 'data_param.'\r\n# In the example URL above:\r\n# - 'route' can be set to 'petroleum/move/wkly' based on the path in the URL.\r\n# - 'data_param' can be set to 'value' based on the 'data' parameter in the URL.\r\n\r\n# Optionally, you can further customize your data retrieval by specifying:\r\n# - 'frequency' to set the desired data frequency (e.g., 'weekly', 'monthly', 'annual').\r\n# - 'start_date' to specify the beginning date for the data you want to retrieve.\r\n# - 'end_date' to specify the end date for the data you want to retrieve.\r\n# - 'facet_name' to define the facet by which you want to filter the data.\r\n# - 'facet_values' to specify the values within the chosen facet by which to filter the data.\r\n\r\n# Define the API route for fetching data related to weekly petroleum imports and exports.\r\n# Adjust this value according to the dataset path from the URL.\r\n# You can add a \"/\" at the beginning and/or end.\r\nroute = 'petroleum/move/wkly'\r\n\r\n# Define the data parameter that specifies what type of data to retrieve.\r\n# Adjust this value based on the 'data' parameter from the URL.\r\ndata_param = 'value'\r\n\r\n# Specify the data retrieval parameters.\r\nfrequency='four-week-average' # Data frequency.\r\nstart_date='2018-01-01' # Start date for data retrieval.\r\nend_date='2023-08-25' # End date for data retrieval.\r\n\r\n# Specify the facet parameters for data filtering.\r\nfacet_name = 'product' # Name of the facet to filter by.\r\nfacet_values = ['EPC0','EPJK'] # Values to filter within the facet.\r\n\r\n# Fetch data from the EIA API\r\nmy_data = eia.get_data(\r\n route,\r\n data_param,\r\n frequency=frequency,\r\n start_date=start_date,\r\n end_date=end_date,\r\n facet_name=facet_name,\r\n facet_values=facet_values\r\n)\r\n\r\n# Save the retrieved data to an Excel file named 'my_data'\r\neia.save_to_excel(my_data, 'my_data')\r\n\r\n# Filter the data to select only records where 'product-name' is 'Crude Oil'\r\n# and select columns 'period', 'product-name', and 'value'\r\nmy_new_data = eia.filter_and_select_columns(\r\n my_data,\r\n filter_columns=['product-name'],\r\n filter_values=['Crude Oil'],\r\n selected_columns=['period', 'product-name', 'value']\r\n)\r\n\r\n# Save the filtered and selected data to an Excel file named 'my_new_data'\r\neia.save_to_excel(my_new_data, 'my_new_data')\r\n```\r\n\r\n## Notes\r\n\r\n* The EIAOpenData library relies on data from the Energy Information Administration (EIA). To ensure the accuracy and continuity of the data, please check the relevant website: [The U.S. Energy Information Administration Open Data](https://www.eia.gov/opendata/). You can visit the EIA's official website to verify the data and stay updated on any changes or updates to their datasets.\r\n* I welcome your feedback for the development and improvement of the library. Contribute to the GitHub repo: [GitHub Repo](https://github.com/urazakgul/EIAOpenData)\r\n* Please report any issues or suggestions by opening a new issue in the \"Issue\" section of the GitHub repo: [GitHub Issues](https://github.com/urazakgul/EIAOpenData/issues)\r\n\r\n## Release Notes\r\n\r\n### v0.1.0 - 02/09/2023\r\n\r\n* First version released.\r\n\r\n### v0.1.1 - 12/09/2023\r\n\r\n* Added the ability to customize data retrieval by specifying `facet_name` and `facet_values` parameters for more precise filtering of dataset facets.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "EIAOpenData is a Python package that provides easy access to various energy-related data obtained from the Energy Information Administration (EIA) API.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/urazakgul/EIAOpenData"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "407975378414318860b7627a3f901c37717e01497f676bcc4f1c0c0aead83b40",
"md5": "8dc2ff15af37a211d99244a4ae02473e",
"sha256": "480f442c1d3d2f8bc6b29c326630776c86fd84eaaac3bfed6f21f56e8f1dbfc1"
},
"downloads": -1,
"filename": "EIAOpenData-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8dc2ff15af37a211d99244a4ae02473e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6174,
"upload_time": "2023-09-11T20:15:15",
"upload_time_iso_8601": "2023-09-11T20:15:15.545170Z",
"url": "https://files.pythonhosted.org/packages/40/79/75378414318860b7627a3f901c37717e01497f676bcc4f1c0c0aead83b40/EIAOpenData-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-11 20:15:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "urazakgul",
"github_project": "EIAOpenData",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "eiaopendata"
}
