Trade and product check¶

GET /v1/products/{hs6} is a one-call dossier on a 6-digit HS product for trade with Russia: who supplies Russia, at what price, in which months Türkiye sells, which restrictions apply, and how many Russian companies are in the industries that buy it. It replaces five or six separate lookups and is the right first call for any product question.

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/products/382440?years=3"

Parameters¶

Parameter	Type	Default	Meaning
`hs6` (path)	string	required	Exactly 6 digits, for example `382440`. No dots, spaces, or shorter/longer codes: anything else returns 400 `hs6 must be exactly 6 digits`. Leading zeros matter (`090111`).
`years`	integer	`5`	How many annual periods to return in `russia_imports_by_supplier`: the most recent `years` years that have data for this code. Range 1 to 20; otherwise 400 `years must be between 1 and 20`. Only that block depends on it.

Typical latency is 2 to 4 seconds. The full response is about 25 to 30 KB.

Response at a glance¶

data has ten keys. A block with no data is null and notes says why.

Key	What it is
`hs6`	The code you asked for.
`russia_imports_by_supplier`	Annual: Russia's imports of this code by supplying country, top 10 per year plus `others`.
`monthly_suppliers`	Monthly: same shape for the last 24 months present in the monthly mirror.
`china_chapter_monthly`	China's monthly exports to Russia for the whole HS chapter (2 digits), not this product.
`turkey_exports_monthly`	Türkiye's own exports of this code to Russia, last 24 months (TÜİK).
`unit_prices`	USD per kg by supplier for the last complete year.
`seasonality`	Average monthly share of Türkiye's annual exports of this code to Russia.
`restrictions`	US CHP list, EU 833/2014 annexes, Russian parallel-import list for this code.
`buyers`	Counts of active Russian companies in the OKVED industries that buy this product, and the top regions.
`notes`	Object: block name to explanation, for every block that is `null` or limited. Empty `{}` when everything is present.

meta.sources lists each source that returned data, with as_of = the newest period used from it (period start date). meta.truncated is always false for this endpoint.

Where the numbers come from¶

The "Russia imports from X" blocks are mirror data: they use what the exporting countries report as their exports to Russia (partner code 643), not Russian customs statistics. Consequences:

A country appears only if it reports. Missing countries are missing from the totals, so total_value_usd is the sum of what reporters sent, not Russia's full import.
The latest year and the latest months are often reported by only some countries and fill in later. A drop at the end of a series can be late reporting, not a market fall.
China is special: its monthly data after December 2024 is only available at HS-chapter level (see china_chapter_monthly).

How shares are computed¶

For every period (a year, or a month) the API takes all reporting countries, sorts them by value_usd and computes:

total_value_usd: sum of value_usd over all reporters of that period.
suppliers: the top 10 by value, each with share = value_usd / total_value_usd.
others: everything below the top 10, as {suppliers: <count>, value_usd, share}.

So the shares of suppliers plus others.share add up to 1. others.suppliers is 0 when 10 or fewer countries reported, which is common in recent periods.

reporter is the numeric UN country code (156 China, 398 Kazakhstan, 699 India, 51 Armenia, 268 Georgia, 792 Türkiye, 392 Japan, 616 Poland, 410 South Korea). reporter_iso2 is the two-letter code and can be null when no mapping is held.

Block reference¶

`russia_imports_by_supplier`¶

An array, oldest year first, one object per year (up to years). Example: the 2025 entry for 382440 (live response):

{
  "year": 2025,
  "total_value_usd": 13130741.575000001,
  "suppliers": [
    { "reporter": 156, "reporter_iso2": "CN", "value_usd": 7275197.0, "share": 0.5540583491378323 },
    { "reporter": 398, "reporter_iso2": "KZ", "value_usd": 2405362.97, "share": 0.18318561493736502 },
    { "reporter": 699, "reporter_iso2": "IN", "value_usd": 1472074.983, "share": 0.11210905146459711 },
    { "reporter": 268, "reporter_iso2": "GE", "value_usd": 1002980.0, "share": 0.07638410932628532 },
    { "reporter": 792, "reporter_iso2": "TR", "value_usd": 868136.0, "share": 0.06611477311021559 },
    { "reporter": 392, "reporter_iso2": "JP", "value_usd": 79973.232, "share": 0.006090534304038346 },
    { "reporter": 410, "reporter_iso2": "KR", "value_usd": 26401.0, "share": 0.0020106252072057853 },
    { "reporter": 51, "reporter_iso2": "AM", "value_usd": 616.39, "share": 4.6942512460496725e-05 }
  ],
  "others": { "suppliers": 0, "value_usd": 0.0, "share": 0.0 }
}

