BLS US Economic Data Search

What does BLS US Economic Data Search do?

BLS US Economic Data Search is an Apify actor that connects directly to the official Bureau of Labor Statistics (BLS) Public Data API v2 and retrieves time series data for US economic indicators. The BLS is the principal federal agency responsible for measuring labor market activity, working conditions, price changes, and productivity in the US economy. It publishes hundreds of data series covering inflation, employment, wages, producer prices, productivity, and more -- data that drives policy decisions, financial analysis, and academic research worldwide.

This actor gives you instant, structured access to that data through a simple configuration interface. Choose from five built-in presets for the most widely tracked indicators -- Consumer Price Index (CPI), unemployment rate, total nonfarm employment, average hourly earnings, and Producer Price Index (PPI) -- or supply your own comma-separated BLS series IDs to query any data the agency publishes. Specify a start year and end year to control the historical range, and optionally provide a free BLS registration key to unlock higher rate limits.

Every data point returned includes the series ID, a human-readable series name, year, period code, period name (e.g., "January"), the raw string value, a parsed numeric value, any footnotes from the BLS, and an extraction timestamp. The output is a flat dataset that can be exported to CSV, Excel, JSON, or piped directly into other Apify actors and integrations.

Why use BLS US Economic Data Search on Apify?

Working with the BLS API directly means writing custom code to handle POST request formatting, JSON body construction, response status checking, nested data extraction, string-to-number conversion, and rate limit management. This actor eliminates all of that development overhead. You configure your inputs through the Apify UI or via JSON, click run, and receive clean, structured data in your dataset within seconds.

Running on Apify also means you can schedule recurring runs -- daily, weekly, or monthly -- to automatically capture new economic releases as they are published. The BLS publishes CPI data mid-month, employment data on the first Friday of each month, and PPI data shortly after. Combined with Apify webhooks and integrations, you can push fresh economic data to Google Sheets, Slack, email, databases, or any API endpoint the moment it arrives.

Because the actor uses minimal compute -- a single API POST request with no browser, no HTML parsing, and no pagination -- runs complete in under 30 seconds and cost almost nothing in platform credits. It is an ideal building block for economic monitoring pipelines, financial dashboards, academic research workflows, and automated reporting systems.

The actor is especially valuable for economists, financial analysts, data scientists, journalists, academic researchers, policy analysts, and anyone who needs reliable, programmatic access to official US economic statistics without the overhead of building and maintaining custom API integration code.

Key features

• Five built-in presets for the most requested economic indicators: CPI inflation, unemployment rate, nonfarm employment, average hourly earnings, and PPI
• Custom series support -- enter any valid BLS series ID (or multiple IDs separated by commas) to pull exactly the data you need from hundreds of available series
• Flexible year range -- specify start and end years to control how much historical data is returned, up to a 20-year window without an API key
• No API key required -- works immediately with no registration using the BLS public API, though a free key unlocks higher rate limits
• Clean, flat output -- each data point is a separate record with series metadata, period details, numeric value, footnotes, and a timestamp, ready for CSV export or JSON processing
• Human-readable series names -- the actor maps common series IDs to descriptive names so output is immediately understandable without cross-referencing BLS documentation
• Automatic invalid data filtering -- data points marked as unavailable by the BLS (value "-") are automatically excluded from the output
• Parsed numeric values -- string values from the API are automatically converted to proper numbers for immediate computation and analysis
• Footnote consolidation -- multiple footnote entries per data point are joined into a single readable string

How to use BLS US Economic Data Search

1. Navigate to the BLS US Economic Data Search actor page on Apify and click Try for free.
2. In the input form, select a Data Preset from the dropdown (CPI, Unemployment, Employment, Wages, PPI) or choose "Custom Series IDs" and enter your own series IDs.
3. Set the Start Year and End Year for the data range you want.
4. Optionally paste your free BLS API Key if you need higher rate limits.
5. Click Start and wait a few seconds for the run to complete.
6. Open the Dataset tab to view, download, or export your results in JSON, CSV, Excel, or other formats.

You can also call this actor programmatically via the Apify API or integrate it into your workflow using the Apify JavaScript or Python client.

Example: Track CPI inflation with default settings

The simplest possible input -- just use the defaults to get CPI data for the last 5 years:

{}

Example: Track CPI inflation over the last 5 years

{
    "preset": "cpi",
    "startYear": 2020,
    "endYear": 2025
}

Example: Get unemployment rate data for a decade

{
    "preset": "unemployment",
    "startYear": 2015,
    "endYear": 2025
}

