US Foreign Trade

Methods (8)

• searchExports

  read

  US exports by HS or NAICS code, country, month. Auto-routes to /exports/hs vs /exports/naics.

  Required paramstime
  Input schema

  {
    "type": "object",
    "properties": {
      "hsCode": {
        "type": "string",
        "examples": [
          "2709"
        ]
      },
      "naicsCode": {
        "type": "string"
      },
      "countryCode": {
        "type": "string"
      },
      "time": {
        "type": "string",
        "examples": [
          "2024-01"
        ]
      },
      "commLvl": {
        "type": "string"
      },
      "district": {
        "type": "string"
      },
      "limit": {
        "type": "number"
      }
    },
    "additionalProperties": false,
    "required": [
      "time"
    ]
  }

  Uses ALL_VAL_MO + E_COMMODITY. Default COMM_LVL=HS4. Slice by time to cap.

• searchImports

  read

  US imports by HS or NAICS code, country, month. Auto-routes to /imports/hs vs /imports/naics.

  Required paramstime
  Input schema

  {
    "type": "object",
    "properties": {
      "hsCode": {
        "type": "string",
        "examples": [
          "2709"
        ]
      },
      "naicsCode": {
        "type": "string"
      },
      "countryCode": {
        "type": "string"
      },
      "time": {
        "type": "string",
        "examples": [
          "2024-01"
        ]
      },
      "commLvl": {
        "type": "string"
      },
      "district": {
        "type": "string"
      },
      "limit": {
        "type": "number"
      }
    },
    "additionalProperties": false,
    "required": [
      "time"
    ]
  }

  Uses GEN_VAL_MO + I_COMMODITY (NOT ALL_VAL_MO; that is exports-only).

• searchTradeByPort

  read

  HS commodity × US port × country (porths endpoints). Filter by port code.

  Required paramsdirectionhsCodetime
  Input schema

  {
    "type": "object",
    "properties": {
      "direction": {
        "type": "string",
        "examples": [
          "imports"
        ],
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "exports"
            ]
          },
          {
            "type": "string",
            "enum": [
              "imports"
            ]
          }
        ]
      },
      "hsCode": {
        "type": "string",
        "examples": [
          "2709"
        ]
      },
      "time": {
        "type": "string",
        "examples": [
          "2024-01"
        ]
      },
      "portCode": {
        "type": "string"
      },
      "countryCode": {
        "type": "string"
      },
      "commLvl": {
        "type": "string"
      },
      "limit": {
        "type": "number"
      }
    },
    "additionalProperties": false,
    "required": [
      "direction",
      "hsCode",
      "time"
    ]
  }

  Port codes are Census 4-digit identifiers (e.g. 5301=Houston).

• searchTradeByState

  read

  HS commodity × US state × country (statehs endpoints). Filter by state postal code.

  Required paramsdirectionhsCodetime
  Input schema

  {
    "type": "object",
    "properties": {
      "direction": {
        "type": "string",
        "examples": [
          "exports"
        ],
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "exports"
            ]
          },
          {
            "type": "string",
            "enum": [
              "imports"
            ]
          }
        ]
      },
      "hsCode": {
        "type": "string",
        "examples": [
          "2711"
        ]
      },
      "time": {
        "type": "string",
        "examples": [
          "2024-01"
        ]
      },
      "state": {
        "type": "string",
        "examples": [
          "TX"
        ]
      },
      "countryCode": {
        "type": "string"
      },
      "commLvl": {
        "type": "string"
      },
      "limit": {
        "type": "number"
      }
    },
    "additionalProperties": false,
    "required": [
      "direction",
      "hsCode",
      "time"
    ]
  }

  State filter is uppercase 2-letter (TX, CA, LA).

• getTradeBalance

  read

  Convenience: fetches both directions, returns {exportsValue, importsValue, balance}.

  Required paramshsCodetime
  Input schema

  {
    "type": "object",
    "properties": {
      "hsCode": {
        "type": "string",
        "examples": [
          "2709"
        ]
      },
      "time": {
        "type": "string",
        "examples": [
          "2024-01"
        ]
      },
      "countryCode": {
        "type": "string"
      },
      "commLvl": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "hsCode",
      "time"
    ]
  }

  Hits 2 upstream endpoints in parallel. Sum is in dollars.

• getCountryCodes

  read

  Built-in Census Schedule C/D ↔ ISO lookup. Top 30 partners + USMCA/OECD/NATO/APEC.

  Input schema

  {
    "type": "object",
    "properties": {
      "searchText": {
        "type": "string",
        "examples": [
          "mex"
        ]
      },
      "region": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }

  Pass searchText to filter ("mex" → Mexico=2010). No upstream call.

• lookupHsCode

  read

  Built-in HS chapter index for petroleum, petrochem, steel, machinery, ores.

  Input schema

  {
    "type": "object",
    "properties": {
      "chapter": {
        "type": "string",
        "examples": [
          "27"
        ]
      },
      "keyword": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }

  In-memory; covers chapters 26/27/28/29/39/72/73/84/85.

• getServiceInfo

  read

  Endpoints, common variables, country-code system, value-field asymmetry, time formats.

  Input schema

  {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }

  30-day cache. Use to discover the api before composing queries.