Field	Meaning
`year`	Calendar year.
`total_value_usd`	Sum over all reporters, USD.
`suppliers[]`	Top 10: `reporter`, `reporter_iso2`, `value_usd`, `share`.
`others`	Remainder: `suppliers` (how many countries), `value_usd`, `share`. In 2023 the same code has `{"suppliers": 14, "value_usd": 1540738.788, "share": 0.0588…}`.

Only years that have rows are listed; the window ends at the newest year with data and counts back years years among those present.

`monthly_suppliers`¶

The last 24 distinct months that have rows in the monthly mirror, oldest first (not necessarily 24 consecutive calendar months). Same shape as the annual block, with period (first day of the month) instead of year, and each supplier also has net_kg (net weight, can be null).

{
  "period": "2024-10-01",
  "total_value_usd": 1605853.244,
  "suppliers": [
    { "reporter": 156, "reporter_iso2": "CN", "value_usd": 944572.0, "net_kg": 458615.0, "share": 0.5882056803940423 },
    { "reporter": 699, "reporter_iso2": "IN", "value_usd": 517963.57, "net_kg": 142331.0, "share": 0.3225472638519638 },
    { "reporter": 392, "reporter_iso2": "JP", "value_usd": 78976.674, "net_kg": 15440.0, "share": 0.04918050531397127 }
  ],
  "others": { "suppliers": 0, "value_usd": 0.0, "share": 0.0 }
}

(The real entry lists all its suppliers, six for that month; the list is trimmed here to three.) null when the monthly mirror has no rows for the code, with a note under notes.monthly_suppliers.

Count the reporters

In the 382440 response the number of countries per month falls from 9 and 6 (Sept and Oct 2024) to 2 to 5 in 2025 and 2026. A month with two or three reporters says little about the market. Compare len(suppliers) + others.suppliers across periods before you read a trend.

`china_chapter_monthly`¶

{
  "hs2": "38",
  "level": "HS chapter (2-digit)",
  "note": "China GACC publishes Russia trade by HS chapter (2-digit) only, so this is the value of the whole chapter, not of this HS6 line; use it for the direction of China's trade, not for the product's size.",
  "rows": [
    { "period": "2025-01-01", "value_usd": 92909000.0 },
    { "period": "2025-02-01", "value_usd": 51491000.0 },
    { "period": "2025-03-01", "value_usd": 95603000.0 }
  ]
}

rows holds every month available, oldest first (21 months from 2025-01 in the live response; the sample above is trimmed to three). The value is the whole chapter 38 ("miscellaneous chemical products"), far larger than this one product (92.9 M USD in January 2025 for the chapter, against a 7.3 M USD full-year China figure for the product). Use it for direction (up or down), never as the size of the product.

`turkey_exports_monthly`¶

Türkiye's own exports of this HS6 to Russia from TÜİK, last 24 months present, oldest first. null when TÜİK shows no such exports.

[
  { "period": "2024-06-01", "value_usd": 56294.0, "net_kg": 18900.0 },
  { "period": "2024-07-01", "value_usd": 127528.0, "net_kg": 52709.0 },
  { "period": "2024-08-01", "value_usd": 43239.0, "net_kg": 21646.0 }
]

(Trimmed to the first three of 24 items.) This is Turkish customs data, not mirror data, and usually runs a month or two behind the present.

`unit_prices`¶

USD per kilogram by supplier for the last complete calendar year that is present (never the current, partial year), independent of years. Only suppliers that reported net weight appear, top 10 by value.

{
  "year": 2025,
  "rows": [
    { "reporter": 156, "reporter_iso2": "CN", "value_usd": 7275197.0, "net_wgt_kg": 5136542.0, "usd_per_kg": 1.4163608513276051 },
    { "reporter": 398, "reporter_iso2": "KZ", "value_usd": 2405362.97, "net_wgt_kg": 457170.0, "usd_per_kg": 5.261419100115931 },
    { "reporter": 699, "reporter_iso2": "IN", "value_usd": 1472074.983, "net_wgt_kg": 580830.0, "usd_per_kg": 2.534433453850524 }
  ]
}

(Trimmed to three of eight rows.) usd_per_kg is value_usd / net_wgt_kg. It is an average over everything a country shipped under the code, so it mixes grades; read it as an indication of price level and spread. null when nobody reported weight (then notes.unit_prices says so).

`seasonality`¶

