US Port Container Throughput Statistics Scraper

Monthly and annual TEU (twenty-foot equivalent unit) container throughput for seven major US port authorities, normalized into one consistent schema. There is no machine-readable national feed for US port throughput — every port authority publishes its own periodic statistics page in its own format, so tracking the industry means visiting a different agency site every month. This actor does that for you and returns one clean row per port/period.

What it does

For each selected port, the actor visits that authority's own published statistics page or document (an HTML table, PDF report, or spreadsheet, depending on the source) and extracts loaded/empty import and export TEU volumes, computes totals, and captures the source's own year-over-year comparison figures where published. Records are tagged with the reporting period (monthly, annual, calendar_ytd, or fiscal_ytd) so mixed cadences across ports can be reconciled.

Ports covered

Port	UN/LOCODE	State	Granularity
Port of Los Angeles	USLAX	CA	Monthly, calendar-YTD, and annual container figures, plus separate annual automobile and breakbulk cargo tables
Port Houston	USHOU	TX	Monthly and calendar-YTD
Port of Oakland	USOAK	CA	Monthly (2022–present); optional full historical backfill back to 1998
Port of Charleston (SC Ports Authority)	USCHS	SC	Monthly, calendar-YTD, and fiscal-YTD (SC's fiscal year runs July–June)
PortMiami	USMIA	FL	Annual only (this source publishes no monthly breakdown)
Port Everglades	USFLL	FL	Fiscal-year annual figures (Oct–Sep)
Port of San Diego	USSAN	CA	Monthly

Five other US ports (Long Beach, NY/NJ, Savannah, Norfolk/Virginia, Seattle-Tacoma) are not yet covered — each publishes throughput data in a shape (JS-rendered dashboard, narrative press releases, or no public statistics page at all) that needs different tooling than the seven above.

Input

Field	Type	Description	Default
ports	array	Which ports to scrape. See UN/LOCODE column above.	all 7
includeHistory	boolean	Also fetch Port of Oakland's full 1998–2023 monthly archive. A large one-time fetch (~300 extra rows) — leave off for routine refreshes.	false
maxItems	integer	Maximum number of records to save across all selected ports.	800

Output

Field	Description
port_name	Port name, e.g. "Port of Los Angeles"
port_authority	Publishing agency, e.g. "South Carolina Ports Authority"
unlocode	UN/LOCODE for the port, e.g. "USLAX"
state	US state abbreviation
cargo_class	container | automobile | breakbulk
period_type	monthly | annual | fiscal_ytd | calendar_ytd
period_start / period_end	ISO-8601 dates bounding the reporting period
year / month	Calendar or fiscal year, and month number (null for annual/YTD rows)
loaded_imports_teu / loaded_exports_teu	Loaded (full) container volume, where published
total_loaded_teu	Loaded imports + loaded exports
empty_imports_teu / empty_exports_teu	Empty container volume, where published
total_empty_teu	Empty imports + empty exports
total_teu	Total volume for the period
prior_year_total_teu	Same period, prior year — as published by the source
change_teu / change_pct	Year-over-year change, computed or as published by the source
units	TEU | units | short_tons — the automobile and breakbulk tables are not TEU-denominated
vessel_calls	Vessel call count for the period, where published
source_url	The specific page or document this row came from
source_format	html_table | pdf | xlsx
published_at	Date the source published this period's figures, where stated
scraped_at	ISO-8601 timestamp when this row was scraped

Not every field is populated for every port — sources vary in what they publish. A null means the source doesn't report that figure for that period, not a scraping failure.

Example

{
  "ports": ["USLAX", "USOAK", "USHOU"],
  "maxItems": 200
}

Returns current-period throughput rows for the ports of Los Angeles, Oakland, and Houston.

Notes

• Automobile and breakbulk statistics are only published as a separate series by Port of Los Angeles; every other port in this list reports container cargo only.
• total_teu figures reflect exactly what each source publishes and are not cross-normalized for calendar vs. fiscal year — check period_type before comparing two ports for the same nominal month.
• PortMiami and Port Everglades publish annual figures only; there is no monthly cadence to request for those two ports.