This application is created as part of the Streamlit Connections Hackathon 🎉 contest. 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 dataframes, providing a more user-friendly approach compared to the original Python code from BLS, which can be found here. Feel free to explore the app's demonstration video below (🔊 make sure to have the sound on for some background music 🎵).

• 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.

• Description
• How to use streamlit-bls-connection
  • Installation
  • Create .py file
  • In terminal set file path of folder containing .py file
  • Run Streamlit App
• Documentation
• Requirements
• License
• Contact
• Reporting Issues
• Acknowledgements
• How do I obtain an API Key?
• How do I use the API Key?
• Use in Google Colab
• Streamlit Demo

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 !

To run the Streamlit app locally on your machine, follow these steps:

1. Install the streamlit-bls-connection package and its dependencies by running the following command in your terminal or command prompt:

pip install streamlit_bls_connection

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.

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)

3. In your terminal or command prompt, navigate to the directory where your Python script is located.

cd /path/to/your/python/script

4. Run the Streamlit app using the following command:

streamlit run app.py

5. See your results in the browser of your Streamlit App!

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.

• Python version 3.8 and above

This project is licensed under the MIT License. See the LICENSE file for details.

For questions, suggestions, or contributions, please visit my GitHub Profile.

If you encounter any problems 🔥, have questions ❓, or want to request a new feature 🆕, please feel free to open an issue on GitHub. 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!

Special thanks 👏 to the Streamlit team for creating an amazing framework for building interactive web apps with Python.

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/.

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.

There are two options:

1. Enter the API key in the .query method as a string!

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':

#secrets.toml
[connections_bls]
api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

In your main.py file you can then add:

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)

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!

If you want to see a showcase demo 🚀 in Streamlit, click the link below!