Country Trade Data (Exports, Imports, Balance & Partners)

{
  "type": "object",
  "required": [
    "country_code"
  ],
  "properties": {
    "year": {
      "type": "number"
    },
    "country_code": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "required": [
    "country_code",
    "country_name",
    "year",
    "total_exports_usd",
    "total_imports_usd",
    "trade_balance_usd",
    "top_exports",
    "top_imports",
    "top_partners",
    "data_source",
    "note"
  ],
  "properties": {
    "note": {
      "type": "string",
      "description": "A caveat about estimate quality. Observed as the SAME text -- '...based on 2023 published trade statistics' -- regardless of the requested year (e.g. 2022); this reads as a static disclaimer rather than one adjusted to the requested/returned year."
    },
    "year": {
      "type": "number",
      "description": "The trade data's reference year. Observed as 2023 when the optional `year` input was omitted and as the requested 2022 when it was supplied."
    },
    "data_source": {
      "type": "string",
      "description": "Typically the literal string 'World Bank API + embedded product data'."
    },
    "top_exports": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "value_usd": {
            "type": "number"
          },
          "share_percent": {
            "type": "number",
            "description": "Percent of total exports this product represents."
          }
        },
        "additionalProperties": true
      },
      "description": "Typically 5 entries."
    },
    "top_imports": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "value_usd": {
            "type": "number"
          },
          "share_percent": {
            "type": "number",
            "description": "Percent of total imports this product represents."
          }
        },
        "additionalProperties": true
      },
      "description": "Typically 5 entries, same shape as top_exports."
    },
    "country_code": {
      "type": "string",
      "description": "Two-letter ISO country code the endpoint resolved to, e.g. 'US', 'DE' -- note this differs from the three-letter code accepted as input (e.g. 'USA', 'DEU')."
    },
    "country_name": {
      "type": "string"
    },
    "top_partners": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "'export' or 'import' -- which direction this partner relationship represents. Observed as one of these two values."
          },
          "country": {
            "type": "string"
          },
          "trade_value_usd": {
            "type": "number"
          }
        },
        "additionalProperties": true
      },
      "description": "Typically 5 entries, mixing export-direction and import-direction partners in one list rather than two separate lists."
    },
    "total_exports_usd": {
      "type": "number"
    },
    "total_imports_usd": {
      "type": "number"
    },
    "trade_balance_usd": {
      "type": "number",
      "description": "Exports minus imports; e.g. negative for the US (a trade deficit) and positive for Germany (a trade surplus)."
    }
  },
  "description": "The country trade record.",
  "additionalProperties": true
}