TradeService

GetTradeFlows

Get bilateral merchandise trade flows.

get/api/trade/v1/get-trade-flows

Request

  • Base URL: https://api.worldmonitor.app
  • URL: https://api.worldmonitor.app/api/trade/v1/get-trade-flows
  • Auth: one of:
    • API key in header X-WorldMonitor-Key
    • API key in header X-Api-Key

Query parameters

reporting_countrystring

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

partner_countrystring

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.

yearsinteger

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.

jmespathstring

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

OK

fetchedAtstring

ISO 8601 timestamp when data was fetched from WTO.

upstreamUnavailableboolean

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

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.

coverageStartYearinteger

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.

coverageEndYearinteger

Changes

No recorded changes to this operation across all 1 revision of this API.