すべてのドキュメントを閲覧

品目別貿易APIリファレンス

1つの国の輸出入を、2桁、4桁、6桁のHS品目別に読み取ります。コード、月、方向ごとに1行で、各コードの名称が付きます。

概要

GET /v1/trade/{country}/products

GET /v1/trade/{country}/products は、1つの国の財貿易を品目別に返します。HSコード、月、方向ごとに1行で、コードの名称が付きます。level は深さを選びます。2 は類(デフォルト)、4 は項、6 は号です。start と end がない場合、回答は保有する最新の月です。

partner は回答を1つのパートナー国に絞り、hs はその桁で始まるコードに絞ります。国が何を売り、何を買っているかを調べるために使います。1つの品目を全パートナー国と対比するには、1品目ルートを使います。

その国自身の機関がパートナー国の合計のみを提供する場合(カナダ、メキシコ、オーストラリア)、品目ルートは類については他国の報告から回答し、partner_reported と表示します。項と号には404 basis_not_available が返ります。MCPツールは trade_get_products で、同じパラメータを受け付けます。

リクエスト

2026年6月の英国の輸出上位3つの類を構成比つきで示し、実際のレスポンスを添えます:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?start=2026-06&end=2026-06&flow=export&top=3&share=true"
英国、輸出上位3つの類
{
  "country": "GBR",
  "basis": "own",
  "source": "HM Revenue & Customs",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "GBP",
  "classification": "HS",
  "edition": "2022",
  "edition_basis": "inferred_from_year",
  "valuation_basis": "not_stated",
  "trade_system": "not_stated",
  "partner_basis": "not_stated",
  "trade_scope": "all_partners",
  "latest_period": "2026-09",
  "total_basis": "customs",
  "totals": [
    {
      "period": "2026-06",
      "flow": "export",
      "official_total": "37649508686",
      "sum_of_rows": "37649508686"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows",
    "rank",
    "share"
  ],
  "total": 3,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7115661421",
      "net_weight_kg": "195511199",
      "rank": 1,
      "share": "0.188997",
      "change": null,
      "product_code": "84",
      "product_level": 2,
      "product_label": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES; PARTS THEREOF",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7044982137",
      "net_weight_kg": "1706268",
      "rank": 2,
      "share": "0.187120",
      "change": null,
      "product_code": "71",
      "product_level": 2,
      "product_label": "NATURAL OR CULTURED PEARLS, PRECIOUS OR SEMI-PRECIOUS STONES, PRECIOUS METALS, METALS CLAD WITH PRECIOUS METAL, AND ARTICLES THEREOF; IMITATION JEWELLERY; COIN",
      "edition": "2022"
    }
  ],
  "next_cursor": null
}

ページには3行のうち最初の2行を示しています。share は1に対する割合です。類84は、その月の輸出の0.189134です。行が1つのパートナー国に絞られていないため、partner は null です。

パラメータ

