Guide to using the Bureau of Labor Statistics (BLS) Public Data API to access data from the Occupational Employment and Wage Statistics (OEWS) survey.
This tutorial was developed by the Bloomberg Center for Government Excellence (GovEx) Research & Analytics team. When possible, we automate data collection through the BLS API rather than downloading Data Tables. Since BLS series ID construction is complex and OEWS specific examples are not included in the official API documentation, we created this tutorial to help others query OEWS data with Python.
Querying the API requires constructing series IDs that specify exactly which data you want. Each OEWS series ID encodes the geographic area, occupation, industry, and employment or wage measure you're requesting.
OEWS series IDs follow this 25-character format:
OE + U + areatype_code(1) + area_code(7) + industry_code(6) + occupation_code(6) + datatype_code(2)
| Component | Position | Length | Example Value | Description |
|---|---|---|---|---|
| Survey | 1-2 | 2 | OE |
Survey (always OE) |
| Seasonal | 3 | 1 | U |
Not seasonally adjusted (always U) |
| Area Type | 4 | 1 | M |
M (metro), S (state), N (national) |
| Area Code | 5-11 | 7 | 0011260 |
Geographic identifier (CBSA codes, State FIPS) |
| Industry | 12-17 | 6 | 000000 |
Industry classification (NAICS) |
| Occupation | 18-23 | 6 | 000000 |
Occupation classification (SOC) |
| Data Type | 24-25 | 2 | 13 |
Employment or Wage measure (01-17) |
Complete code definitions: reference/series_id_codes.json
Example Series IDs:
OEUN000000000000000000001: Total employment for all occupations across all industries in the United StatesOEUS280000000000025201113: Annual median wage for elementary school teachers in MississippiOEUM001910000000029124204: Annual mean wage for orthopedic surgeons in Dallas-Fort Worth, TX
- Year coverage: API provides only the most recent year. For historical data, use OEWS Data Tables
- Rate limits: 500 requests/day, 50 series per request (API v2 with registration). For large-scale data collection, remember to batch requests in groups of 50 with delays between requests to respect rate limits.
- Python 3.9+
- BLS API key (register at https://data.bls.gov/registrationEngine/)
# Clone the repository
git clone https://github.com/govex/bls-oews-api-tutorial.git
cd bls-oews-api-tutorial
# # Create and activate virtual environment (if needed)
uv venv
source .venv/bin/activate
# Install dependencies
uv pip install -e .
# Add your API key to .env file (if preferred)
echo "BLS_API_KEY=your_key_here" > .envimport requests
API_URL = 'https://api.bls.gov/publicAPI/v2/timeseries/data/'
API_KEY = 'your_api_key_here' # Or use your .env file
# Request median wage for all occupations in Atlanta MSA
series_id = 'OEUM001126000000000000013'
payload = {
"seriesid": [series_id],
"registrationkey": API_KEY
}
response = requests.post(API_URL, json=payload)
data = response.json()
if data['status'] == 'REQUEST_SUCCEEDED':
value = data['Results']['series'][0]['data'][0]['value']
print(f"Requested value: ${value}\n")
else:
print(f"API Error: {data.get('message', 'Unknown error')}\n")
print("Full API response:")
dataFor querying multiple series efficiently, see examples/batch_request.py. This example demonstrates querying median and mean annual wages for all major occupations across all US states.
python examples/batch_request.py- OEWS Overview
- OEWS Data Files
- OEWS Technical Documentation
- OEWS Profiles Definitions
- BLS API Documentation
- Standard Occupational Classification (SOC)
- North American Industry Classification System (NAICS)
Contributions and suggestions are welcome! Feel free to open issues or submit pull requests.
MIT License. See LICENSE for details.
Developed by the Bloomberg Center for Government Excellence (GovEx) Research & Analytics team.