{
  "years": [2020, 2021, 2024],
  "basis": "average over the listed complete years of each calendar month's share of that year's exports",
  "months": [
    { "month": 1, "avg_share": 0.06559022641600404 },
    { "month": 2, "avg_share": 0.07979790402222593 },
    { "month": 3, "avg_share": 0.08325176497586034 }
  ]
}

(Months 4 to 12 removed from the sample; the real list has 12 items whose avg_share sum to 1.) For each of up to the last three complete years (all 12 months present in TÜİK data), the API takes each month's share of that year's exports and averages across those years. For 382440 the full list peaks in September (0.130) and has a trough in August (0.032). It is built from the whole TÜİK history for the code, not only from the 24 months in turkey_exports_monthly. It needs at least 2 complete years; otherwise the block is null and notes.seasonality explains.

`restrictions`¶

Three keys, same content as /v1/restrictions/{hs}, with the parallel-import list lifted out of eu:

Key	Content
`hs`	US CHP list: `query`, `on_chp_list`, `items[]`.
`eu`	`query`, `eu_833_annexes[]`, `us_chp[]`.
`parallel_import`	Russia's parallel-import list entries: `tnved_code`, `mode`, `rows`, `brands_sample`.

For 382440: not on the US CHP list; EU Annex XXI (import ban, Art. 3i(1)) and XXIII (export ban, Art. 3k(1)) cover 3824; parallel-import entries exist for chapter 38 and for 3824400000 (in the live response the parallel-import array has four entries; the sample shown on the restrictions page is trimmed to three). Field-by-field explanation on the sanctions and restrictions page.

`buyers`¶

Which Russian industries buy this product, and how many active companies are in them. Counts only: no company names.

Field	Meaning
`mappings[]`	Rows of the HS-to-OKVED mapping used: `hs_prefix`, `okved_prefix`, `note`. The longest matching HS prefix wins; all rows of that prefix are used.
`by_okved[]`	For each `okved_prefix`: `companies`, the number of active companies whose main OKVED code starts with it.
`top_regions[]`	Up to 10 regions with the most active companies across all the listed OKVED prefixes: `region_code`, `region`, `companies`.

{
  "mappings": [
    { "hs_prefix": "3824", "okved_prefix": "20.59", "note": "prepared binders, chemical mixtures n.e.c.: other chemical products makers" },
    { "hs_prefix": "3824", "okved_prefix": "23.64", "note": "concrete and mortar additives: dry construction mix makers" },
    { "hs_prefix": "3824", "okved_prefix": "46.75", "note": "wholesale of chemical products" }
  ],
  "by_okved": [
    { "okved_prefix": "20.59", "companies": 1696 },
    { "okved_prefix": "23.64", "companies": 574 },
    { "okved_prefix": "46.75", "companies": 10566 }
  ],
  "top_regions": [
    { "region_code": "77", "region": "77 Москва г", "companies": 2453 },
    { "region_code": "78", "region": "78 Санкт-Петербург г", "companies": 925 },
    { "region_code": "52", "region": "52 НИЖЕГОРОДСКАЯ ОБЛАСТЬ", "companies": 774 }
  ]
}

(top_regions trimmed to three of ten.) The mapping covers HS chapters 28 to 40 only; for other chapters buyers is null with a note. The counts are a size of the potential buyer base, not a list of buyers; they count each company once per prefix. To get names, call /v1/companies/search with one of the okved_prefix values, only_active=true and a region.

`notes`¶

An object of strings keyed by block name. Present keys in practice: russia_imports_by_supplier, monthly_suppliers, china_chapter_monthly, turkey_exports_monthly, unit_prices, seasonality, buyers. Real examples:

{
  "seasonality": "Fewer than 2 complete calendar years (all 12 months) of TUIK exports to Russia for this HS6.",
  "buyers": "No buyer mapping curated for this product group yet (buyer mappings cover HS chapters 28-40 only)."
}

(from GET /v1/products/854231). Always read notes when a block is null: it separates "no such data" from "not enough data". For 382440 the response has "notes": {}.

Worked reading of the `382440` response¶

HS 3824 40 is prepared additives for cements, mortars and concrete. This is how the sample (?years=3) reads:

