UN Comtrade Trade Flow Change Report

Trade analysts, procurement teams, and supply-chain researchers enter one or more bounded UN Comtrade watches. Each watch specifies one reporter, partner, HS product, flow, frequency, and period for the official keyless preview API. The Actor returns a report-first change alert, source-linked trend report, optional normalized rows, and export; unchanged checks are free.

Store Quickstart

Run a free baseline for Japan exports to World for HS chapter 84 in annual 2023 data:

{
  "watches": [
    {
      "id": "japan-world-hs84-2023",
      "reporterCode": "392",
      "partnerCode": "0",
      "hsCode": "84",
      "flowCode": "X",
      "frequency": "A",
      "period": "2023"
    }
  ],
  "monitorKey": "japan-world-hs84",
  "initialRunMode": "baseline_only",
  "generateReport": true,
  "emitRawRows": false,
  "emitExport": false,
  "emitUnchanged": false,
  "maxChargeUsd": 35,
  "dryRun": false
}

Repeat the same input on a schedule. New, changed, or removed records in the bounded response create alerts and the requested report. A source-confirmed unchanged response emits zero rows and zero charges.

The anonymous preview API is intentionally limited: one HS product and one period per request, at most 500 records, and no claim of complete country-period coverage. Use multiple narrow watches rather than assuming a preview is a full trade matrix.

Run the next report

Use emit_backfill and emitExport when you explicitly want the current bounded snapshot packaged as a report and export:

{
  "watches": [
    {
      "id": "japan-world-hs84-2023-report",
      "reporterCode": "392",
      "partnerCode": "0",
      "hsCode": "84",
      "flowCode": "X",
      "frequency": "A",
      "period": "2023"
    }
  ],
  "monitorKey": "japan-world-hs84-report",
  "initialRunMode": "emit_backfill",
  "generateReport": true,
  "emitRawRows": false,
  "emitExport": true,
  "maxChargeUsd": 35,
  "dryRun": false
}

Input examples

Monthly imports

{
  "watches": [
    {
      "id": "us-imports-hs30-202501",
      "reporterCode": "840",
      "partnerCode": "0",
      "hsCode": "30",
      "flowCode": "M",
      "frequency": "M",
      "period": "202501"
    }
  ],
  "monitorKey": "us-imports-hs30-monthly",
  "initialRunMode": "baseline_only",
  "generateReport": true,
  "maxChargeUsd": 35,
  "dryRun": false
}

Several narrow products and periods

{
  "watches": [
    {
      "id": "japan-hs84-2022",
      "reporterCode": "392",
      "partnerCode": "0",
      "hsCode": "84",
      "flowCode": "X",
      "frequency": "A",
      "period": "2022"
    },
    {
      "id": "japan-hs84-2023",
      "reporterCode": "392",
      "partnerCode": "0",
      "hsCode": "84",
      "flowCode": "X",
      "frequency": "A",
      "period": "2023"
    }
  ],
  "monitorKey": "japan-hs84-period-comparison",
  "initialRunMode": "emit_backfill",
  "generateReport": true,
  "emitExport": true,
  "maxChargeUsd": 35,
  "dryRun": false
}

Dry run

{
  "watches": [],
  "monitorKey": "preview-dry-run",
  "generateReport": true,
  "emitRawRows": true,
  "emitExport": true,
  "dryRun": true
}

Dry run output is deterministic and illustrative. It does not call UN Comtrade, write monitor state, or charge PPE.

Sample output

The first row is the aggregate report when report generation is enabled:

{
  "rowType": "trade_trend_report",
  "billingEventName": "trade-trend-report",
  "report": {
    "reportType": "bounded_trade_flow_change_report",
    "queryCount": 1,
    "changedRecordCount": 2,
    "newRecordCount": 1,
    "updatedRecordCount": 1,
    "removedRecordCount": 0,
    "byFlow": [{"key": "X", "count": 2}],
    "coverageNote": "Official preview response only; one product and one period per request, max 500 records, not comprehensive trade data."
  }
}

See docs/sample-output.json for representative report, alert, normalized row, and export records.

Output fields

• report: changed-record counts and bounded query dimensions, emitted before detail rows.
• record: reporter, partner, HS code, flow, period, trade value, quantity, and source-linked public fields when supplied by the API.
• previousRecord: prior snapshot for value changes and removals.
• matchedWatchIds: duplicate watches are fetched once and associated with all matching IDs.
• limitations and prohibitedInterpretations: safeguards travel with every row.

The Actor does not claim complete trade data, market share, forecast accuracy, causality, supplier identity, sanctions status, legal compliance, or investment value. Values are reported as published by the source for the selected bounded query.

Pricing

Event	Price	Delivered when
trade-flow-row	$0.006	Optional normalized current record for a changed snapshot
trade-flow-change-alert	$0.20	A new, changed, or removed record is observed
trade-trend-report	$12.00	Changed records are grouped into a report-first summary
trade-export-generated	$8.00	Selected changed records are packaged as a compact export

There is no start charge. The complete planned PPE amount is estimated before the first push and the run fails closed if it exceeds maxChargeUsd.

Baseline and no-change billing

• baseline_only stores the first complete source snapshot with zero rows and zero charges.
• A later unchanged response emits zero rows and zero charges.
• emitUnchanged cannot override this safeguard.
• State is committed only after every billable row receives a positive PPE receipt.
• Any API error, response validation error, partial/truncated preview, or state-save failure fails closed.

Compliance and source limits

• Only the official anonymous UN Comtrade preview endpoint is used; no login, browser session, subscription key, or user API key is accepted.
• Requests are sequential at no more than one request per second and use maxRecords=500.
• A watch contains one period and one HS product. Multiple periods/products require separate watches and are fetched separately.
• Preview responses may be incomplete for broad queries. A response that indicates truncation, partial data, more than 500 records, or exactly 500 returned records is rejected rather than presented as complete.
• The output is descriptive public data and is not legal, customs, sanctions, tax, investment, procurement, or trade advice.
• No UN endorsement or affiliation is implied.

See also

• Government Tender & Grants Alert Report for public tender and grant opportunity watches.
• GovCon Recompete Watch for public award and recompete signals.
• Procurement Intelligence for adjacent public procurement records.

Development

npm test
npm start