Skip to main content

Trade Tools

These tools answer questions like:

  • "Who are the top exporters of semiconductors globally?"
  • "What are Thailand's main trade partners for electronics?"
  • "Has Vietnam's share of US electronics imports grown?"
  • "What's the trade balance between the US and China for solar panels?"
  • "Which countries dominate EV battery exports?"

Tools at a glance​

ToolWhat it doesCredits
find_hsResolve a goods/services concept to an HS/EBOPS codeFree
search_tradeTrade flows for a country over timeBYOK
top_partnersTop trading partners for a country + productBYOK
top_tradersCountries ranked by trade in a productBYOK
trade_balanceTrade surplus/deficit for a countryBYOK

:::info BYOK β€” Bring Your Own Key Comtrade data tools require a UN Comtrade API key connected to your account. Without a key, the tools return a call-to-action with a link to connect one. You can still answer from general knowledge in the meantime.

find_hs is always free β€” no key required. :::

find_hs β€” Resolve a concept to a trade code​

Translates any goods or services concept to its UN Comtrade classification code. Always call this first β€” never guess an HS code.

  • Goods β†’ HS code (Harmonized System): "semiconductors" β†’ 8542, "electric vehicles" β†’ 8703, "soybeans" β†’ 1201
  • Services β†’ EBOPS code: "financial services" β†’ SB, "tourism" β†’ ST

Works in any language: "ΰΈŠΰΈ΄ΰΈ›" β†’ semiconductor codes, "εŠε°Žδ½“" β†’ same.

Returns ranked candidates at multiple granularities (chapter / heading / subheading) β€” pick the level of specificity you need, then pass the code(s) to the Comtrade tools.

This resolver is free (0 credits).

search_trade β€” Trade flows over time​

Returns a country's exports or imports for a specific HS code over time β€” annual series showing how the flows evolved.

search_trade(
  reporter="Thailand",
  partner="US",
  hs_code="8542",        # semiconductors
  flow="export",
  from_year=2018
)

Key params:

  • reporter β€” reporting country (name, ISO, or M49 code; resolved server-side)
  • partner β€” counterpart country, or "World" for all partners
  • hs_code β€” from find_hs
  • flow β€” export or import
  • from_year / to_year β€” year range

top_partners β€” Top trading partners​

Returns the top trading partners for a country in a specific product category β€” how much they traded and what share each partner represents.

top_partners(
  reporter="Vietnam",
  hs_code="8471",      # computers
  flow="export",
  year=2023
)

Use this for: "Who buys Thailand's electronics?" or "Where does Germany source its lithium from?"

top_traders β€” Countries ranked by trade​

Returns countries ranked by how much they export or import a specific product. Pass multiple HS codes to combine them (e.g. chicken + pork in a single livestock total).

top_traders(
  codes=["0207", "0203"],   # chicken + pork combined
  flow="export",
  year=2023,
  limit=15
)

Use this for: "Which countries dominate EV battery exports?" or "Who are the biggest rice exporters?"

trade_balance β€” Trade surplus and deficit​

Returns the trade surplus or deficit for a country across all products (or a specific HS code), showing how the balance has evolved over time.

trade_balance(reporter="US", partner="China", from_year=2018)
trade_balance(reporter="Germany", hs_code="8703")  # EVs only

Typical workflow​

Trade questions typically follow this pattern:

1. find_hs("semiconductors")              β†’ hs_code: "8542"  (free)
2. top_traders(codes=["8542"], flow="export", year=2023)
   β†’ Taiwan 38%, South Korea 22%, Netherlands 12% …

3. find_hs("electric vehicle batteries") β†’ hs_code: "8507"
4. top_partners(reporter="China", hs_code="8507", flow="export")
   β†’ EU 34%, US 18%, Korea 11% …

When to use trade tools​

Trade context is most valuable as a backdrop for an investment read β€” not as a standalone answer:

ScenarioTrade question to ask
Exporter facing tariffsWhich products are affected? β†’ find_hs β†’ search_trade
Supply chain analysisWhich countries dominate this input? β†’ top_traders
Country/sector readHow dependent is this market on a single partner? β†’ top_partners
Trade policy impactHow has the balance shifted since tariffs were applied? β†’ trade_balance over time

For a company with heavy cross-border revenue, asset_pulse returns revenue_by_region and related_assets β€” use those to identify which trade flows matter before querying Comtrade.

Routing guide​

You want to…Use
Get an HS code for a productfind_hs (free, always do this first)
How have Thailand's chip exports changed?find_hs β†’ search_trade
Who are the biggest solar panel exporters?find_hs β†’ top_traders
Who does Japan buy its LNG from?find_hs β†’ top_partners
US-China trade balance in EVsfind_hs β†’ trade_balance