Bilateral merchandise trade flows + balance API

Bilateral merchandise trade between two countries for a year (UN Comtrade, all commodities), returning reporter exports-to and imports-from the partner PLUS the derived trade balance, total trade and a normalized balance ratio (-1..+1). The MORE is the two-flow join into a balance an agent would otherwise compute by hand. Answers 'US-China trade balance', 'how much does X export to Y', 'bilateral trade deficit'.

Price$0.01per request

MethodPOST

Route/v1/gov/comtrade-trade-flows

StatusLive

MIME typeapplication/json

Rate limit60/minute

Cache604800s public

govecon-datacomtradetradeexportsimportstrade-balancebilateralun

API URLhttps://x402.hexl.dev/v1/gov/comtrade-trade-flows

Integration docs

Example request

{
  "reporter": "USA",
  "partner": "CHN",
  "year": 2022
}

Example response

{
  "reporter": "USA",
  "partner": "CHN",
  "year": 2022,
  "exportsUsd": 153837022415,
  "importsUsd": 575688091172,
  "balance": -421851068757,
  "totalTrade": 729525113587,
  "balanceRatio": -0.5783,
  "note": "Merchandise trade, all commodities (HS TOTAL). exportsUsd = reporter exports TO partner; importsUsd = reporter imports FROM partner."
}

Input schema

{
  "type": "object",
  "required": [
    "reporter",
    "partner"
  ],
  "properties": {
    "reporter": {
      "type": "string",
      "description": "Reporter country ISO code (major economies only, e.g. USA, CHN, DEU, JPN, GBR)."
    },
    "partner": {
      "type": "string",
      "description": "Partner country ISO code (same supported list)."
    },
    "year": {
      "type": "integer",
      "description": "Trade year; defaults to two years ago (latest reliably available)."
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}