Example: Query multiple custom series

{
    "preset": "custom",
    "customSeriesIds": "CUUR0000SA0,LNS14000000,CES0500000003",
    "startYear": 2022,
    "endYear": 2025,
    "apiKey": "your_bls_registration_key_here"
}

Example: Pull PPI data for a single year

{
    "preset": "ppi",
    "startYear": 2024,
    "endYear": 2024
}

Example: API call via cURL

curl "https://api.apify.com/v2/acts/ryanclinton~bls-economic-data/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -d '{"preset": "wages", "startYear": 2020, "endYear": 2025}'

Example: Python client integration

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "preset": "custom",
    "customSeriesIds": "CUUR0000SA0,CUUR0000SA0L1E",
    "startYear": 2020,
    "endYear": 2025,
}

run = client.actor("ryanclinton/bls-economic-data").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['seriesName']}: {item['periodName']} {item['year']} = {item['numericValue']}")

Input parameters

Parameter	Type	Required	Default	Description
preset	string (select)	No	cpi	Quick preset for common economic indicators. Options: CPI, Unemployment Rate, Total Nonfarm Employment, Average Hourly Earnings, PPI, or Custom Series IDs.
customSeriesIds	string	No	--	Comma-separated BLS series IDs (e.g., CUUR0000SA0,LNS14000000). Only used when preset is set to "Custom Series IDs". Find series IDs at data.bls.gov.
startYear	integer	No	2020	Start year for the data range.
endYear	integer	No	2025	End year for the data range.
apiKey	string	No	--	Optional BLS registration key for higher request limits. Get one free at data.bls.gov/registrationEngine.

Preset reference

The actor includes five built-in presets that map to specific BLS series IDs. This table shows exactly which series each preset queries.

Preset	Series ID	Series Name	Description
cpi	CUUR0000SA0	CPI - All Urban Consumers (All Items)	Tracks changes in the price level of a market basket of consumer goods and services. The primary measure of US inflation.
unemployment	LNS14000000	Unemployment Rate (Seasonally Adjusted)	The percentage of the civilian labor force that is jobless, actively seeking work, and available to work.
employment	CES0000000001	Total Nonfarm Employment (Thousands)	The total number of paid US workers excluding farm employees, government workers, and nonprofit organization employees.
wages	CES0500000003	Average Hourly Earnings - All Private	Average hourly earnings of all employees on private nonfarm payrolls, seasonally adjusted.
ppi	WPSFD4	PPI - All Commodities	Measures average changes in selling prices received by domestic producers for their output. A leading indicator of consumer inflation.

The actor also recognizes several additional series IDs with built-in human-readable names: LNS11000000 (Civilian Labor Force Level), LNS12000000 (Civilian Employment Level), and CUUR0000SA0L1E (CPI - All Items Less Food and Energy). For any unrecognized series ID, the raw ID is used as the series name.

Output example

Each run produces a dataset of data point records. Here are realistic examples of the output for different presets.

Unemployment rate output

[
    {
        "seriesId": "LNS14000000",
        "seriesName": "Unemployment Rate (Seasonally Adjusted)",
        "year": "2025",
        "period": "M01",
        "periodName": "January",
        "value": "4.0",
        "numericValue": 4.0,
        "footnote": null,
        "extractedAt": "2025-03-15T12:34:56.789Z"
    },
    {
        "seriesId": "LNS14000000",
        "seriesName": "Unemployment Rate (Seasonally Adjusted)",
        "year": "2024",
        "period": "M12",
        "periodName": "December",
        "value": "4.1",
        "numericValue": 4.1,
        "footnote": null,
        "extractedAt": "2025-03-15T12:34:56.790Z"
    },
    {
        "seriesId": "LNS14000000",
        "seriesName": "Unemployment Rate (Seasonally Adjusted)",
        "year": "2024",
        "period": "M06",
        "periodName": "June",
        "value": "4.1",
        "numericValue": 4.1,
        "footnote": null,
        "extractedAt": "2025-03-15T12:34:56.791Z"
    },
    {
        "seriesId": "LNS14000000",
        "seriesName": "Unemployment Rate (Seasonally Adjusted)",
        "year": "2023",
        "period": "M01",
        "periodName": "January",
        "value": "3.4",
        "numericValue": 3.4,
        "footnote": null,
        "extractedAt": "2025-03-15T12:34:56.792Z"
    }
]

CPI output

{
    "seriesId": "CUUR0000SA0",
    "seriesName": "CPI - All Urban Consumers (All Items)",
    "year": "2024",
    "period": "M11",
    "periodName": "November",
    "value": "317.338",
    "numericValue": 317.338,
    "footnote": null,
    "extractedAt": "2025-03-15T12:34:56.800Z"
}

