{"uid":"cap_hjSycwdXrnBj8qn_RktyR","slug":"2s-trade-flows-api-ef582592","name":"2s Trade Flows API","description":"Annual international merchandise-trade flows from UN Comtrade (HS classification). Pass reporter (the country whose trade you want; ISO-2/ISO-3 like 'US'/'USA', a UN M49 number, or 'World'), optional partner (counterparty; default World), year (YYYY), flow (export|import), and commodity: 'TOTAL' (all goods, default), a specific HS code ('27', '8703'), or 'AG2'/'AG4'/'AG6' for a top-commodity breakdown at the 2/4/6-digit level. Returns trade value (USD), net weight, quantity, and the HS commodity, sorted by value. Country names are resolved from Comtrade's own reference data.","url":"https://2s.io/api/trade/flows?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","queryParams"],"properties":{"type":{"const":"http"},"method":{"const":"GET"},"queryParams":{"type":"object","required":["reporter","year"],"properties":{"flow":{"enum":["export","import"],"type":"string","default":"export","description":"Trade direction from the reporter's perspective. Default export."},"year":{"type":"string","description":"Calendar year (YYYY). Comtrade annual data typically lags ~6-12 months."},"limit":{"type":"integer","default":25,"maximum":100,"minimum":1,"description":"Max rows to return (1-100), sorted by trade value desc. Default 25."},"partner":{"type":"string","default":"World","maxLength":40,"minLength":2,"description":"Partner/counterparty country (same formats). Default \"World\" (all partners aggregated)."},"reporter":{"type":"string","maxLength":40,"minLength":2,"description":"Reporting country: ISO-2/ISO-3 (\"US\"/\"USA\"), UN M49 number, or \"World\"."},"commodity":{"type":"string","default":"TOTAL","maxLength":8,"minLength":2,"description":"\"TOTAL\" (all goods, default), a specific HS code (\"27\", \"8703\"), or \"AG2\"/\"AG4\"/\"AG6\" for a top-commodity breakdown."}},"additionalProperties":false}}}}},"responseSchema":{"type":"json","schema":{"type":"object","required":["ok","items","total","source"],"properties":{"ok":{"enum":[true],"type":"boolean"},"meta":{"type":"object","required":["query"],"properties":{"query":{"type":"object","required":["reporter","reporterCode","partner","partnerCode","year","flow","commodity"],"properties":{"flow":{"type":"string"},"year":{"type":"string"},"partner":{"type":"string"},"reporter":{"type":"string"},"commodity":{"type":"string"},"partnerCode":{"type":"integer"},"reporterCode":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"items":{"type":"array","items":{"type":"object","required":["reporter","reporterIso","partner","partnerIso","flow","period","commodityCode","commodity","valueUsd","netWeightKg","quantity","quantityUnit"],"properties":{"flow":{"type":"string","nullable":true},"period":{"type":"string","nullable":true},"partner":{"type":"string","nullable":true},"quantity":{"type":"number","nullable":true},"reporter":{"type":"string","nullable":true},"valueUsd":{"type":"number","nullable":true},"commodity":{"type":"string","nullable":true},"partnerIso":{"type":"string","nullable":true},"netWeightKg":{"type":"number","nullable":true},"reporterIso":{"type":"string","nullable":true},"quantityUnit":{"type":"string","nullable":true},"commodityCode":{"type":"string","nullable":true}},"additionalProperties":false}},"total":{"type":"integer","nullable":true,"description":"Total matching rows upstream; null when unknown."},"source":{"type":"object","required":["provider","url","license"],"properties":{"url":{"type":"string"},"license":{"type":"string"},"provider":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":{"ok":true,"meta":{"query":{"flow":"example","year":"example","partner":"example","reporter":"example","commodity":"example","partnerCode":1,"reporterCode":1}},"items":[{"flow":"example","period":"example","partner":"example","quantity":1,"reporter":"example","valueUsd":1,"commodity":"example","partnerIso":"example","netWeightKg":1,"reporterIso":"example","quantityUnit":"example","commodityCode":"example"}],"total":1,"source":{"url":"example","license":"example","provider":"example"}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.009","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.009/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.009","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.009","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_7BHjUXf9LYkAQCe6ReaSu","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.009","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves UN Comtrade international merchandise trade flow data (imports/exports) by country, year, and commodity code","exampleAgentPrompt":"What were the top 25 goods the US exported to the world in 2022? Pull from UN Comtrade annual data and sort by trade value.","exampleUseCases":null,"resultDescription":"Returns an array of trade flow records, each with reporter country, partner country, commodity HS code and description, trade direction (import/export), period, value in USD, net weight in kg, and quantity with unit. Also includes metadata about the query parameters used and source attribution (UN Comtrade license and URL). Total matching row count is provided when available.","failureModes":["Missing required 'reporter' or 'year' parameters returns validation error","Invalid ISO country code or M49 number returns empty result or upstream error","Requested year has no data yet due to Comtrade's 6-12 month reporting lag","Invalid HS commodity code returns empty items array","limit out of range (>100 or <1) causes schema validation failure","Upstream Comtrade API unavailable returns error response"],"whenToPreferThis":"Use this endpoint when you need official, ground-truth international trade statistics sourced from UN Comtrade — especially for annual merchandise trade values, weights, and quantities broken down by country pair and HS commodity code. Prefer this over web scraping or unofficial sources when accuracy and citability matter. Best for research, economic analysis, supply chain intelligence, and policy reporting.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-28T04:06:21.837Z","isFirstParty":false,"canonicalSlug":"2s-trade-flows-api-ef582592"}