Import/Export Trade Flow & Supply-Chain Concentration Intelligence

This actor does not scrape bills of lading or shipment manifests with company names. That's a deliberate scope decision, made after the Phase 1 research the build PRD required before any scraping code got written — read this section before deciding whether this actor fits what you need.

Phase 1 research: why this isn't a shipment-manifest scraper

The original brief was company-level bill-of-lading intelligence — "who imports what from whom," the ImportYeti/Panjiva/ImportGenius product category. Before writing any scraping logic, per the PRD's own explicit Phase 1 instruction, this was actually researched:

• Company-level manifest data has no legitimate free public source. The products that sell this (Panjiva, ImportGenius, ImportYeti, Datamyne) are built on ocean bill-of-lading data licensed in bulk directly from US Customs and Border Protection through a formal commercial arrangement — not a free API or an open dataset. Scraping their websites (including "free preview" tiers meant to entice paid signups) would mean extracting a competitor's licensed, proprietary database through their paywall, which is a real ToS and legal exposure question, not just a technical scraping challenge. That line wasn't crossed.
• What genuinely is free and public: official government trade statistics — at country level, not company level. UN Comtrade publishes real bilateral trade data (which country traded how much of which HS code with which other country) via a public API, confirmed live and used here. US Census Bureau and USITC DataWeb have equivalent APIs gated behind a free registration (not integrated in this build; UN Comtrade's keyless tier already covers the core need without asking for a signup).
• The PRD itself pre-authorizes exactly this fallback: "If line-item detail proves inaccessible, fall back to aggregate trade-statistics data ... as a v1 scope" and "if scope was reduced to aggregate statistics only, adjust output schema accordingly and be transparent about it." This actor does both — the output schema below has nothing in common with the PRD's original shipper/consignee/bill-of-lading fields, because that data was never legitimately reachable to begin with.

What you get instead: the same underlying buyer question the PRD cared about — "how exposed am I to a single supplier country" — answered with real, verifiable trade statistics rather than fabricated or scraped-in-a-gray-area company records.

What it does

• concentration_risk (default): for a reporter country + HS code, checks trade value against ~29 major trading-partner economies and computes a Herfindahl-Hirschman Index (HHI) — the standard economics/antitrust concentration metric, not a bespoke formula — to answer "how concentrated is my supply in one country."
• trade_flow: a single bilateral lookup (e.g. "US imports of HS 851714 from China, 2025").

Verified live, including two real bugs caught before shipping

• Confirmed UN Comtrade's keyless "preview" API works with zero registration — tested against real US import data for HS 851714 (smartphones) from China, cross-checked the exact dollar figure twice.
• Bug 1: the reference file mapping ISO country codes to Comtrade's internal codes contains historical entries — "US" naively resolved to a deprecated pre-1981 code, silently returning wrong/empty results for the actual current United States. Fixed by filtering to only currently-valid entries (no entryExpiredDate).
• Bug 2: the free tier rate-limits aggressively — a real test run of ~28 sequential concentration-mode calls hit 429 errors on roughly half of them, and in one run China itself (usually the most important partner for a US concentration check) failed on a timeout. Fixed with a retry-after-backoff on 429/timeout, which took a real test from 14/29 partners returning data up to 25/29 — verified before and after.
• After both fixes, a real US-imports-of-smartphones concentration check returned China at 52.2% share and an HHI of 3598 ("high" concentration) — a genuinely sensible, real-world-plausible result, not a synthetic test case.

What's still a known limitation

• concentration_risk checks a curated list of ~29 major economies, not every country on earth. UN Comtrade's free tier has no single "all partners in one call" option (confirmed live: requesting partnerCode=0 returns only a world-total aggregate row, not a per-country breakdown) — an exhaustive ~200-country sweep isn't practical on the free tier's rate limits. partnersChecked vs. partnersWithData in the output makes this transparent per run rather than silently presenting a partial picture as complete.
• The optional comtradeApiKey (fuller "data" tier) is implemented per UN's published docs but not live-tested — no test key was available during this build. The keyless preview path is what's actually verified end-to-end.

Input schema

{
  "mode": "concentration_risk",
  "hsCode": "851714",
  "reporterCountry": "US",
  "partnerCountry": "CN",
  "flowType": "import",
  "year": "2025"
}

partnerCountry is required for trade_flow, ignored for concentration_risk.

Output schema

concentration_risk:

{
  "reporterCountry": "string",
  "hsCode": "string",
  "flowType": "import | export",
  "year": "string",
  "partnersChecked": "number",
  "partnersWithData": "number",
  "totalTradeValueUsd": "number",
  "topPartners": [{ "partnerCountry": "string", "tradeValueUsd": "number", "sharePercent": "number" }],
  "herfindahlIndex": "number",
  "concentrationLevel": "low | moderate | high | very_high",
  "scrapedAt": "ISO timestamp"
}

trade_flow:

{
  "reporterCountry": "string",
  "partnerCountry": "string",
  "hsCode": "string",
  "flowType": "import | export",
  "year": "string",
  "tradeValueUsd": "number | null",
  "quantity": "number | null",
  "quantityUnit": "string | null",
  "sourceUrl": "string",
  "scrapedAt": "ISO timestamp"
}

Pricing

Event	Price
Run started	£0.05
Trade flow checked	£0.03
Concentration report generated	£0.10
Lookup failed	free

Setup note

No browser needed — plain HTTP calls to UN Comtrade's public API, runs on apify/actor-node:20.

Related actor

Cross-links with ../Global%20Landed-Cost%20%26%20Tariff-Change%20Monitor/tariff-change-monitor (Actor 26) — found your supply is concentrated in one country here, check what a tariff change on that country would actually cost you there.

n8n integration

• Workflow A (trigger): scheduled competitor/supply-chain monitoring for a tracked HS code + country list.
• Workflow B (processing): alert when concentration level crosses a threshold (e.g. moderate → high) or a new dominant partner country emerges between runs.