Output fields reference

Field	Type	Description
seriesId	string	The BLS series identifier (e.g., LNS14000000). Use this to cross-reference with BLS documentation or for subsequent queries.
seriesName	string	Human-readable name of the series (e.g., "Unemployment Rate (Seasonally Adjusted)"). Resolved from a built-in lookup table; falls back to the raw series ID for unrecognized series.
year	string	Four-digit year of the data point (e.g., "2024").
period	string	BLS period code. Monthly data uses M01 through M12. Annual averages use M13. Quarterly data uses Q01 through Q05.
periodName	string	Human-readable period name (e.g., "January", "February", "Annual").
value	string	Raw value as returned by the BLS API, preserved as a string to maintain exact precision.
numericValue	number or null	Parsed numeric value for computation and analysis. Null if the raw value cannot be parsed as a number.
footnote	string or null	Any footnotes attached to the data point by the BLS, joined with semicolons if multiple exist. Null if no footnotes are present.
extractedAt	string	ISO 8601 timestamp of when the data was extracted by this actor.

Technical details

Understanding how this actor works under the hood can help you get the most out of it and troubleshoot any issues.

POST-only API architecture

Unlike most REST APIs that use GET requests with query parameters, the BLS Public Data API v2 exclusively uses POST requests with a JSON body. The actor constructs a single POST request to https://api.bls.gov/publicAPI/v2/timeseries/data/ with a JSON payload containing the following fields:

• seriesid -- an array of BLS series ID strings
• startyear -- the start year as a string
• endyear -- the end year as a string
• registrationkey -- the optional API key (included only when provided)

This means all data for all requested series and the full year range is returned in a single API response -- there is no pagination to manage. The actor makes exactly one HTTP request per run regardless of how many series or years you request.

Preset resolution system

When you select a preset (e.g., "unemployment"), the actor resolves it to the corresponding BLS series ID (LNS14000000) from its internal mapping table. When you choose "Custom Series IDs", the actor parses your comma-separated string, trims whitespace, and filters empty entries. In both cases, the resolved array of series IDs is passed to the API request.

String-to-number parsing

The BLS API returns all data values as strings (e.g., "246.819" for a CPI value or "4.1" for an unemployment rate). The actor automatically parses each string value into a proper JavaScript number using parseFloat and stores it in the numericValue field. If parsing fails (which can happen with special markers), numericValue is set to null. The original string value is always preserved in the value field.

Series name lookup

The actor maintains an internal mapping of common BLS series IDs to human-readable names. When transforming the API response, each series ID is looked up in this table. Recognized series get descriptive names like "CPI - All Urban Consumers (All Items)". Unrecognized series IDs (which you may encounter when using custom IDs) are used as-is for the seriesName field.

Footnote consolidation

BLS data points can have multiple footnotes, each containing a code and text description. The actor filters out empty footnotes, extracts the text from each remaining footnote, and joins them with semicolons into a single string. If no footnotes exist, the field is set to null.

Response status validation

After receiving the API response, the actor checks the status field. The BLS API returns REQUEST_SUCCEEDED for successful queries. If the status indicates failure -- such as when you exceed the daily request limit, provide an invalid series ID, or request a year range beyond the allowed maximum -- the actor logs detailed error messages (including all messages from the BLS response) and pushes the error information to the dataset so you can diagnose the issue without checking logs.

Invalid value filtering

The BLS uses a dash character ("-") to indicate data points where no value is available for that period. The actor automatically filters these out of the output so your dataset contains only valid, usable data points. This ensures every record in your dataset has a meaningful value that can be used in calculations and analysis.

BLS API key limits comparison

The BLS API works without any registration, but a free API key significantly improves your limits.

Feature	Without API Key	With Free API Key
Daily request limit	25 requests	500 requests
Maximum year range	20 years	10 years
Maximum series per request	25 series	50 series
Catalog data	Not available	Available
Calculations	Not available	Available
Annual averages	Not available	Available
Registration cost	Free	Free

Note the counterintuitive year range limit: registered users get a smaller maximum year range (10 years) than unregistered users (20 years). If you need more than 10 years of data with a registered key, you will need to make multiple runs with different year ranges.

Register for a free key at data.bls.gov/registrationEngine. Registration takes approximately 30 seconds.

How much does it cost to use?

BLS US Economic Data Search is extremely lightweight. It makes a single POST request to the BLS API, transforms the response, and outputs the results. A typical run uses approximately 128 MB of memory and completes in under 30 seconds.

