Bilateral TradeFlow record structure

The cataloged TradeFlow dataset states its own grain: "Bilateral reporter x partner x 6-digit HS commodity x flow x period." Every returned record is one country pair, one commodity, one direction and one time bucket - never a multi-commodity summary.

Behind that sentence sits a field dictionary of 38 named columns: identification fields (typeCode, freqCode, refPeriodId, refYear, refMonth, period), party codes (reporterCode, partnerCode, partner2Code), commodity detail (cmdCode, aggrLevel, isLeaf, customsCode, motCode), measures (qty, netWgt, grossWgt, cifvalue, fobvalue, primaryValue) and status booleans (isReported, isAggregate, legacyEstimationFlag).

Delivery matches the grain. The acquisition notes describe response JSON that nests records under a 'data' array alongside 'count' and 'elapsedTime', and for HS chapter 85 electrical machinery and chapter 90 instruments alone the cataloged size estimate runs into the millions of records.

Grain decides which questions a trade table can answer. A source shipping only national totals cannot say whether China's exports of HS 8542 integrated circuits to one partner moved in a given month; the bilateral, 6-digit, per-flow row can.

Two consequences follow:

• Flows stay separable. Because each row carries one flowCode, mirror reconciliation compares reporter-side exports against partner-side imports instead of fighting a blended value column.
• Aggregates are flagged, not hidden. isAggregate marks computed rows and isLeaf marks finest-detail commodity codes, so analysts can filter before summing rather than discovering double-counts late.

That discipline is rare: only 32.9% of the 1,744 datasets Datadory catalogs offer an official API, and fewer document their row contract this explicitly.

1. Ask for the stated grain. The cataloged record spells out "reporter x partner x 6-digit HS commodity x flow x period"; a vendor who cannot match that sentence is selling something coarser.
2. Count the estimation flags. Comtrade Plus exposes isReported, legacyEstimationFlag and isAggregate beside the values. A feed without them buries imputed figures inside reported ones.
3. Exercise the free route. The unauthenticated public preview endpoint returns live records with no registration, so sample real rows before committing to premium bulk download.

Where to see it in context: electronic-equipment-instruments data and semiconductors data.

These entries complete the Comtrade field picture:

• cif-fob-value-fields — the valuation columns carried inside every row of this structure.
• hs-8542-integrated-circuits — the 6-digit commodity code electronics queries filter cmdCode down to.
• un-m49-country-codes — the numeric identifiers (842 USA, 156 China) filling reporterCode and partnerCode.
• unauthenticated-preview-endpoint — the key-free route that returns sample rows of exactly this shape.