Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tonyhollaar/streamlit_connection
Streamlit example st.experimental_connection()
https://github.com/tonyhollaar/streamlit_connection
Last synced: about 17 hours ago
JSON representation
Streamlit example st.experimental_connection()
- Host: GitHub
- URL: https://github.com/tonyhollaar/streamlit_connection
- Owner: tonyhollaar
- License: mit
- Created: 2023-07-25T03:19:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-04T14:47:40.000Z (3 months ago)
- Last Synced: 2024-08-04T16:37:48.740Z (3 months ago)
- Language: Python
- Size: 2.79 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://bls-connection-demo.streamlit.app/)
# App Description
[This application](https://bls-connection-demo.streamlit.app/) is created as part of the **Streamlit Connections Hackathon 🎉** [contest](https://discuss.streamlit.io/t/connections-hackathon/47574). The goal of this app is to demonstrate how to easily set up and retrieve data from one of my favorite data **APIs** (Application Programming Interfaces) – the public datasets from the *U.S. Bureau of Labor Statistics* (BLS) – by utilizing a custom-built **Streamlit** connection 🔌. This allows you to query the dataset(s) and save them as [pandas](https://pandas.pydata.org/) dataframes, providing a more user-friendly approach compared to the original Python code from BLS, which can be found [here](https://www.bls.gov/developers/api_python.htm#python2).
Feel free to explore the app's demonstration video below (🔊 make sure to have the sound on for some background music 🎵).
https://github.com/tonyhollaar/streamlit_connection/assets/121459374/7a25b2e3-baba-4e23-accf-9781b9f09a4c
## App Features
- Display data retrieved from the BLS API in a user-friendly manner using Streamlit.
- Visualize datasets with interactive charts and plots.
- Allow users to customize input parameters for data retrieval.
# Streamlit Connection API
# 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)
- [How do I use the API Key?](#how-do-i-use-the-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!
## Acknowledgements
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.
## How do I use the API Key?
There are two options:
1. Enter the API key in the .query method as a string!
```Python
import streamlit as st
from streamlit_bls_connection import BLSConnection
conn = st.experimental_connection('bls', type=BLSConnection)
dataframes_dict = conn.query(seriesids_list=['APU000074714'], start_year_str='2020', end_year_str='2023', api_key='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', catalog=True, calculations=True, annualaverage=True, aspects=True)
```
2. If you cloned this repository and run it on your local machine you can add a secrets.toml file in your .streamlit subfolder (.streamlit/secrets.toml) with the below text and replace with your own API key and 'save':
```Python
#secrets.toml
[connections_bls]
api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
```
In your main.py file you can then add:
```Python
import streamlit as st
from streamlit_bls_connection import BLSConnection
conn = st.experimental_connection('bls', type=BLSConnection)
dataframes_dict = conn.query(seriesids_list=['APU000074714'], start_year_str='2020', end_year_str='2023', api_key=st.secrets["connections_bls"]["api_key"], catalog=True, calculations=True, annualaverage=True, aspects=True)
```
## 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/)