TradeStats - customs trade statistics

One product (HS2, HS4 or HS6 code, e.g. "850760" lithium-ion batteries, "8708" auto parts, "72" iron and steel, "030617" frozen shrimp) side by side across several reporting countries (default: all of JP, US, GB, EU) for one flow. Every country is measured over the same 12 months, ending at common_month (the latest month all compared countries have published, normally the earliest of their latest months). Per country: the 12-month value in US dollars on a comparable basis (imports CIF, exports FOB; the US export value is FAS and the notes say so), the previous 12 months and year-over-year change, kilograms, the unit price in US dollars per kg (only where weights exist; kg_coverage says what share of the value has a weight) and the 3 largest partners with their shares. A country without the code is status "no_code" and one with a missing month status "no_data"; they are never shown as 0. Partner definitions differ between countries (origin, consignment, destination); the notes explain it. Use it for "which country trades more of X" or "how do unit prices compare"; national codes (JP 9 digits, US 10, GB 8) are rejected. Use get_mirror_trade instead to put one country's exports to another next to that country's imports from it, and get_item_summary for the full detail of one country. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Splits the change in the value of a named indicator or of an HS code into a unit-value (price) effect and a volume effect: the latest window of 1, 3 or 12 months (default 12) is compared with the same months a year earlier, with the log-mean (LMDI) method, so the two effects add up to the change in value exactly (check shows the residual). The answer gives value, quantity and unit value for both windows in the reporter currency and in US dollars. Give either "indicator" (an id or alias from list_indicators; only indicators that have a quantity measure can be split, others answer decomposition_not_applicable) or "reporter", "flow" and "code" (HS code of 2, 4 or 6 digits or the national code; "country" for one partner). Use it for questions such as how much of a change in imports or exports came from a higher unit value and how much from a larger quantity. The unit value is value divided by quantity, a calculation that also reflects product mix, not a price index; in US dollars the exchange-rate movement is part of the price effect; the split describes the numbers and does not show causes. A window with a missing month, a missing weight or a zero quantity is returned as null with a reason, never as a zero effect. Reference information computed mechanically from public statistics; not investment advice, a credit rating or a trading recommendation.

Trade balance of one reporter for a product and partner country (default: world total) by month: export value, import value and balance (exports minus imports), in the reporter's currency and in US dollars. A month with trade in one direction only shows the other side as 0 only when that direction is published for the month, has no source gap, AND the chapter has no undisclosed (withheld) amount that month; otherwise the other side and the balance are null (months_unknown counts them; never treat null as 0). For the United Kingdom (GB) most one-direction chapter-months are null for this reason. Available at HS6, HS4 and HS2 only, because national import and export codes are different numbering systems. This tool combines both flows, so it takes no flow argument. Use from/to (YYYY-MM, or just YYYY for a whole year) for the range. Use it for "does the United Kingdom run a surplus or a deficit with Germany in vehicles and parts (chapter 87)?"; for one direction alone, with quantities and prices, use get_series. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Call this first. Describes what the service holds: the reporters (JP, US, GB, EU) with their currency, national code level, and for import and export the first month and the latest published month; per reporter also source (the agency to name when you cite the data) and latest_month (that reporter's own latest published month; data_through, also given as common_latest_month, is only the latest month published by every reporter for BOTH flows, so a reporter can be ahead); the HS levels, the datasets, how to choose between the tools (get_catalog, then search_items, then get_item_summary, then the specific tools), and the access limits that apply to you (history window, ranking size, whether an API key is in use). Takes no arguments. It also lists null_reasons, the fixed words used in *_unavailable_reason fields. Use it for "what period does the data cover?" and "what is the latest month?"; it has no product figures, so for a product use get_item_summary. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Call by name, no HS code needed: returns one named indicator as a series (monthly or quarterly, newest first) with its latest value, year-on-year changes, a partner-country breakdown where the indicator has one, the definition, the caveats and a fixed notice that the value is our own calculation and not an official figure. Give an id or an English or Japanese alias (a few distinctive words also work when they match one indicator); list_indicators shows what exists. Use it to read an indicator by name; use get_series instead for one HS code. An indicator that cannot be computed yet is answered with status not_computable or not_built and the reason, never with zeros. Naphtha prices state their quantity basis: kL read directly from the source, or (only as a fallback) an estimate under a stated density assumption.