Market size and trend. Reported supplies to Russia: 26.2 M USD in 2023, 23.6 M in 2024, 13.1 M in 2025. Taken at face value that is a 50% fall since 2023, but see the coverage check in step 6.
Who supplies. China is the largest supplier in all three years and its share rises: 31% (2023), 36% (2024), 55% (2025). Kazakhstan holds 18% in 2023 to 2025. Armenia falls out of the top three: 22% in 2023, 17% in 2024, below 0.1% in 2025. India reaches 11% in 2025. Türkiye (TR) is the fifth of eight reporting suppliers in 2025, with 868 k USD (6.6%).
Monthly pattern. In Oct 2024 China has 59% and India 32%; Nov 2024 China 68%, India 20%, Georgia 8%. The latest monthly entry (Aug 2026) totals 354 k USD, split between India (50%) and Georgia (49.5%), which only shows how few countries have reported yet.
Prices. In 2025 China, Georgia, Türkiye and South Korea ship at about 1.3 to 1.5 USD/kg, India at 2.5, Kazakhstan at 5.3 and Japan at 5.0. A figure of 5 USD/kg most likely reflects a different mix or grade under the same code, not the same goods at a higher price.
Türkiye. Exports of this code to Russia are small: 56 k, 128 k and 43 k USD in June to August 2024. They are seasonal: September is the heaviest month (13% of the year), August the lightest (3%).
Coverage check. Count reporters per year: 24 countries in 2023, 18 in 2024, 8 in 2025. Part of the 2025 drop is likely missing reporters, not demand. Look at the stable core (China, Kazakhstan) before you quote a trend.
Restrictions. Two EU annexes cover the code (an import ban under Annex XXI and an industrial-capacity export ban under XXIII, text of 2026-07-24), and the Russian parallel-import list has entries for it. Read the annex text and its exceptions before drawing conclusions.
Buyers. About 1,700 active chemical-product makers (OKVED 20.59), 574 dry-mix makers (23.64) and 10,566 chemical wholesalers (46.75); Moscow, Saint Petersburg and the Nizhny Novgorod region lead (2,453, 925 and 774 active companies).

Step 7 is orientation

Treat the restriction lines as pointers to the annex and article; the full text is in /v1/docs/search and on the publisher's site.

Code¶

curlPythonJavaScript

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/products/382440?years=3"

body = get("/v1/products/382440", years=3)
d = body["data"]

for y in d["russia_imports_by_supplier"] or []:
    reporters = len(y["suppliers"]) + y["others"]["suppliers"]
    top = ", ".join(f'{s["reporter_iso2"]} {s["share"]:.0%}' for s in y["suppliers"][:3])
    print(y["year"], f'{y["total_value_usd"]/1e6:.1f} M USD', f"{reporters} reporters", top)

for block, why in d["notes"].items():
    print("note:", block, "-", why)
print([ (s["source_id"], s["as_of"]) for s in body["meta"]["sources"] ])

const body = await get("/v1/products/382440", { years: "3" });
const d = body.data;

for (const y of d.russia_imports_by_supplier ?? []) {
  const reporters = y.suppliers.length + y.others.suppliers;
  const top = y.suppliers.slice(0, 3).map((s) => `${s.reporter_iso2} ${(s.share * 100).toFixed(0)}%`).join(", ");
  console.log(y.year, `${(y.total_value_usd / 1e6).toFixed(1)} M USD`, `${reporters} reporters`, top);
}
for (const [block, why] of Object.entries(d.notes)) console.log("note:", block, "-", why);
console.log(body.meta.sources.map((s) => [s.source_id, s.as_of]));

Errors and edge cases¶

Case	Response
`hs6` not exactly 6 digits (`/v1/products/38244`, `/v1/products/38.2440`)	400 `hs6 must be exactly 6 digits`
`years` outside 1 to 20	400 `years must be between 1 and 20`
`years=abc`	400 `invalid or missing parameter(s): years`
Code with no trade data at all	200; blocks are `null` and `notes` lists the reasons
Code outside chapters 28 to 40	200; `buyers` is `null` with a note

Caveats to repeat when you publish¶

Supplier values are mirror data from the exporting countries and are incomplete in the latest year and months. Quote as_of from meta.sources and the number of reporters.
china_chapter_monthly is the whole chapter. Do not present it as this product's trade.
unit_prices is a blended average per country, not a price quote.
restrictions is a documentation aid. Quote the annex, article and consolidated_date.
meta.sources has no separate entry for the annual supplier block at present, so as_of values describe the monthly, China, TÜİK, restriction and company sources only.

Trade and product check¶

Parameters¶

Response at a glance¶

Where the numbers come from¶

How shares are computed¶

Block reference¶

russia_imports_by_supplier¶

monthly_suppliers¶

china_chapter_monthly¶

turkey_exports_monthly¶

unit_prices¶

seasonality¶

restrictions¶

buyers¶

notes¶

Worked reading of the 382440 response¶