パラメータ場所種別必須デフォルト許容値と意味
countryパス文字列はいなし報告国のISO 3166-1 alpha-3コード(大文字)。例:GBR。国ではないコードには400が返ります。数値のない国には404 country_not_covered が返ります。
levelクエリ整数いいえ22(類)、4(項)、6(号)。他の値には400が返ります。タイは4桁で保有しているため、タイに 6 を指定すると404 basis_not_available が返ります。
partnerクエリ文字列いいえすべてのパートナー国このパートナー国との貿易のみ(ISO 3166-1 alpha-3、大文字)。その国のパートナー国ではないコードには、400 unknown_partner が返ります。
flowクエリ文字列いいえ両方向export または import。
startクエリ文字列、YYYY-MMいいえ保有する最新の月最初の月(含む)。start のみで end がない場合、回答は保有する最新の月までです。start が end より後の場合は400が返ります。
endクエリ文字列、YYYY-MMいいえ保有する最新の月最後の月(含む)。end のみの場合、回答はそれ以前で保有する最新の月です。
hsクエリ文字列、1〜6桁いいえすべてのコードこれらの桁で始まるコードのみ。level より長い場合は400が返ります。
basisクエリ文字列いいえ保有する最良のソースown、third_party、partner_reported。ソースを名前で1つ指定し、順序をスキップします。問い合わせに該当する行がないソースには、404 basis_not_available が返ります。
currencyクエリ文字列いいえソース自身の通貨USD。各月を日次レートの平均で換算します。
topクエリ整数いいえすべての行1〜1000。各月・各方向について、値の大きい順に上位N行の品目の行を残し、同順位は品目コードで決め、各行に rank を追加します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
shareクエリブール値いいえfalsetrue を指定すると、各行に share を追加します。同じ月と方向のすべての品目の行の合計に対するその行の値を、小数点以下6桁の1に対する割合で表します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
ytdクエリブール値いいえfalsetrue を指定すると、1月から end(デフォルトは最新の月)までを保存済みの月から合算し、period_type は year_to_date になります。start ではなく end を送ってください。start を指定すると400が返ります。月が欠けている場合は404 period_not_published が返ります。算出値です。パートナー国報告の回答には使えません。
changeクエリブール値いいえfalsetrue を指定すると、各行に change を追加します。1年前の同じ月(または年初来)と、その差、および両側の公表状況を示します。1年前の月が欠けている場合は404 period_not_published が返ります。算出値です。最大12か月までです。パートナー国報告の回答には使えません。
limitクエリ整数いいえ5001〜1000。1ページの最大行数。
cursorクエリ文字列いいえなし前のページの next_cursor。他のパラメータは変更しません。

レスポンス

回答には、パートナー国ルートのフィールド(そのページに掲載)に加えて、パートナー国の絞り込みについての1つがあります。

フィールド意味
country回答の対象である報告国のISO 3166-1 alpha-3コード。
partner行が絞り込まれているパートナー国。partner が送られなかった場合は null。
basis回答したソース:own、third_party(UN Comtrade)、partner_reported。
source公表元。例:HM Revenue & Customs、Eurostat Comext、UN Comtrade、Customs reports of other countries。
reporters_includedpartner_reported の場合:回答に入れ替えて反映された報告の報告国の count と countries。他のソースでは null。
note数値を使う前にお読みください。パートナー国報告の回答に設定され、それ以外は null です。
coveragefull または partial。パートナー国報告の回答は partial です。
partner_coverageすべてのパートナー国が掲載される場合は all、公表元が上位のパートナー国と残りの1行のみを表示する場合は top_n。パートナー国報告の回答では null。
scopegoods。
currency回答内のすべての値のISO 4217コード。
classificationHS(Harmonized System)。
edition指定したすべての月を1つの版が対象とする場合のHS版(2007、2012、2017、2022)。月によって異なる場合は null で、各行にそれぞれの版が示されます。
edition_basis公表元が版を示している場合は as_published、Narwhalが年から割り出した場合は inferred_from_year。
valuation_basis公表元が貿易をどのように評価しているか。例:輸出はFOB、輸入はCIF。示されていない場合は not_stated。
trade_system公表元が示している場合は general または special。それ以外は not_stated。
partner_basisパートナー国が、公表元が示すとおりに、原産地、積出地、仕向地のどれで数えられているか。示されていない場合は not_stated。
trade_scope数値が何を対象としているか。例:all_partners、extra_union_only、intra_union_other_method。
latest_periodNarwhalがこの国とソースについて保有する最新の月。
total_basisofficial_total の基準:customs、balance_of_payments、eurostat_concept。公表元が合計を示していない場合は null。
totals月と方向ごとに1項目:period、flow、official_total(公表元自身の財の合計。存在しない場合は null)、sum_of_rows(その月と方向について、グループ行を除くすべてのパートナー国の行の合計。算出値)。hs がない場合は、partner が行を絞り込む場合も含め、その月の財の合計全体を保持します。hs がある場合(および1品目ルートでは)、代わりにその品目の合計を保持します。sum_of_rows は、回答の全ページの行の合計(partner が指定されていればその国の行。top とページングでは減りません)で、公表元は1つの品目の合計を表示しないため、official_total は null です。
fxcurrency=USD の場合、および複数の通貨にまたがるパートナー国報告の回答の場合:各月に使われたレート。period、from_currency、to_currency、rate、平均に使った days を含みます。それ以外は null。
calculatedNarwhalが算出したフィールドの名前。例:sum_of_rows、rank、share、value、official_total。
total全ページにわたる、一致する行数。
next_cursor次のページのカーソル。最後のページでは null。

