# Trade Flow & Supply-Chain Concentration Intelligence (`conceivable_extension/shipment-manifest-intelligence`) Actor

Bilateral trade-flow data and supply-chain concentration risk (HHI) by HS code and country pair, from UN Comtrade's real public statistics. Scoped to aggregate country-level data, not company-level bills of lading — see README for exactly why.

- **URL**: https://apify.com/conceivable\_extension/shipment-manifest-intelligence.md
- **Developed by:** [joseph fadero](https://apify.com/conceivable_extension) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 shipment record returneds

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

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

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

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

```json
{
  "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 Landed-Cost & Tariff-Change Monitor](../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.

# Actor input Schema

## `mode` (type: `string`):

trade\_flow: bilateral trade value/quantity between two specific countries. concentration\_risk: how concentrated a country's trade in this HS code is across its major partners (HHI) — 'how exposed am I to one supplier country'.

## `hsCode` (type: `string`):

6-digit Harmonized System code, e.g. '851714'.

## `reporterCountry` (type: `string`):

2-letter ISO code of the country whose trade you're checking, e.g. 'US'.

## `partnerCountry` (type: `string`):

2-letter ISO code of the trading partner. Required when mode is trade\_flow; ignored for concentration\_risk (which checks a curated list of major economies instead).

## `flowType` (type: `string`):

Whether to check imports into the reporter country or exports from it.

## `year` (type: `string`):

Reporting year, e.g. '2025'. UN Comtrade data typically lags 6-12 months behind the current year.

## `comtradeApiKey` (type: `string`):

Optional. Without one, this actor uses UN Comtrade's free public preview API (works out of the box, some rate/row limits). A free key from comtradeapi.un.org unlocks the fuller data API — implemented per UN's published docs but not live-verified in this build (no test key was available).

## Actor input object example

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

# Actor output Schema

## `resultsDatasetUrl` (type: `string`):

Country- and commodity-level trade-flow and supply-chain concentration data (not company-level bills of lading, a deliberate scope decision), produced by this run.

# 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 = {
    "hsCode": "851714",
    "reporterCountry": "US",
    "partnerCountry": "CN",
    "year": "2025"
};

// Run the Actor and wait for it to finish
const run = await client.actor("conceivable_extension/shipment-manifest-intelligence").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 = {
    "hsCode": "851714",
    "reporterCountry": "US",
    "partnerCountry": "CN",
    "year": "2025",
}

# Run the Actor and wait for it to finish
run = client.actor("conceivable_extension/shipment-manifest-intelligence").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 '{
  "hsCode": "851714",
  "reporterCountry": "US",
  "partnerCountry": "CN",
  "year": "2025"
}' |
apify call conceivable_extension/shipment-manifest-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,conceivable_extension/shipment-manifest-intelligence"
        }
    }
}
```

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/SaY9t2GkBoxZ4CsBA/builds/DDTsSwaDIc67pErJG/openapi.json