# US Labor Market Monitor (`primeselectai/us-labor-market-demand-monitor`) Actor

Monitor US labor-market demand using official BLS time series. Receive normalized observations, stable IDs, historical changes, footnotes, and refresh-ready output for staffing and workforce analytics.

- **URL**: https://apify.com/primeselectai/us-labor-market-demand-monitor.md
- **Developed by:** [Simon Jessen](https://apify.com/primeselectai) (community)
- **Categories:** Jobs
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## US Labor Market Demand Monitor

Start with the business outcome: identify where labor demand, wages, and worker availability are changing before committing recruiting resources. The output includes stable series IDs, periods, values, MoM and YoY changes, footnotes, retrieval timestamps, and BLS attribution. Configure a predefined indicator or provide explicit BLS series IDs afterward.

### Outcome

Turn official US labor statistics into normalized occupation and regional demand signals with trend changes that support staffing forecasts, pricing, and recruiting-market decisions.

### Use cases

- Use the Actor when you need turn official US labor statistics into normalized occupation and regional demand signals with trend changes that support staffing forecasts, pricing, and recruiting-market decisions.
- Build workflows around instead of scraping copyrighted job-board listings, the Actor provides repeatable labor-market intelligence from BLS time series: occupation and industry demand proxies, regional unemployment trends, wage benchmarks, month-over-month and year-over-year changes, anomaly flags, and stable series-level history.
- Designed for Staffing agencies, recruiting firms, workforce consultants, HR software companies, and labor-market analysts.
- Schedule repeat runs: Users rerun weekly or monthly to refresh benchmark series, detect revisions, compare regions, and monitor occupation or industry demand changes over time.
- Feed normalized dataset records into APIs, spreadsheets, databases, automations, or AI/agent workflows.

### Quick start

1. Open the Actor input form.
2. Set the filters or query relevant to your workflow.
3. Start with a small `maxResults` value.
4. Run the Actor and inspect the default dataset before scheduling larger or recurring jobs.

Example input:

```json
{
  "query": "unemployment rate",
  "seriesIds": [
    "LNS14000000",
    "CES0000000001",
    "CES0500000003"
  ],
  "startYear": "2024",
  "endYear": "2025",
  "maxResults": 10
}
```

### Inputs

- **query** (string, optional) — Human-readable indicator label used to select a predefined BLS series family, such as unemployment rate, total nonfarm employment, average hourly earnings, or labor force participation.
- **seriesIds** (array, optional) — Optional explicit BLS series IDs. If supplied, these take precedence over the predefined query.
- **startYear** (string, optional) — Four-digit first year to retrieve.
- **endYear** (string, optional) — Four-digit final year to retrieve.
- **maxResults** (integer, optional) — Maximum number of normalized observations returned after filtering and enrichment.

### Output example

The example below is taken from the latest validated local live-source sample when available; otherwise it is derived from the bundled dataset schema.

```json
{
  "id": "LNS14000000:2026:M08",
  "seriesId": "LNS14000000",
  "seriesTitle": "Unemployment Rate",
  "year": 2026,
  "period": "M08",
  "periodName": "August",
  "value": 4.1,
  "unit": "percent",
  "monthOverMonthChange": 0.0,
  "yearOverYearChange": -0.2,
  "yearOverYearPercentChange": -4.651163,
  "footnotes": [],
  "retrievedAt": "2026-09-04T14:44:14.268192+00:00",
  "source": "U.S. Bureau of Labor Statistics"
}
```

### Pricing

Store pricing is configured in Apify. The intended primary paid unit is **normalized labor-market observation**. Start with a small result limit while validating your workflow, then scale only when the output and economics fit your use case. The README never hard-codes a price that could drift from the live Store configuration.

### Source and limitations

- Source: U.S. Bureau of Labor Statistics Public Data API.
- Licence/terms: U.S. Government public data; no restrictive end-use control stated in BLS API Terms of Service.
- Reuse condition: BLS states that accessed data should not include controls over end use. Cite BLS and the retrieval date, state that BLS cannot vouch for downstream data or analyses, do not falsely represent or materially misstate BLS content, and do not use the BLS logo without permission. This Actor must sell transformed analysis and normalized indicators rather than implying BLS endorsement.
- Automation condition: Use the unauthenticated Version 1 API within its documented limits: up to 25 series per request, up to 10 years per request, and the published request-rate and daily-query limits. Implement backoff, caching, retries, and source-health checks.
- This is labor-market intelligence rather than a live job-posting scraper, so the product must be positioned around staffing forecasts, benchmarking, and demand monitoring.
- BLS data is published historical or periodic statistical data and may not provide real-time vacancy counts or individual job listings.
- BLS API rate limits and Version 1 query caps constrain large bulk requests; caching and batching are required.
- BLS requires attribution, retrieval dates, accurate representation, and a disclaimer that BLS cannot vouch for downstream analyses.
- Series IDs and metadata can be difficult for end users; a maintained predefined series catalog is essential.

This Actor does not bypass authentication, rate limits, robots/API policies, licensing conditions, or upstream access controls. Missing upstream values are not invented.

### FAQ

**Does this use the approved source contract?**\
Yes. Runtime requests are restricted to the source contract validated by Market Hunter before build.

**Can I schedule repeat runs?**\
Yes, when the source permits automated access. Use conservative schedules and result limits that respect upstream conditions.

**Why can some fields be empty or null?**\
The upstream source may omit fields for particular records. The Actor preserves missing values rather than fabricating data.

### Troubleshooting

- If a narrow query returns no rows, loosen filters and retry with a small result limit.
- If the upstream source returns a rate-limit or temporary server error, retry later instead of increasing request pressure.
- If authentication or source identity is required, verify the protected credential/identity configured for the Actor.
- If the upstream response schema changes, report the failed run so the deterministic mapping can be updated.

### Related Actors

- BLS Wage Benchmark API
- US Unemployment Rate Monitor
- Federal Employment Projection Monitor
- State Labor Market Comparison API

> Store publication remains an explicit manual action. This product is not affiliated with or endorsed by the upstream source unless the Store listing explicitly states otherwise.

# Actor input Schema

## `query` (type: `string`):

Human-readable indicator label used to select a predefined BLS series family, such as unemployment rate, total nonfarm employment, average hourly earnings, or labor force participation.

## `seriesIds` (type: `array`):

Optional explicit BLS series IDs. If supplied, these take precedence over the predefined query.

## `startYear` (type: `string`):

Four-digit first year to retrieve.

## `endYear` (type: `string`):

Four-digit final year to retrieve.

## `maxResults` (type: `integer`):

Maximum number of normalized observations returned after filtering and enrichment.

## Actor input object example

```json
{
  "query": "unemployment rate",
  "seriesIds": [
    "LNS14000000",
    "CES0000000001",
    "CES0500000003"
  ],
  "startYear": "2024",
  "endYear": "2025",
  "maxResults": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runMeta` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "unemployment rate",
    "seriesIds": [
        "LNS14000000",
        "CES0000000001",
        "CES0500000003"
    ],
    "startYear": "2024",
    "endYear": "2025",
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("primeselectai/us-labor-market-demand-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "unemployment rate",
    "seriesIds": [
        "LNS14000000",
        "CES0000000001",
        "CES0500000003",
    ],
    "startYear": "2024",
    "endYear": "2025",
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("primeselectai/us-labor-market-demand-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "unemployment rate",
  "seriesIds": [
    "LNS14000000",
    "CES0000000001",
    "CES0500000003"
  ],
  "startYear": "2024",
  "endYear": "2025",
  "maxResults": 10
}' |
apify call primeselectai/us-labor-market-demand-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,primeselectai/us-labor-market-demand-monitor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/taZ0dWW5UNxJVk9NQ/builds/7ShwjzAxdNadAP3Ye/openapi.json