rows の各項目は、1つのHSコードの、1つの月と方向です。

フィールド意味
flowexport または import。
period月(YYYY-MM)。年初来の場合は、その最後の月。
period_typemonth または year_to_date。
period_start, period_endその行が対象とする最初の日と最後の日(YYYY-MM-DD)。
valuecurrency の整数単位。小数の文字列です。
net_weight_kg公表元が提供している場合の、キログラム単位の正味重量。それ以外は null。
rank, share, changeパートナー国ルートと同じです。top、share、change を指定した場合に設定され、それ以外は null。
product_codeHSコード(2桁、4桁、6桁)。HS品目ではない公表元独自の行は、公表元のコードのままです。例:船用品と個人向けの貨物の 00。
product_level類は 2、項は 4、号は 6。
product_labelコードの名称。HS品目ではない行では null。
editionその月のソースのHS版。報告国が異なる版を使っている場合は null。

その他の例

1つの項の号

英国の輸出における項8517の下の6桁コード、最初のページ(5行):

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?level=6&hs=8517&start=2026-06&end=2026-06&flow=export&limit=5"
英国、8517の号
{
  "country": "GBR",
  "basis": "own",
  "source": "HM Revenue & Customs",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "GBP",
  "classification": "HS",
  "edition": "2022",
  "edition_basis": "inferred_from_year",
  "valuation_basis": "not_stated",
  "trade_system": "not_stated",
  "partner_basis": "not_stated",
  "trade_scope": "all_partners",
  "latest_period": "2026-09",
  "total_basis": "customs",
  "totals": [
    {
      "period": "2026-06",
      "flow": "export",
      "official_total": null,
      "sum_of_rows": "427312411"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 9,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "2578425",
      "net_weight_kg": "12393",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851711",
      "product_level": 6,
      "product_label": "Line telephone sets with cordless handsets",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "105530961",
      "net_weight_kg": "115108",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851713",
      "product_level": 6,
      "product_label": "Smartphones for wireless networks",
      "edition": "2022"
    }
  ],
  "next_cursor": "eyJiIjoiY2hhbmdlPUZhbHNlfGNvdW50cnk9R0JSfGVuZD0yMDI2LTA2fGZsb3c9ZXhwb3J0fGhzPTg1MTd8bGV2ZWw9NnxzaGFyZT1GYWxzZXxzdGFydD0yMDI2LTA2fHl0ZD1GYWxzZSIsIm8iOjV9"
}

ページには5行のうち最初の2行を示しています。total は9なので、next_cursor が設定されています。totals は9つの号の合計を保持し、official_total は null です。

パートナー国の合計のみを提供する国の項

カナダ自身の機関は品目を提供しません。項を求めるリクエストには404が返り、無料です:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/products?level=4&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
カナダ、類85の項
{
  "type": "https://narwhalapi.com/problems/basis-not-available",
  "title": "Basis not available",
  "status": 404,
  "detail": "Narwhal holds CAN's own partner totals only, not its products; UN Comtrade is held as partner totals only, not by product; partner-reported products are held at chapter level only (level=2). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "5dd0f449-8c1e-4354-9af6-d8a76a5eefdd"
}

ソース