One-call overview of a product (HS2/4/6 or national code) of one reporter for the usual questions: a one-line summary (ai_context_summary, in US dollars), latest month, the last 12 months against the previous 12 and 3 years earlier, top 20 partners plus "other", the fastest growing and declining partners, calendar-year totals, partner concentration, new markets, the seasonal peak and trough months (or seasonality_unavailable_reason) and an anomaly signal, with notes on gaps and non-comparable periods. Precomputed monthly; use it right after search_items (or first, when you know the code) instead of several separate calls (e.g. semiconductor manufacturing machines 848620 for export, pharmaceuticals chapter 30 for import). get_item_summary is about one product; get_catalog is about the whole service (coverage, latest month, your limits), so call get_catalog for those and this tool for a product. For other months, a single partner country or details use get_series, get_partners, get_ranking, get_new_markets, get_seasonality. value_basis says on which basis the reporter's own values are (for example the US import value is the customs value without freight and insurance); compare_countries restates imports on a CIF basis, so its totals can differ by about 1-2% from this answer. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Estimate of one country's trade for a product from the records of the reporting countries that trade with it: for a target such as CN (China), flow "import" sums the reporters' exports to the target (what the target bought from them) and flow "export" sums the reporters' imports from the target, over the same 12 months ending at the latest month every reporter used has published, in US dollars. Use it for a country whose own customs statistics are not available here. Returns the estimate, each reporter's value and share, the previous 12 months and year-over-year change, which reporters were used or had no figure (never counted as 0) and notes. It is an estimate, not a published figure: it covers only the reporting countries listed (the rest of the target's trade is not in it), exports are FOB and imports CIF, goods routed through trading hubs such as Hong Kong are recorded under the hub, and precious metals (HS 71) can differ enormously between the two sides. Available at HS6, HS4 and HS2 only. For the two records of trade between two reporting countries use get_mirror_trade instead.

