Skip to main content
GET
GetTradeFlows

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Query Parameters

reporting_country
string

WTO member code of reporting country, as a 3-digit UN M49 code (for example "840" = United States). Empty selects the "840" default.

Pattern: ^([0-9]{3})?$
partner_country
string

WTO member code of partner country, as a 3-digit UN M49 code. Empty selects "000" = World, which is the only partner currently covered: the WTO indicators behind these flows (ITS_MTV_AX, ITS_MTV_AM) publish a World total and answer 204 for every named partner. Any other code is accepted by validation and answered with unavailable_reason TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED, so coverage can widen without a contract change.

Pattern: ^([0-9]{3})?$
years
integer<int32>

Number of years to look back from the newest seeded year, inclusive of both endpoints (years = 10 returns 11 calendar years). 0 selects the default of 10; the maximum is 30, which is the full seeded window.

jmespath
string

Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath.

Response

Successful response

Response containing trade flow records.

flows
object[]
fetchedAt
string

ISO 8601 timestamp when data was fetched from WTO.

upstreamUnavailable
boolean

True when flows could not be served because of a fault — a seeded pair whose cache entry is gone, or a cache read that failed. False when flows are served AND when the request names a combination that is simply not part of seeded coverage, which is a contract answer rather than an outage.

unavailableReason
enum<string>

TradeFlowUnavailableReason says why no rows were returned. The distinction that matters is NOT_COVERED — a contract answer, nothing is broken and a retry cannot help — against every other member, which names a fault.

Available options:
TRADE_FLOW_UNAVAILABLE_REASON_UNSPECIFIED,
TRADE_FLOW_UNAVAILABLE_REASON_INVALID_REQUEST,
TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED,
TRADE_FLOW_UNAVAILABLE_REASON_SEED_MISSING,
TRADE_FLOW_UNAVAILABLE_REASON_COVERAGE_UNKNOWN,
TRADE_FLOW_UNAVAILABLE_REASON_CACHE_UNAVAILABLE
coverageStartYear
integer<int32>

First and last calendar year covered by flows. Both are 0 when no flows are returned. This is the effective window after slicing to years, which may be narrower than the requested lookback when the seed starts later.

coverageEndYear
integer<int32>