STB Weekly Freight Rail Service Change Monitor

An Apify Actor that monitors week-over-week changes in Class I railroad service performance metrics from the Surface Transportation Board.

How It Works

1. Discovery — Scrapes the STB Rail Service Data page to find the latest EP724 Consolidated Data workbook URL
2. Download — Fetches the XLSX directly (no browser needed)
3. Validation — Verifies workbook structure: 6 dimension headers, ≥1000 data rows, ≥8 date columns
4. Diffing — Compares the newest two weekly columns, computes absolute delta and percent change, carries 4-week trailing history
5. Filtering — Applies user-configured railroad, measure, threshold, and interpretation filters
6. Output — Writes bounded, provenance-rich change records to the default dataset

Quick Start

# Install
npm install

# Run locally
apify run

# With custom input
apify run --input='{"railroads":["BNSF"],"measureContains":"Speed","minPercentChange":5,"maxResults":50}'

# Run tests
npm test

Input Parameters

Parameter	Type	Default	Description
railroads	string[]	[]	Filter by railroad name (substring match). Empty = all.
measureContains	string	""	Case-insensitive filter on measure column.
minAbsoluteChange	integer	0	Min absolute delta. 0 = disabled.
minPercentChange	number	0	Min absolute percent change. 0 = disabled.
interpretations	string[]	[]	improvement, warning, neutral. Empty = all.
maxResults	integer	200	Max records (1–2000).

Threshold logic: Records meeting either minAbsoluteChange or minPercentChange are included (OR logic). Setting both to 0 returns all records.

Output Fields

Each dataset item:

Field	Type	Description
recordKey	string	Stable metric key plus the current reporting period
metricId	string	Stable SHA-256 hash from all six workbook dimension fields
railroad	string	Class I railroad (e.g. BNSF, UP, CSX, NS)
measure	string	Performance category
variable / subVariable	string	Specific metric breakdown
currentValue	number	Latest week's value
previousValue	number	Prior week's value
absoluteDelta	number	Current − previous
percentChange	number	(delta / previous) × 100, null if previous was 0
movement	string	increased or decreased
interpretation	string	improvement, warning, or neutral
interpretationLabel	string	Conservative human-readable label
history	object[]	4-week trailing history: [{period, value}]
currentPeriod	string	Latest data period
previousPeriod	string	Prior data period
units	string	Normalized unit inferred from the official measure label
sourceUrl	string	Direct XLSX URL
sourcePageUrl	string	Official STB rail-service archive page
retrievedAt	string	ISO timestamp of retrieval

Directional Interpretation

Metric Direction	Increase	Decrease
Train Speed	✅ Improvement	⚠️ Warning
Dwell Time	⚠️ Warning	✅ Improvement
Cars Held on Line	⚠️ Warning	✅ Improvement
Trains Held	⚠️ Warning	✅ Improvement
Past-Due Orders	⚠️ Warning	✅ Improvement
All other metrics	Neutral	Neutral

Note: These are deliberately narrow, naming-based classifications. They do not establish causality or predict service. All other measures remain neutral.

Disclaimer

This data is sourced from official Surface Transportation Board (STB) reports. Values are as reported by Class I railroads and may be subject to revision. This is not a prediction, operational guarantee, or investment advice. Directional classifications are heuristic approximations based on metric naming conventions and should not be relied upon for safety-critical decisions.

Tech Stack

• Runtime: Node.js 22
• SDK: apify v3
• Parsing: bounded XLSX ZIP/XML extraction with fflate
• HTTP: Node.js built-in fetch
• Testing: node:test (built-in, zero additional dependencies)
• Container: node:22-slim (no browser or Playwright)

Source and reuse

The Actor transforms weekly public data published by the U.S. Surface Transportation Board. It preserves the official archive and workbook URLs on every record. It does not use an STB seal or imply government endorsement.