各リクエストには1つのソースが回答します。この順序で、行を保有する最初のソースです。その国自身の税関または統計機関(basis は own)、その国自身のUN Comtradeへの申告(third_party、パートナー国の合計のみ)、次に、その国について他国が報告した内容で方向を入れ替えたもの(partner_reported)。他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_reported で、partner_reported は類(2桁)までしか届きません。basis はソースを名前で1つ求めます。回答の basis、source、note フィールドが、どのソースが回答したかを示し、ソースが1つの回答の中で混在することはありません。パートナー国報告の回答は、その国自身の数値とは別の測定であり、公式の数値ではありません。船用品や個人向けの貨物など、HS品目ではない公表元独自の行は、公表元のコード(類のレベルでは 00、号のレベルでは 999999)のまま、product_label を null として返ります。HSコードのルート(/v1/trade/hs-codes)はこれらのコードを知らず、これらには404を返します。1品目ルート(/v1/trade/{country}/products/{hs})は、これらを行つきで、product_label を null として返します。

通貨

値は currency に示される通貨の整数単位で、小数の文字列で表されます。デフォルトでは、ソースが公表している通貨です。例:英国歳入関税庁(HM Revenue & Customs)ではGBP。currency=USD は、各月をその月の日次為替レートの平均で換算します。月ごとに使用したレートは fx に挙がり、calculated が換算したフィールドを示します。レートのない月には404 rate_not_available が返ります。為替レートのソースが回答できない場合は、503 upstream_unavailable が返ります。すでにUSDの回答は、そのまま返されます。

ページング

limit は1ページの最大行数を1〜1000で指定し、デフォルトは500です。さらに行が一致する場合、next_cursor に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_cursor が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。

価格

1行以上を返すリクエストは1回の呼び出しで、1,000回あたり$2です。長い回答の各ページは、limit にかかわらず1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料です。

エラー

これらのエラーは、request_id を含む共通のエラー形式で返されます。キーがない、または無効な場合(401)、残高が呼び出しの料金に満たない場合(402)、1分あたりのリクエストが多すぎる場合(429)は、すべてのルートに共通するアカウントのエラーです。APIエラーとクレジットを参照してください。

ステータスコード発生する場面
400invalid_queryパラメータが不足している、形式が不正、または許容値の範囲外の場合。例:level=3、start=2026-13、end より後の start、start と併せて送られた ytd、level より長い hs、送られた as_of または version(これらのルートは現在保有している内容を返します)。パートナー国報告の回答に top、share、ytd、change を求めた場合も同様です。
400invalid_cursorカーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。
400unknown_partnerpartner が、指定した月においてその国のパートナー国ではない場合。例:ZZZ is not a partner of GBR.
400range_too_largetop、share、ytd、change が12か月を超える場合、パートナー国報告の回答が12か月を超える場合、または、あらゆるレベル(2桁、4桁、6桁)の品目の回答が、hs も partner もなしに、保有する12か月を超える場合。オープンクエリは、12か月を超える期間を invalid_query として拒否します。
404country_not_coveredNarwhalは、どのソースにもその国の貿易の行を保有していません。
404period_not_published指定した月が保有されていない場合(No trade rows for 2026-10.)、または ytd や change に必要な月が欠けている場合。
404basis_not_available求められたソース、または順序内のすべてのソースが、その問い合わせに該当するものを何も保有していない場合。detail に理由が示されます。例:その国自身の機関がパートナー国の合計のみで品目を提供していない場合や、パートナー国報告の回答が類(2桁)までしか届かない場合や、タイ自身の機関が4桁で保有しているのに6桁を求められた場合。カバレッジルートを参照してください。
404rate_not_availablecurrency=USD が求められ、ある月の為替レートがない場合。
503upstream_unavailable為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。
503trade_data_unavailable品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。

APIエラーとクレジット · 貿易データAPIリファレンス · 貿易の対象国

このページは役に立ちましたか?