Estimated cost per run: Under $0.005 (less than half a cent) in Apify platform credits.

Apify offers a free tier that includes $5 of monthly platform credits -- enough to run this actor hundreds of times per month at no cost. For most users tracking a few economic indicators on a weekly or monthly schedule, the free tier will be more than sufficient.

The BLS API itself is completely free. No charges are applied by the Bureau of Labor Statistics regardless of whether you use a registration key or not.

Scenario	Memory	Duration	Estimated Cost
Single preset, 5-year range	128 MB	~10 seconds	~$0.001
Single preset, 20-year range	128 MB	~15 seconds	~$0.002
Multiple custom series, 5-year range	128 MB	~15 seconds	~$0.002
Scheduled daily run (30 runs/month)	128 MB	~10 seconds each	~$0.03/month

Common use cases

• Inflation tracking -- monitor CPI trends over time to understand purchasing power changes, inform pricing strategies, or support economic reporting. Pull monthly CPI data and compare year-over-year changes.
• Labor market analysis -- track unemployment rates, nonfarm payrolls, and labor force participation to assess employment conditions. Combine employment and wage data for a comprehensive labor market picture.
• Wage growth monitoring -- follow average hourly earnings trends to evaluate compensation dynamics across the private sector. Compare wage growth against CPI inflation to calculate real wage changes.
• Producer price forecasting -- use PPI data as a leading indicator of consumer inflation. Rising producer prices often signal future CPI increases, making PPI valuable for forward-looking analysis.
• Academic research -- access decades of official government statistics for economic research papers, dissertations, and coursework. The structured output integrates easily with statistical software and data analysis tools.
• Financial dashboards -- schedule recurring runs to feed live economic indicators into business intelligence tools, Google Sheets dashboards, or custom reporting applications.
• Journalism and reporting -- quickly pull official economic statistics for news articles, fact-checking, and data-driven stories without navigating the BLS website or writing custom scripts.
• Policy analysis -- compare economic indicators across time periods to evaluate the impact of policy changes on employment, inflation, and wages.

Tips for best results

• Use presets for common indicators. The built-in presets cover the five most popular BLS data series. If you just need CPI or unemployment data, selecting a preset is the fastest way to get started.
• Register for a free BLS API key. Even though the actor works without one, a registration key increases your daily limit from 25 to 500 requests and unlocks additional features like annual averages and calculations. Sign up at data.bls.gov/registrationEngine.
• Mind the year range limits. Without an API key, the BLS supports up to a 20-year range per request. With a key, the maximum drops to 10 years. Stay within these limits to avoid API errors.
• Find additional series IDs on the BLS website. Visit data.bls.gov to browse hundreds of available series covering regional employment, industry-specific prices, import/export prices, productivity, and more. Each series page displays its ID in the URL or header.
• Combine multiple series in a single run. Use the "Custom Series IDs" option to query several series separated by commas. This is more efficient than running the actor multiple times and stays within the per-request series limit (25 without key, 50 with key).
• Schedule recurring runs. Set up a monthly schedule on Apify to automatically capture new BLS data releases. CPI is typically released mid-month, employment data comes out on the first Friday, and PPI follows shortly after.
• Use the numericValue field for analysis. While the raw value field preserves the exact string from the BLS, the numericValue field is already parsed as a number, making it ready for calculations, charting, and aggregation without additional processing.
• Check footnotes for data quality context. Some data points carry footnotes from the BLS that explain revisions, methodology changes, or preliminary status. The footnote field captures this context so you can assess data quality.
• Export to CSV for spreadsheet analysis. The flat output structure (one row per data point) is designed for easy import into Excel, Google Sheets, or any statistical software. Use the Apify dataset export feature to download CSV files directly.
• Compare CPI and PPI together. Query both indices in a single custom run to analyze the relationship between producer and consumer prices. Rising PPI often foreshadows CPI increases.

FAQ

Do I need a BLS API key to use this actor? No. The actor works without any API key using the BLS public API v2. However, registering for a free key at data.bls.gov/registrationEngine increases your daily request limit from 25 to 500 and unlocks additional capabilities.

What economic data can I access? Any time series published by the Bureau of Labor Statistics. The built-in presets cover CPI (inflation), unemployment rate, nonfarm employment, average hourly earnings, and PPI. Using custom series IDs, you can access hundreds of additional data series including regional employment data, industry-specific price indices, import/export prices, productivity statistics, and more.

