# US Port Container Throughput Statistics Scraper (`jungle_synthesizer/us-port-container-throughput-statistics-scraper`) Actor

Monthly and annual TEU container throughput for major US port authorities, normalized into one schema.

- **URL**: https://apify.com/jungle\_synthesizer/us-port-container-throughput-statistics-scraper.md
- **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community)
- **Categories:** Business, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 record scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 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

```json
{
  "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.

# Actor input Schema

## `sp_intended_usage` (type: `string`):

What will this data feed? E.g. lead lists, KYB checks, price tracking.

## `sp_improvement_suggestions` (type: `string`):

Provide any feedback or suggestions for improvements.

## `sp_contact` (type: `string`):

We'll personally help with your use case. No spam.

## `maxItems` (type: `integer`):

Maximum number of throughput records to save across all selected ports.

## `ports` (type: `array`):

US port authorities to scrape. Defaults to all seven currently supported.

## `includeHistory` (type: `boolean`):

Also fetch Port of Oakland's full 1998-2023 monthly TEU archive (XLSX) in addition to current-period data. One-time large fetch (~300+ rows) — leave off for routine monthly refreshes.

## Actor input object example

```json
{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "maxItems": 800,
  "ports": [
    "USLAX",
    "USOAK",
    "USHOU",
    "USCHS",
    "USMIA",
    "USFLL",
    "USSAN"
  ],
  "includeHistory": false
}
```

# Actor output Schema

## `results` (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 = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "maxItems": 800,
    "ports": [
        "USLAX",
        "USOAK",
        "USHOU",
        "USCHS",
        "USMIA",
        "USFLL",
        "USSAN"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jungle_synthesizer/us-port-container-throughput-statistics-scraper").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 = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "maxItems": 800,
    "ports": [
        "USLAX",
        "USOAK",
        "USHOU",
        "USCHS",
        "USMIA",
        "USFLL",
        "USSAN",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("jungle_synthesizer/us-port-container-throughput-statistics-scraper").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 '{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "maxItems": 800,
  "ports": [
    "USLAX",
    "USOAK",
    "USHOU",
    "USCHS",
    "USMIA",
    "USFLL",
    "USSAN"
  ]
}' |
apify call jungle_synthesizer/us-port-container-throughput-statistics-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jungle_synthesizer/us-port-container-throughput-statistics-scraper"
        }
    }
}

```

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/a0VasWmIAjVkj7itb/builds/EHYilJTVni8Xl2iYX/openapi.json