Get Trade Balance
comtrade_get_trade_balanceRead-only
Compute the trade balance for a country over one or more periods — total exports minus total imports — with optional HS or SITC commodity filter. Preview makes two paced requests per served period; authenticated calls batch periods. Returns the signed balance (USD), export value, import value, and coverage ratio (exports / imports). Note: mirror asymmetry is common — balance reflects values as reported by this country; the same flow may be recorded differently by the partner. Uses comtrade_lookup_countries to resolve reporter codes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| freq | No | Frequency: A=annual, M=monthly. | A |
| period | Yes | Annual periods (YYYY) or monthly periods (YYYYMM). Serves the first 12 and discloses the remainder; input ceiling 120. | |
| cmd_code | No | HS or SITC commodity codes to restrict the balance calculation. Serves the first 20 and discloses the remainder; input ceiling 200. Omit to compute the overall trade balance across all commodities. | |
| reporter_code | Yes | M49 numeric code of the reporting country. | |
| classification | No | Goods classification: HS/H0–H6 or SITC S1–S4/SS. | HS |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Possible incompleteness of the balance when a preview response reaches its cap. | |
| periods | No | Balance computation per period. | |
| cmdCodes | No | Commodity codes used in the query (absent when querying all commodities). | |
| mirrorCaveat | No | Standard caveat about mirror asymmetry — balance reflects this country's reported values. | |
| reporterCode | No | M49 reporter code used. | |
| reporterDesc | No | Reporter country name. | |
| referenceNotice | No | Reference descriptions unavailable; codes and trade values retained. | |
| unservedPeriods | No | Periods beyond the 12-period work cap; query them separately. | |
| unservedCmdCodes | No | Commodity codes beyond the 20-code work cap; query them separately. |