How often is BLS data updated? Most major indicators are updated monthly. CPI is typically released in the second or third week of each month. Employment data (nonfarm payrolls) is released on the first Friday of each month. PPI is released mid-month. Some series are updated quarterly or annually. Schedule your actor runs accordingly to capture fresh data.

Can I query multiple series at once? Yes. Select the "Custom Series IDs" preset and enter multiple series IDs separated by commas. The BLS API supports up to 25 series per request without an API key and 50 series with a registered key. All data points for all series will appear in a single output dataset.

What is a BLS series ID and where do I find one? A series ID is a unique alphanumeric code that identifies a specific BLS data series. For example, CUUR0000SA0 is the CPI for All Urban Consumers and LNS14000000 is the seasonally adjusted unemployment rate. You can find series IDs by browsing data.bls.gov, where each data series page shows its ID. The BLS also provides a series ID finder that explains the structure of IDs for each survey program.

Why does the year range limit decrease with an API key? This is a quirk of the BLS API design. Unregistered users can request up to 20 years of data per call, while registered users are limited to 10 years. The tradeoff is that registered users get access to 500 daily requests (vs. 25), up to 50 series per request (vs. 25), and additional features like calculations and annual averages. If you need more than 10 years with a key, make separate runs for different year ranges.

What formats can I export the data in? Apify datasets support export in JSON, CSV, Excel, XML, and RSS formats. You can also access results programmatically via the Apify API or connect them directly to Google Sheets, Slack, email, and other integrations through Apify's built-in integration options.

What happens if the BLS API returns an error? The actor checks the API response status and logs detailed error messages. Common issues include exceeding the daily request limit, requesting a year range beyond the allowed maximum, or specifying invalid series IDs. Error details are logged and pushed to the dataset so you can diagnose the problem.

What does the period code mean? The period field uses BLS conventions: M01 through M12 represent January through December for monthly data. M13 represents an annual average (available only with a registered API key). Quarterly series use Q01 through Q05. The periodName field provides the human-readable equivalent so you do not need to decode the period codes yourself.

Can I get seasonally adjusted vs. non-adjusted data? Yes, but it depends on the series ID you query. Different series IDs represent different seasonal adjustment variants. For example, LNS14000000 is the seasonally adjusted unemployment rate, while LNU04000000 is the non-adjusted version. Check data.bls.gov to find the specific series ID for the adjustment variant you need.

How does this differ from the FRED Economic Data Search actor? While both actors provide US economic data, they connect to different sources. This actor pulls directly from the BLS, which is the primary source for labor market, price, and productivity data. The FRED actor connects to the Federal Reserve Bank of St. Louis database, which aggregates data from the BLS and many other sources (840,000+ series). Use this BLS actor when you specifically need BLS data at the source; use FRED for a broader range of economic indicators including GDP, interest rates, money supply, and financial market data.

Is there a delay between BLS publishing data and this actor being able to retrieve it? No. The actor queries the BLS API in real time. As soon as the BLS publishes new data points to their API, this actor can retrieve them. There is no caching or delay on the actor side.

Integrations and related actors

BLS US Economic Data Search works seamlessly with the Apify platform ecosystem. Connect it to:

• Google Sheets -- automatically push new economic data to a spreadsheet on each run for dashboards and reporting
• Slack / Email -- get notifications when new BLS data is available using Apify webhooks
• Zapier / Make -- trigger downstream workflows whenever the actor finishes a run
• Apify API -- call the actor programmatically from any language using REST endpoints or the official JavaScript/Python clients
• Databases -- pipe structured output directly into PostgreSQL, MySQL, MongoDB, or any database through webhook integrations
• Apify Schedules -- set up automated recurring runs (daily, weekly, monthly) to capture new BLS data releases as they are published
• Other Apify actors -- chain this actor with data transformation or notification actors to build complete economic data pipelines

Related actors from the ryanclinton Apify Store

• FRED Economic Data Search -- access the Federal Reserve Economic Data (FRED) database for 840,000+ US and international economic time series including GDP, interest rates, money supply, and financial market data. The broadest single source of US economic statistics.
• World Bank Development Indicators -- query the World Bank API for global development indicators across 200+ countries, including GDP, population, trade, health, and education metrics. Ideal for international comparisons alongside BLS domestic data.
• IMF Economic Data -- search International Monetary Fund datasets for global macroeconomic statistics, fiscal indicators, and financial data spanning IMF member countries.
• OECD Economic Statistics -- search OECD statistical datasets for economic indicators across member countries, covering employment, trade, finance, and social metrics. Provides international context for BLS US-centric data.