Two customs records of trade between two reporting countries: reporter's flow (export or import) with partner as the other side, next to the partner's opposite flow with the reporter as the other side. For example reporter JP, partner GB, flow export, code 8708 (auto parts) shows Japan's exports to the United Kingdom beside the United Kingdom's imports from Japan, for the same 12 months (ending at the latest month both sides have published), in US dollars with the weights. Returns each side's value, kg, basis (exports FOB, imports CIF; the US export value is FAS) and partner definition, the difference (import side minus export side) and the ratio (import side / export side). The import side is normally larger because it includes freight and insurance; differences also come from timing, classification and re-exports, and each country defines its partner differently (the UK counts imports by country of consignment). Works at HS6, HS4 and HS2 only. Use it to check one country's figure against the partner's record, or to see how large the valuation gap is; use compare_countries instead to compare more countries on one flow. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Partner countries that are new or surging for one product of one reporter, comparing the latest 12 months with the 12 months before. "new": the 12-month value is at least min_value (default 1,000,000 US dollars; never below 100,000) and the previous 12 months were lower and under 100,000 US dollars (no trade counts as 0). "surging": the 12-month value is at least min_value and grew +100% or more in US dollars (at least doubled), not counting the new ones. Each list is ordered by 12-month value, largest first; limit caps the rows of both lists together ("new" is filled first, then "surging"). Partners whose previous 12 months are unknown are in neither list. Use it for questions like "which countries started buying Japanese auto parts (8708)?" or "which markets are taking off?". For the whole partner ranking use get_partners (sort "growth"); for a one-call overview of a product use get_item_summary. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Trading partners of one reporter for one product. window 12 (default) covers the latest 12 months: each partner's 12-month value (and value_usd), share, year-over-year change against the previous 12 months, the 3-year change and rank; sort "growth" ranks by growth instead of size and, unless min_value is given, leaves out partners below a default floor (the larger of US$ 1,000,000 and 1% of the world 12-month value) because small bases give large percentages; min_value (US dollars) sets another floor (0 shows every partner). window 1 gives one month (any month, with month). Both include other (the world total minus the partners shown), country-concentration measures (HHI, number of partners, top partner and its share) and partner_count (every partner with trade in the window, whatever limit or min_value), partners_returned, truncated (limit cut off partners) and partners_below_floor (partners under min_value or the default growth floor). Use it to see who buys from or supplies the reporter, how concentrated the supply is and who is growing (e.g. where the United Kingdom's lithium-ion batteries 850760 come from and China's share). get_partners covers one product across all its partners over 12 months (or one month); use get_ranking instead to rank the products of one partner, or to find the biggest month-on-year movers; use get_new_markets for partners that are new or have doubled. Not included: partner history over time (use get_series with country). Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Rankings of one reporter for a month. kind "items_for_country": the largest products (at the chosen level) for a partner country (default: world total). kind "countries_for_item": the largest partner countries for one product code. kind "movers_up" / "movers_down": the products with the largest US-dollar increase / decrease versus the same month a year earlier (for a partner, default world; kept for the world total and some partners), with previous-year value, change and year-over-year percent. month defaults to the latest. Results are precomputed ranks; limit is capped by your key tier (default top 20 without a key). Use it for "what does Japan buy from Vietnam?" (items_for_country) or "which products from China jumped this month?" (movers_up with country). get_ranking looks at a single month; for one product's partners over the latest 12 months, with growth and concentration, use get_partners instead; for one product's overview use get_item_summary. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Seasonal pattern of one product of one reporter: for the 3 latest full calendar years before the year of the latest published month (data through 2026-08 gives 2023 to 2025; the years are stated in the answer), each calendar month's share of the 3-year value total and of the 3-year quantity total, the lowest and highest share of that month in any single year, and the peak and trough months (adjacent months merged, e.g. Oct-Nov, with their share of the year). Covers the world total and the 5 largest partners by latest-12-month value, or one partner with country. Not produced where the 3-year annual average is below min_value (default 1,000,000 US dollars) or trade is missing in any of the 3 years; seasonality_unavailable_reason then says not_enough_history, below_threshold, or (no month beyond 0.8x to 1.2x of an even share) no_peak_or_trough. Months are the months goods left (exports) or entered (imports) the reporting country. Use it for "when is the busy season?" or "which months are weak?" (e.g. knitted sweaters 6110 or frozen shrimp 030617); for month-by-month history use get_series. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Monthly time series for one product (HS2/4/6 or national code) of one reporter and partner country (default: world total). Per month: value and value_usd, quantity, kilograms, unit price (per unit and per kg), year-over-year and month-over-month change, share of the country total and trailing-12-month share, flags for months whose changes are not comparable because of a reclassification or definition change. When available it also includes precomputed signals: 3- and 6-month moving averages, deviation from them, acceleration, 12-month volatility and a 36-month anomaly score, each with the number of months used. Use from/to (YYYY-MM, or just YYYY for a whole year) to choose the range; the latest 200 months are returned at most. A monthly answer also carries totals, the sums over the rows returned (months_with_value, value, value_usd, quantity only when every row has one in a single unit, kg, unit_price = value / quantity and unit_price_kg as ratios of sums; complete says whether every month of the range has a row and nothing was cut by the 200-row limit). When quantity, kg or unit_price is null the row says why (quantity_unavailable_reason, kg_unavailable_reason, unit_price_unavailable_reason; for mixed_units also child_units, the units below the code). freq "year" returns calendar-year totals instead (value, quantity, unit price, year-over-year changes; the current year is flagged ytd). Use it for history, trends and quantity or unit-price questions (e.g. frozen shrimp 030617 by year, or lithium-ion batteries 850760 from one country by month). For a quick overview of the latest figures use get_item_summary instead; for the busy and slow months use get_seasonality. Not included: forecasts, partner detail (see get_partners). Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.

