<div align="center">
<img src="https://raw.githubusercontent.com/tonyhollaar/streamlit_bls_connection/main/logo.svg"><br>
</div>
# Table of Contents
- [Description](#description)
- [How to use streamlit-bls-connection](#how-to-use-streamlit-bls-connection)
- [Installation](#installation)
- [Create .py file](#create-py-file)
- [In terminal set file path of folder containing .py file](#in-terminal-set-file-path-of-folder-containing-py-file)
- [Run Streamlit App](#run-streamlit-app)
- [Documentation](#documentation)
- [Requirements](#requirements)
- [License](#license)
- [Contact](#contact)
- [Reporting Issues](#reporting-issues)
- [Acknowledgements](#acknowledgements)
- [How do I obtain an API Key?](#how-do-i-obtain-an-api-key)
- [Use in Google Colab](#use-in-google-colab)
- [Streamlit Demo](#streamlit-demo)
## Description
The `streamlit-bls-connection` Python package allows you to easily interact with the U.S. Bureau of Labor Statistics (BLS) API and retrieve data as pandas dataframes and display them in [`Streamlit`](https://docs.streamlit.io/) !
## How to use `streamlit-bls-connection`
To run the Streamlit app locally on your machine, follow these steps:
### Installation
1. Install the `streamlit-bls-connection` package and its dependencies by running the following command in your terminal or command prompt:
```bash
pip install streamlit_bls_connection
```
### Create .py file
2. Create a new Python script with your favorite text editor (e.g., VSCode, Spyder, Notepad++), name it `app.py` and copy/paste below code and save changes.
```python
import streamlit as st
from streamlit_bls_connection import BLSConnection
# Step 1: Setup connection to US Bureau of Labor Statistics
conn = st.experimental_connection('bls', type=BLSConnection)
# Step 2: Define input parameters
# Tip: one or multiple Series ID's* can be retrieved
# find Series ID's on www.bls.gov > DATA TOOLS
seriesids_list = ['APU000074714', 'APU000072610']
start_year_str = '2014' # start of date range
end_year_str = '2023' # end of date range
# Step 3: Fetch data using the custom connection
dataframes_dict = connection.query(seriesids_list,
start_year_str,
end_year_str,
api_key = None)
# Step 4: Create dataframes
gas_df = dataframes_dict['APU000074714']
electricity_df = dataframes_dict['APU000072610']
# Step 5: Show Dataframes in Streamlit
st.dataframe(gas_df)
st.dataframe(electricity_df)
```
### In terminal set file path of folder containing .py file
3. In your terminal or command prompt, navigate to the directory where your Python script is located.
```bash
cd /path/to/your/python/script
```
### Run Streamlit App
4. Run the Streamlit app using the following command:
```bash
streamlit run app.py
```
5. See your results in the browser of your Streamlit App!
### Documentation
`connection.query(seriesids: List[str], start_year: str, end_year: str, api_key: Optional[str] = None, catalog: bool = False, calculations: bool = False, annualaverage: bool = False, aspects: bool = False) -> Dict[str, pd.DataFrame]`
The `query` method of the `BLSConnection` class allows you to fetch data from the BLS API. Before using this method, you need to create a `BLSConnection` object using the `st.experimental_connection` function and import the `BLSConnection` class.
**Parameters:**
- `seriesids` (list of str):
- **Description:** A list of strings representing the BLS time series data to fetch.
- **Example:** `['APU000074714', 'APU000072610']`
- **Note:** The Series IDs are unique identifiers for specific datasets or statistical measures available from the Bureau of Labor Statistics. You can find Series IDs on the BLS website's DATA TOOLS section.
- `start_year` (str):
- **Description:** The start year for the data retrieval (inclusive), represented as a string.
- **Example:** `'2014'`
- **Note:** The data retrieval will begin from this year onwards.
- `end_year` (str):
- **Description:** The end year for the data retrieval (inclusive), represented as a string.
- **Example:** `'2023'`
- **Note:** The data retrieval will include data up to and including this year.
- `api_key` (str, optional):
- **Description:** The API key for accessing the BLS API. If provided, it enhances the data access capabilities, allowing for a larger number of requests.
- **Example:** `'YOUR_API_KEY_HERE'`
- **Note:** Without an API key, you might be subject to limitations on the number of requests you can make. To obtain an API key, you can register on the BLS website.
- `catalog`, `calculations`, `annualaverage`, `aspects` (bool, optional):
- **Description:** Optional boolean parameters to include additional data fields for each time series.
- **Default:** `False`
- `catalog`: Whether to include catalog data for the series. Catalog data provides information about the series, such as the title and survey name. (Accessible only with an API key)
- `calculations`: Whether to include calculated data for the series. Calculated data refers to additional statistics derived from the primary data series. (Accessible only with an API key)
- `annualaverage`: Whether to include annual average data for the series. This field will be relevant if the series has data computed as annual averages. (Accessible only with an API key)
- `aspects`: Whether to include additional aspects data for the series. Aspects data includes additional metadata or contextual information about the series. (Accessible only with an API key)
- **Note:** Enabling any of these parameters with an API key will include the corresponding data fields in the returned DataFrames. This additional information can be useful for more detailed analysis and visualization of the data.
**Returns:** A dictionary with Series IDs as keys and DataFrames as values, containing the fetched BLS data for each series. Each DataFrame includes columns for 'date', 'value', '%_change_value', 'year', 'month', 'period'. If the API key is provided, 'seriesID', 'series_title', and 'survey_name' columns are also included in the DataFrames. Empty or all-None columns are excluded from the DataFrames.
## Requirements
- Python version 3.8 and above
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Contact
For questions, suggestions, or contributions, please visit my [GitHub Profile](https://github.com/tonyhollaar).
## Reporting Issues
If you encounter any problems 🔥, have questions ❓, or want to request a new feature 🆕, please feel free to open an issue on [GitHub](https://github.com/tonyhollaar/streamlit_bls_connection/issues). I appreciate your feedback and will do our best to address any concerns promptly.
When reporting an issue, please provide as much detail as possible, including the version of the package, the Python version, and a clear description of the problem or feature request. This will help me better understand and resolve the issue quickly.
Thank you for your contributions to making this package better!
## Acknowledgments
Special thanks 👏 to the Streamlit team for creating an amazing framework for building interactive web apps with Python.
## How do I obtain an API Key?
Before using the `streamlit-bls-connection` package, you have the option to obtain an API key from the U.S. Bureau of Labor Statistics (BLS). The API key is required for enhanced data access capabilities, allowing for a larger number of requests.
To obtain your API key, follow these steps:
1. Visit the BLS registration page: [https://data.bls.gov/registrationEngine/](https://data.bls.gov/registrationEngine/).
2. Fill out the registration form with the necessary details.
3. Submit the registration form.
4. You should receive an email confirmation with your API key.
5. Copy your API key and use it as the value for the `api_key` parameter when using the `connection.query()` method.
Please note that the `api_key` parameter in the `connection.query()` method is optional. If you don't provide an API key, you might be subject to limitations on the number of requests you can make. However, you can still use the package without an API key, but with potential restrictions on the data you can access.
Having an API key will provide you with a more comprehensive and seamless experience when working with the BLS API.
## Use in Google Colab
If you want to try it out in the cloud ☁️, to see the `streamlit-bls-connection` with a Streamlit app in action, you can click the link below!
[](https://colab.research.google.com/github/tonyhollaar/streamlit_bls_connection/blob/main/example_googlecolab_streamlit_bls_connection.ipynb)
## Streamlit Demo
If you want to see a showcase demo 🚀 in Streamlit, click the link below!
[](https://bls-connection-demo.streamlit.app/)
Raw data
{
"_id": null,
"home_page": "https://github.com/tonyhollaar/",
"name": "streamlit-bls-connection",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "streamlit,api,bls",
"author": "Tony Hollaar",
"author_email": "thollaar@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ea/ab/72cae1a14243b304ddbb859f326121fd80ff36ccdfa981acf1e788a8b49f/streamlit_bls_connection-0.9.tar.gz",
"platform": null,
"description": "\n\n\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/tonyhollaar/streamlit_bls_connection/main/logo.svg\"><br>\n</div>\n\n# Table of Contents\n- [Description](#description)\n- [How to use streamlit-bls-connection](#how-to-use-streamlit-bls-connection)\n - [Installation](#installation)\n - [Create .py file](#create-py-file)\n - [In terminal set file path of folder containing .py file](#in-terminal-set-file-path-of-folder-containing-py-file)\n - [Run Streamlit App](#run-streamlit-app)\n- [Documentation](#documentation)\n- [Requirements](#requirements)\n- [License](#license)\n- [Contact](#contact)\n- [Reporting Issues](#reporting-issues)\n- [Acknowledgements](#acknowledgements)\n- [How do I obtain an API Key?](#how-do-i-obtain-an-api-key)\n- [Use in Google Colab](#use-in-google-colab)\n- [Streamlit Demo](#streamlit-demo)\n\n## Description\nThe `streamlit-bls-connection` Python package allows you to easily interact with the U.S. Bureau of Labor Statistics (BLS) API and retrieve data as pandas dataframes and display them in [`Streamlit`](https://docs.streamlit.io/) !\n\n## How to use `streamlit-bls-connection`\nTo run the Streamlit app locally on your machine, follow these steps:\n\n### Installation\n1. Install the `streamlit-bls-connection` package and its dependencies by running the following command in your terminal or command prompt:\n\n```bash\npip install streamlit_bls_connection\n```\n\n### Create .py file\n2. Create a new Python script with your favorite text editor (e.g., VSCode, Spyder, Notepad++), name it `app.py` and copy/paste below code and save changes.\n```python\nimport streamlit as st\nfrom streamlit_bls_connection import BLSConnection\n\n# Step 1: Setup connection to US Bureau of Labor Statistics\nconn = st.experimental_connection('bls', type=BLSConnection)\n\n# Step 2: Define input parameters\n# Tip: one or multiple Series ID's* can be retrieved\n# find Series ID's on www.bls.gov > DATA TOOLS\nseriesids_list = ['APU000074714', 'APU000072610']\nstart_year_str = '2014' # start of date range\nend_year_str = '2023' # end of date range\n\n# Step 3: Fetch data using the custom connection\ndataframes_dict = connection.query(seriesids_list,\n start_year_str, \n end_year_str,\n api_key = None)\n\n# Step 4: Create dataframes\ngas_df = dataframes_dict['APU000074714']\nelectricity_df = dataframes_dict['APU000072610']\n\n# Step 5: Show Dataframes in Streamlit\nst.dataframe(gas_df)\nst.dataframe(electricity_df)\n```\n\n### In terminal set file path of folder containing .py file\n3. In your terminal or command prompt, navigate to the directory where your Python script is located.\n```bash\ncd /path/to/your/python/script\n```\n### Run Streamlit App\n4. Run the Streamlit app using the following command:\n```bash\nstreamlit run app.py\n```\n5. See your results in the browser of your Streamlit App!\n\n### Documentation\n`connection.query(seriesids: List[str], start_year: str, end_year: str, api_key: Optional[str] = None, catalog: bool = False, calculations: bool = False, annualaverage: bool = False, aspects: bool = False) -> Dict[str, pd.DataFrame]`\n\nThe `query` method of the `BLSConnection` class allows you to fetch data from the BLS API. Before using this method, you need to create a `BLSConnection` object using the `st.experimental_connection` function and import the `BLSConnection` class.\n\n**Parameters:**\n\n- `seriesids` (list of str):\n - **Description:** A list of strings representing the BLS time series data to fetch.\n - **Example:** `['APU000074714', 'APU000072610']`\n - **Note:** The Series IDs are unique identifiers for specific datasets or statistical measures available from the Bureau of Labor Statistics. You can find Series IDs on the BLS website's DATA TOOLS section.\n\n- `start_year` (str):\n - **Description:** The start year for the data retrieval (inclusive), represented as a string.\n - **Example:** `'2014'`\n - **Note:** The data retrieval will begin from this year onwards.\n\n- `end_year` (str):\n - **Description:** The end year for the data retrieval (inclusive), represented as a string.\n - **Example:** `'2023'`\n - **Note:** The data retrieval will include data up to and including this year.\n\n- `api_key` (str, optional):\n - **Description:** The API key for accessing the BLS API. If provided, it enhances the data access capabilities, allowing for a larger number of requests.\n - **Example:** `'YOUR_API_KEY_HERE'`\n - **Note:** Without an API key, you might be subject to limitations on the number of requests you can make. To obtain an API key, you can register on the BLS website.\n\n- `catalog`, `calculations`, `annualaverage`, `aspects` (bool, optional):\n - **Description:** Optional boolean parameters to include additional data fields for each time series.\n - **Default:** `False`\n - `catalog`: Whether to include catalog data for the series. Catalog data provides information about the series, such as the title and survey name. (Accessible only with an API key)\n - `calculations`: Whether to include calculated data for the series. Calculated data refers to additional statistics derived from the primary data series. (Accessible only with an API key)\n - `annualaverage`: Whether to include annual average data for the series. This field will be relevant if the series has data computed as annual averages. (Accessible only with an API key)\n - `aspects`: Whether to include additional aspects data for the series. Aspects data includes additional metadata or contextual information about the series. (Accessible only with an API key)\n - **Note:** Enabling any of these parameters with an API key will include the corresponding data fields in the returned DataFrames. This additional information can be useful for more detailed analysis and visualization of the data.\n\n**Returns:** A dictionary with Series IDs as keys and DataFrames as values, containing the fetched BLS data for each series. Each DataFrame includes columns for 'date', 'value', '%_change_value', 'year', 'month', 'period'. If the API key is provided, 'seriesID', 'series_title', and 'survey_name' columns are also included in the DataFrames. Empty or all-None columns are excluded from the DataFrames.\n\n## Requirements\n- Python version 3.8 and above\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Contact\nFor questions, suggestions, or contributions, please visit my [GitHub Profile](https://github.com/tonyhollaar).\n\n## Reporting Issues\n\nIf you encounter any problems \ud83d\udd25, have questions \u2753, or want to request a new feature \ud83c\udd95, please feel free to open an issue on [GitHub](https://github.com/tonyhollaar/streamlit_bls_connection/issues). I appreciate your feedback and will do our best to address any concerns promptly.\n\nWhen reporting an issue, please provide as much detail as possible, including the version of the package, the Python version, and a clear description of the problem or feature request. This will help me better understand and resolve the issue quickly.\n\nThank you for your contributions to making this package better!\n\n## Acknowledgments\nSpecial thanks \ud83d\udc4f to the Streamlit team for creating an amazing framework for building interactive web apps with Python.\n\n## How do I obtain an API Key?\nBefore using the `streamlit-bls-connection` package, you have the option to obtain an API key from the U.S. Bureau of Labor Statistics (BLS). The API key is required for enhanced data access capabilities, allowing for a larger number of requests.\n\nTo obtain your API key, follow these steps:\n\n1. Visit the BLS registration page: [https://data.bls.gov/registrationEngine/](https://data.bls.gov/registrationEngine/).\n\n2. Fill out the registration form with the necessary details.\n\n3. Submit the registration form.\n\n4. You should receive an email confirmation with your API key.\n\n5. Copy your API key and use it as the value for the `api_key` parameter when using the `connection.query()` method.\n\nPlease note that the `api_key` parameter in the `connection.query()` method is optional. If you don't provide an API key, you might be subject to limitations on the number of requests you can make. However, you can still use the package without an API key, but with potential restrictions on the data you can access.\n\nHaving an API key will provide you with a more comprehensive and seamless experience when working with the BLS API.\n\n## Use in Google Colab\nIf you want to try it out in the cloud \u2601\ufe0f, to see the `streamlit-bls-connection` with a Streamlit app in action, you can click the link below!\n\n[](https://colab.research.google.com/github/tonyhollaar/streamlit_bls_connection/blob/main/example_googlecolab_streamlit_bls_connection.ipynb)\n\n## Streamlit Demo\nIf you want to see a showcase demo \ud83d\ude80 in Streamlit, click the link below!\n\n[](https://bls-connection-demo.streamlit.app/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package to fetch Bureau of Labor Statistics data using Streamlit",
"version": "0.9",
"project_urls": {
"Download": "https://github.com/tonyhollaar/streamlit_bls_connection/archive/refs/tags/v0.8.tar.gz",
"Homepage": "https://github.com/tonyhollaar/"
},
"split_keywords": [
"streamlit",
"api",
"bls"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "47ac2cf7e65bbd395e50ca0d8305f322ef5bc2174dd47f0098a335eafc87e8e6",
"md5": "22a77e9c86b9afa62790403f96e37ddd",
"sha256": "c205dee1da4f91036f1223c0843dfc43d7e038c92e8fce628f2ca470a53caee3"
},
"downloads": -1,
"filename": "streamlit_bls_connection-0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22a77e9c86b9afa62790403f96e37ddd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9234,
"upload_time": "2023-08-04T21:49:33",
"upload_time_iso_8601": "2023-08-04T21:49:33.629380Z",
"url": "https://files.pythonhosted.org/packages/47/ac/2cf7e65bbd395e50ca0d8305f322ef5bc2174dd47f0098a335eafc87e8e6/streamlit_bls_connection-0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eaab72cae1a14243b304ddbb859f326121fd80ff36ccdfa981acf1e788a8b49f",
"md5": "44116fb1dcbe0170271c19507bb34e3f",
"sha256": "606f7f0eebd35e9c2b69c889534fc9c7f7df3685cbe358cf07957e1a102482ed"
},
"downloads": -1,
"filename": "streamlit_bls_connection-0.9.tar.gz",
"has_sig": false,
"md5_digest": "44116fb1dcbe0170271c19507bb34e3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11764,
"upload_time": "2023-08-04T21:49:35",
"upload_time_iso_8601": "2023-08-04T21:49:35.311309Z",
"url": "https://files.pythonhosted.org/packages/ea/ab/72cae1a14243b304ddbb859f326121fd80ff36ccdfa981acf1e788a8b49f/streamlit_bls_connection-0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-04 21:49:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tonyhollaar",
"github_project": "streamlit_bls_connection",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "streamlit-bls-connection"
}
JSON
