giteaadmin/bls-data
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial BLS data reference and DC/MD/VA unemployment dashboard

Browse Source 
Includes:
- API v1/v2 documentation, endpoints, request/response schemas
- Complete survey catalog (60 surveys, live-fetched from API)
- Series ID decode tables: LAUS, CES, SM, QCEW, OES, JOLTS, CPI, PPI
- QCEW quarterly (47 fields) and annual (43 fields) CSV schemas
- dc_md_va_unemployment.py: pulls 16 LAUS series for DC/MD/VA + DC MSA
- Example API response and 5-year CSV output

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
David Boyd
2026-06-16 11:03:14 -04:00
commit 2b9d3e6d68
9 changed files with 3218 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
qcew_field_schema.md Normal file
View File

@ -0,0 +1,179 @@
# QCEW File Field Schemas
Source: https://data.bls.gov/cew/doc/layouts/
QCEW bulk data is available as CSV files by area, by industry, or as singlefiles (no title columns).
Download: https://www.bls.gov/cew/downloadable-data-files.htm
---
## Quarterly CSV Field Layout
| # | Field Name | Type | Max Len | Description |
|---|-----------|------|---------|-------------|
| 1 | area_fips | Text | 5 | 5-character FIPS code |
| 2 | own_code | Text | 1 | Ownership code |
| 3 | industry_code | Text | 6 | NAICS or SuperSector code |
| 4 | agglvl_code | Text | 2 | Aggregation level code |
| 5 | size_code | Text | 1 | Size code |
| 6 | year | Text | 4 | Year |
| 7 | qtr | Text | 1 | Quarter (1–4; A for annual) |
| 8 | disclosure_code | Text | 1 | `' '`=disclosed; `N`=not disclosed |
| 9 | area_title | Text | 80 | Area name (excluded from singlefile) |
| 10 | own_title | Text | 80 | Ownership description (excluded from singlefile) |
| 11 | industry_title | Text | 80 | Industry description (excluded from singlefile) |
| 12 | agglvl_title | Text | 80 | Aggregation level title (excluded from singlefile) |
| 13 | size_title | Text | 80 | Size class title (excluded from singlefile) |
| 14 | qtrly_estabs | Numeric | 8 | Count of establishments for the quarter |
| 15 | month1_emplvl | Numeric | 9 | Employment, month 1 of quarter |
| 16 | month2_emplvl | Numeric | 9 | Employment, month 2 of quarter |
| 17 | month3_emplvl | Numeric | 9 | Employment, month 3 of quarter |
| 18 | total_qtrly_wages | Numeric | 15 | Total wages for the quarter |
| 19 | taxable_qtrly_wages | Numeric | 15 | Taxable wages for the quarter |
| 20 | qtrly_contributions | Numeric | 13 | UI contributions for the quarter |
| 21 | avg_wkly_wage | Numeric | 8 | Average weekly wage for the quarter |
| 22 | lq_disclosure_code | Text | 1 | Location quotient disclosure code |
| 23 | lq_qtrly_estabs | Numeric | 8 | LQ of establishment count vs. U.S. |
| 24 | lq_month1_emplvl | Numeric | 8 | LQ of month 1 employment vs. U.S. |
| 25 | lq_month2_emplvl | Numeric | 8 | LQ of month 2 employment vs. U.S. |
| 26 | lq_month3_emplvl | Numeric | 8 | LQ of month 3 employment vs. U.S. |
| 27 | lq_total_qtrly_wages | Numeric | 8 | LQ of total quarterly wages vs. U.S. |
| 28 | lq_taxable_qtrly_wages | Numeric | 8 | LQ of taxable quarterly wages vs. U.S. |
| 29 | lq_qtrly_contributions | Numeric | 8 | LQ of quarterly contributions vs. U.S. |
| 30 | lq_avg_wkly_wage | Numeric | 8 | LQ of average weekly wage vs. U.S. |
| 31 | oty_disclosure_code | Text | 1 | Over-the-year disclosure code |
| 32 | oty_qtrly_estabs_chg | Numeric | 8 | OTY change in establishment count |
| 33 | oty_qtrly_estabs_pct_chg | Numeric | 8 | OTY % change in establishment count |
| 34 | oty_month1_emplvl_chg | Numeric | 9 | OTY change in month 1 employment |
| 35 | oty_month1_emplvl_pct_chg | Numeric | 8 | OTY % change in month 1 employment |
| 36 | oty_month2_emplvl_chg | Numeric | 9 | OTY change in month 2 employment |
| 37 | oty_month2_emplvl_pct_chg | Numeric | 8 | OTY % change in month 2 employment |
| 38 | oty_month3_emplvl_chg | Numeric | 9 | OTY change in month 3 employment |
| 39 | oty_month3_emplvl_pct_chg | Numeric | 8 | OTY % change in month 3 employment |
| 40 | oty_total_qtrly_wages_chg | Numeric | 15 | OTY change in total wages |
| 41 | oty_total_qtrly_wages_pct_chg | Numeric | 8 | OTY % change in total wages |
| 42 | oty_taxable_qtrly_wages_chg | Numeric | 15 | OTY change in taxable wages |
| 43 | oty_taxable_qtrly_wages_pct_chg | Numeric | 8 | OTY % change in taxable wages |
| 44 | oty_qtrly_contributions_chg | Numeric | 13 | OTY change in contributions |
| 45 | oty_qtrly_contributions_pct_chg | Numeric | 8 | OTY % change in contributions |
| 46 | oty_avg_wkly_wage_chg | Numeric | 8 | OTY change in avg weekly wage |
| 47 | oty_avg_wkly_wage_pct_chg | Numeric | 8 | OTY % change in avg weekly wage |
---
## Annual CSV Field Layout
| # | Field Name | Type | Max Len | Description |
|---|-----------|------|---------|-------------|
| 1 | area_fips | Text | 5 | 5-character FIPS code |
| 2 | own_code | Text | 1 | Ownership code |
| 3 | industry_code | Text | 6 | NAICS or SuperSector code |
| 4 | agglvl_code | Text | 2 | Aggregation level code |
| 5 | size_code | Text | 1 | Size code |
| 6 | year | Text | 4 | Year |
| 7 | qtr | Text | 1 | Always `A` for annual |
| 8 | disclosure_code | Text | 1 | `' '`=disclosed; `N`=not disclosed |
| 9 | area_title | Text | 80 | Area name (excluded from singlefile) |
| 10 | own_title | Text | 80 | Ownership description (excluded from singlefile) |
| 11 | industry_title | Text | 80 | Industry description (excluded from singlefile) |
| 12 | agglvl_title | Text | 80 | Aggregation level title (excluded from singlefile) |
| 13 | size_title | Text | 80 | Size class title (excluded from singlefile) |
| 14 | annual_avg_estabs | Numeric | 8 | Annual avg of quarterly establishment counts |
| 15 | annual_avg_emplvl | Numeric | 9 | Annual avg of monthly employment levels |
| 16 | total_annual_wages | Numeric | 15 | Sum of 4 quarterly total wages |
| 17 | taxable_annual_wages | Numeric | 15 | Sum of 4 quarterly taxable wages |
| 18 | annual_contributions | Numeric | 13 | Sum of 4 quarterly UI contributions |
| 19 | annual_avg_wkly_wage | Numeric | 8 | Avg weekly wage based on 12-month employment and total annual wages |
| 20 | avg_annual_pay | Numeric | 8 | Avg annual pay (wages ÷ employment) |
| 21 | lq_disclosure_code | Text | 1 | LQ disclosure code |
| 22 | lq_annual_avg_estabs | Numeric | 8 | LQ of annual avg establishment count vs. U.S. |
| 23 | lq_annual_avg_emplvl | Numeric | 8 | LQ of annual avg employment vs. U.S. |
| 24 | lq_total_annual_wages | Numeric | 8 | LQ of total annual wages vs. U.S. |
| 25 | lq_taxable_annual_wages | Numeric | 8 | LQ of taxable annual wages vs. U.S. |
| 26 | lq_annual_contributions | Numeric | 8 | LQ of annual contributions vs. U.S. |
| 27 | lq_annual_avg_wkly_wage | Numeric | 8 | LQ of annual avg weekly wage vs. U.S. |
| 28 | lq_avg_annual_pay | Numeric | 8 | LQ of avg annual pay vs. U.S. |
| 29 | oty_disclosure_code | Text | 1 | OTY disclosure code |
| 30 | oty_annual_avg_estabs_chg | Numeric | 8 | OTY change in annual avg estabs |
| 31 | oty_annual_avg_estabs_pct_chg | Numeric | 8 | OTY % change in annual avg estabs |
| 32 | oty_annual_avg_emplvl_chg | Numeric | 9 | OTY change in annual avg employment |
| 33 | oty_annual_avg_emplvl_pct_chg | Numeric | 8 | OTY % change in annual avg employment |
| 34 | oty_total_annual_wages_chg | Numeric | 15 | OTY change in total annual wages |
| 35 | oty_total_annual_wages_pct_chg | Numeric | 8 | OTY % change in total annual wages |
| 36 | oty_taxable_annual_wages_chg | Numeric | 15 | OTY change in taxable annual wages |
| 37 | oty_taxable_annual_wages_pct_chg | Numeric | 8 | OTY % change in taxable annual wages |
| 38 | oty_annual_contributions_chg | Numeric | 13 | OTY change in annual contributions |
| 39 | oty_annual_contributions_pct_chg | Numeric | 8 | OTY % change in annual contributions |
| 40 | oty_annual_avg_wkly_wage_chg | Numeric | 8 | OTY change in annual avg weekly wage |
| 41 | oty_annual_avg_wkly_wage_pct_chg | Numeric | 8 | OTY % change in annual avg weekly wage |
| 42 | oty_avg_annual_pay_chg | Numeric | 8 | OTY change in avg annual pay |
| 43 | oty_avg_annual_pay_pct_chg | Numeric | 8 | OTY % change in avg annual pay |
---
## Decode Tables
**own_code values:**
| Code | Ownership |
|------|-----------|
| 0 | Total, all ownerships |
| 1 | Federal government |
| 2 | State government |
| 3 | Local government |
| 4 | International government |
| 5 | Private |
| 8 | Total, all government |
| 9 | Total, all ownerships (same as 0) |
**agglvl_code examples:**
| Code | Level |
|------|-------|
| 10 | U.S., NAICS supersectors |
| 11 | U.S., NAICS sector |
| 12 | U.S., NAICS 3-digit |
| 13 | U.S., NAICS 4-digit |
| 14 | U.S., NAICS 5-digit |
| 15 | U.S., NAICS 6-digit |
| 50 | State, NAICS supersectors |
| 51 | State, NAICS sector |
| 74 | County, NAICS 5-digit |
| 75 | County, NAICS 6-digit |
| 76 | MSA, NAICS supersectors |
**size_code values:**
| Code | Employment size class |
|------|----------------------|
| 0 | All establishment sizes |
| 1 | < 5 employees |
| 2 | 5–9 |
| 3 | 10–19 |
| 4 | 20–49 |
| 5 | 50–99 |
| 6 | 100–249 |
| 7 | 250–499 |
| 8 | 500–999 |
| 9 | 1,000+ |
---
## Download URLs
**By-area quarterly (single year):**
```
https://data.bls.gov/cew/data/files/{YEAR}/csv/{YEAR}_qtrly_by_area.zip
```
**By-industry quarterly:**
```
https://data.bls.gov/cew/data/files/{YEAR}/csv/{YEAR}_qtrly_by_industry.zip
```
**Annual singlefile (all areas, all industries, one row per combo):**
```
https://data.bls.gov/cew/data/files/{YEAR}/csv/{YEAR}_annual_singlefile.zip
```
**QCEW API (individual series):**
```
https://data.bls.gov/cew/apps/data_views/data_views.htm
```