un-comtrade-guide

Scope

Use UN Comtrade for reported international merchandise and services trade. It does not provide tariff schedules, national tariff-line detail, or observed transaction prices. Keyless preview supports focused analysis; a configured subscription key changes upstream access, not the need to verify completeness.

Identifiers

• Resolve countries with comtrade_lookup_countries for the intended role. A partner area can be invalid as a reporter (World, Metropolitan France 250), while some groupings report (European Union, 97); validAsReporter and role settle it. Select the returned reporting identity rather than a familiar ISO numeric code: Comtrade's USA reporter is 842, while the similarly named 840 entry is not reporter-valid. comtrade://countries enumerates the reference entries when browsing is needed.
• Discover goods through comtrade_search_commodities. Keep codes as strings, including leading zeros. The default HS catalog is useful for discovery; use the selected HS edition or SITC revision for historical meanings. comtrade://hs-classification/{level} navigates the default HS hierarchy, not historical editions.
• Discover services through comtrade_list_service_categories, which searches the combined EB catalog. Use its returned category and description together; numeric and SDMX category schemes coexist, so a familiar-looking code is not proof of meaning. Each category's schemes tags name the scheme catalogs (EB10, EB10S, EB02) that list its code.

Gates

1. Before calling missing records zero trade, confirm the reporting identity, category, period, frequency, and classification. Check matching data availability; a published dataset does not guarantee a particular bilateral commodity row exists. Follow availability continuation before claiming the matching index is exhausted.
2. Before comparing historical goods, inspect each row's classificationCode. The same commodity code can change meaning across editions. Default HS queries return as-reported data, not a conversion to one common edition. Explicit HS editions are unavailable on keyless trade-data preview; do not silently replace an edition-converted request with HS.
3. Before reporting a complete series or ranking, inspect truncation, coverage, reference notices, and unserved inputs: unservedPeriods, unservedReporters, unservedCmdCodes, and reportersWithoutRecords. Retrieve remaining periods, reporters, or codes separately. A reporter listed in reportersWithoutRecords returned no rows; read its referenceStatus and suggestedReporterCode before concluding it has no trade, since a partner-only code such as 250 reports as 251. Missing descriptions do not justify guessing a commodity's meaning.
4. Before summing goods, choose one aggregation level and exclude overlapping parent/child codes and TOTAL rows from the same sum. World totals and country breakdowns are alternative views; do not add them together.
5. Before computing balances or comparing mirror flows, align period, commodity definition, and reporting perspective. A missing import or export value is not zero. Preserve caveats about CIF/FOB valuation, timing, re-exports, and country definitions.