Tutorial: BLS (Bureau of Labor Statistics)

Economics

Data source: Bureau of Labor Statistics

Overview

BLS (Bureau of Labor Statistics) wraps Bureau of Labor Statistics, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-bls": {
      "url": "https://context.gnist.ai/mcp/bls/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_series`

Get time series data from the Bureau of Labor Statistics. BLS publishes official US government data on employment, unemployment, consumer prices (CPI), producer prices (PPI), productivity, wages, and occupational statistics. This tool fetches observations when you know the series ID. Common series IDs: - LNS14000000 — Unemployment Rate (monthly, seasonally adjusted) - CES0000000001 — Total Nonfarm Payrolls (monthly, seasonally adjusted) - CUUR0000SA0 — CPI-U All Items (monthly, not seasonally adjusted) - CUSR0000SA0 — CPI-U All Items (monthly, seasonally adjusted) - CUUR0000SA0L1E — CPI-U Core (less food and energy) - WPU00000000 — PPI All Commodities - CES0500000003 — Average Hourly Earnings, Total Private - PRS85006092 — Nonfarm Business Labor Productivity Use get_popular_series() to browse curated series by category, or check https://data.bls.gov/dataQuery/find for the full BLS series catalog. Args: series_id: BLS series identifier (e.g. "CUUR0000SA0", "LNS14000000"). start_year: Start year (YYYY). If omitted, BLS returns the latest 3 years (10 years without API key). end_year: End year (YYYY). If omitted, fetches to the latest available. calculations: Include net changes and percent changes (1, 3, 6, 12 month). Requires API key. annual_averages: Include annual average values alongside monthly data. Requires API key. Returns: series_id, observation_count, and observations list with year, period, period_name, value, and optional latest flag and calculations.

Parameter	Type	Required	Description
`series_id`	string	required	BLS series identifier (e.g. "CUUR0000SA0", "LNS14000000").
`start_year`	any	optional	Start year (YYYY). If omitted, BLS returns the latest 3 years (10 years without API key).
`end_year`	any	optional	End year (YYYY). If omitted, fetches to the latest available.
`calculations`	boolean	optional	Include net changes and percent changes (1, 3, 6, 12 month). Requires API key. (default: `False`)
`annual_averages`	boolean	optional	Include annual average values alongside monthly data. Requires API key. (default: `False`)

curl -X POST "https://context.gnist.ai/mcp/bls/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_series", "arguments": {"series_id": "CUUR0000SA0"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bls/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_id': 'CUUR0000SA0'}, 'name': 'get_series'}},
)
print(resp.json())

`get_latest`

Get the most recent observation for a BLS series. Convenience wrapper that fetches a series and returns only the latest data point. Useful for quick lookups like "what is the current unemployment rate?" or "what is the latest CPI reading?". Args: series_id: BLS series identifier (e.g. "LNS14000000" for unemployment rate). Returns: series_id, year, period, period_name, and value of the most recent observation.

Parameter	Type	Required	Description
`series_id`	string	required	BLS series identifier (e.g. "LNS14000000" for unemployment rate).

curl -X POST "https://context.gnist.ai/mcp/bls/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_latest", "arguments": {"series_id": "LNS14000000"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bls/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_id': 'LNS14000000'}, 'name': 'get_latest'}},
)
print(resp.json())

`get_multiple_series`

Fetch multiple BLS series in a single request. Retrieves data for up to 50 series at once (25 without API key). Useful for comparing indicators side by side, e.g. unemployment rate alongside CPI and nonfarm payrolls. Args: series_ids: List of BLS series IDs (max 50 with key, 25 without). start_year: Start year (YYYY). end_year: End year (YYYY). Returns: count and list of series, each with series_id, observation_count, and observations.

Parameter	Type	Required	Description
`series_ids`	list[string]	required	List of BLS series IDs (max 50 with key, 25 without).
`start_year`	any	optional	Start year (YYYY).
`end_year`	any	optional	End year (YYYY).

curl -X POST "https://context.gnist.ai/mcp/bls/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_multiple_series", "arguments": {"series_ids": ["example"]}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bls/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'series_ids': ['example']},
            'name': 'get_multiple_series'}},
)
print(resp.json())

`get_popular_series`

Browse curated popular BLS series organized by category. Returns well-known, commonly-referenced BLS series IDs with titles. Use this when you need to find the right series ID for employment, prices, productivity, or wages data. Available categories: - employment — unemployment rate, nonfarm payrolls, labor force, JOLTS - prices — CPI-U (all items, core, food, shelter, gasoline), PPI - productivity — labor productivity, unit labor costs, real compensation - wages — employment cost index, average hourly earnings, median weekly earnings Args: category: Filter to a specific category. If omitted, returns all categories. Returns: If category specified: category name and list of series (series_id, title). If omitted: list of category names and all series grouped by category.

Parameter	Type	Required	Description
`category`	any	optional	Filter to a specific category. If omitted, returns all categories.

curl -X POST "https://context.gnist.ai/mcp/bls/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_popular_series", "arguments": {"category": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bls/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'category': 'example'}, 'name': 'get_popular_series'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/bls/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/bls/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

FAQ

What data does BLS (Bureau of Labor Statistics) provide?

U.S. labor statistics including employment, CPI, wages, and unemployment data. It exposes 5 tools: get_series, get_latest, get_multiple_series, get_popular_series, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the BLS (Bureau of Labor Statistics) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.