Concentration of the supplying countries behind a named indicator or an HS code over the latest 12 months: the Herfindahl index (hhi, 0 to 1; score_points is the same figure on the 0 to 10,000 scale), the share of the largest supplier and of the top three, the number of supplying countries, how hhi moved against 1 and 3 years earlier (more_diversified, little_change or more_concentrated) and the main suppliers. Give either "indicator" (only indicators with a breakdown by partner country, called "by origin" or "by destination", have one; others answer dependency_not_applicable) or "reporter" and "code" (flow defaults to import; for exports it measures the concentration of destinations; an HS code answers for the latest month only). Use it for questions about how concentrated the sources of a product are and whether they are concentrating or diversifying. The hhi is a mathematical measure of concentration, not a forecast; the partner country is the country of origin or of consignment depending on the reporter and can include transshipment; the 0.02 change used for the direction labels is our convenience threshold, not a standard. For an HS code, top3_share and top_suppliers are shares of the world 12-month total (partners without a country code included in the total), while hhi uses partners with a country code only. Reference information computed mechanically from public statistics; not investment advice, a credit rating or a trading recommendation.

Call by name, no HS code needed: lists the named indicators this service computes from public customs statistics (for example the quarterly base price of domestic naphtha, naphtha import prices and origins, or Japan passenger car and parts exports by destination). Each entry has its id, aliases in English and Japanese, definition, how often it is published, the caveats, the latest month and whether it can be computed in this build (status ok, not_computable with a reason, or not_built). Use it first to find the id or alias to give to get_indicator; narrow the list with reporter or with words in query. The values are our own calculations, not official published figures.

Report a figure that looks wrong or a data problem you noticed (at most 10 reports per day per caller). Give the tool and arguments of the call in question and describe the problem in message (up to 2,000 characters). Returns a report id; the text is stored for review by the operator and is never shown to other users. Use it only after checking the figure; not for questions or feature requests. Look at get_catalog or the notes of an answer first: gaps and non-comparable periods are often documented there.

Find product codes of one reporter by words from the product name (customs wording, e.g. "lithium-ion", "frozen shrimp", "integrated circuits") or by a code prefix (digits, e.g. "8708" or "30"). Use it first when you do not know the exact code; when you know the code, go straight to get_item_summary. Returns code, description, unit, and the first and last month with data. level defaults to hs6 on a build that serves HS6 and above (national-level series exist there only for a few listed codes; each hit says series_available, and for false gives hs6_parent), and to the reporter's national level (most detailed) on a build with full national series; use hs6/hs4/hs2 for broader groups (a code prefix with level hs4 or hs6 lists the codes under a chapter or heading, in code order and capped at limit, so a long list is cut off). Matching ignores case, hyphens and simple plurals, and knows common spelling variants (aluminum/aluminium, sulfur/sulphur, color/colour, tire/tyre) and one product synonym (passenger cars = motor cars); there are no other synonyms. Each hit says in available_in whether the code exists for import and/or export (with the period) and whether net trade (get_balance) is available. It returns codes, not trade values. Customs trade statistics of several reporting countries (Japan JP, United States US, United Kingdom GB, European Union (27 member states) EU) from their official customs data, monthly, by HS product code and partner country. value fields are in the reporter's currency (currency: JPY, USD, GBP or EUR) and *_usd fields in US dollars; ratios and shares are fractions precomputed from the full dataset; every answer carries reporter, currency, data_through (latest published month), the reporter's attribution, and notes. Maximum 200 rows per answer. Numbers in answers are rounded once, at the end: amounts (value, *_usd, v12 ...) to 2 decimals, quantity and kg to 3, unit prices (unit_price*) to 4 significant digits below 100 and 2 decimals from 100 up (never rounded to 0), and ratios, shares and growth rates (yoy*, mom*, share*, hhi*, chg3y) to 6; whole numbers and null are left as they are. A null quantity, kg or unit price comes with a *_unavailable_reason (mixed_units, weight_only, no_quantity_in_source, no_weight_in_source, source_gap, withheld; get_catalog lists them in null_reasons), and a missing seasonality with seasonality_unavailable_reason. The national level (JP 9-digit, US 10-digit, GB 8-digit codes) differs between reporters and between import and export; EU has no national level (HS6 only); HS6, HS4 and HS2 are shared. Import and export are separate datasets, so reporter and flow are always required for product figures. Rankings (limit) are limited to the top 20 without an API key (more is refused with out_of_scope) and to 100 with a free API key. Start with get_catalog (coverage, your access limits, which tool to use) or, when you already know the code, get_item_summary for a one-call overview of a product.