品目別貿易APIリファレンス
1つの国の輸出入を、2桁、4桁、6桁のHS品目別に読み取ります。コード、月、方向ごとに1行で、各コードの名称が付きます。
概要
GET /
GET / は、1つの国の財貿易を品目別に返します。HSコード、月、方向ごとに1行で、コードの名称が付きます。level は深さを選びます。2 は類(デフォルト)、4 は項、6 は号です。start と end がない場合、回答は保有する最新の月です。
partner は回答を1つのパートナー国に絞り、hs はその桁で始まるコードに絞ります。国が何を売り、何を買っているかを調べるために使います。1つの品目を全パートナー国と対比するには、1品目ルートを使います。
その国自身の機関がパートナー国の合計のみを提供する場合(カナダ、メキシコ、オーストラリア)、品目ルートは類については他国の報告から回答し、partner_ と表示します。項と号には404 basis_ が返ります。MCPツールは trade_ で、同じパラメータを受け付けます。
リクエスト
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"{
"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_ が返ります。 |
level | クエリ | 整数 | いいえ | 2 | 2(類)、4(項)、6(号)。他の値には400が返ります。タイは4桁で保有しているため、タイに 6 を指定すると404 basis_ が返ります。 |
partner | クエリ | 文字列 | いいえ | すべてのパートナー国 | このパートナー国との貿易のみ(ISO 3166-1 alpha-3、大文字)。その国のパートナー国ではないコードには、400 unknown_ が返ります。 |
flow | クエリ | 文字列 | いいえ | 両方向 | export または import。 |
start | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最初の月(含む)。start のみで end がない場合、回答は保有する最新の月までです。start が end より後の場合は400が返ります。 |
end | クエリ | 文字列、YYYY-MM | いいえ | 保有する最新の月 | 最後の月(含む)。end のみの場合、回答はそれ以前で保有する最新の月です。 |
hs | クエリ | 文字列、1〜6桁 | いいえ | すべてのコード | これらの桁で始まるコードのみ。level より長い場合は400が返ります。 |
basis | クエリ | 文字列 | いいえ | 保有する最良のソース | own、third_、partner_。ソースを名前で1つ指定し、順序をスキップします。問い合わせに該当する行がないソースには、404 basis_ が返ります。 |
currency | クエリ | 文字列 | いいえ | ソース自身の通貨 | USD。各月を日次レートの平均で換算します。 |
top | クエリ | 整数 | いいえ | すべての行 | 1〜1000。各月・各方向について、値の大きい順に上位N行の品目の行を残し、同順位は品目コードで決め、各行に rank を追加します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
share | クエリ | ブール値 | いいえ | false | true を指定すると、各行に share を追加します。同じ月と方向のすべての品目の行の合計に対するその行の値を、小数点以下6桁の1に対する割合で表します。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
ytd | クエリ | ブール値 | いいえ | false | true を指定すると、1月から end(デフォルトは最新の月)までを保存済みの月から合算し、period_ は year_ になります。start ではなく end を送ってください。start を指定すると400が返ります。月が欠けている場合は404 period_ が返ります。算出値です。パートナー国報告の回答には使えません。 |
change | クエリ | ブール値 | いいえ | false | true を指定すると、各行に change を追加します。1年前の同じ月(または年初来)と、その差、および両側の公表状況を示します。1年前の月が欠けている場合は404 period_ が返ります。算出値です。最大12か月までです。パートナー国報告の回答には使えません。 |
limit | クエリ | 整数 | いいえ | 500 | 1〜1000。1ページの最大行数。 |
cursor | クエリ | 文字列 | いいえ | なし | 前のページの next_。他のパラメータは変更しません。 |
レスポンス
回答には、パートナー国ルートのフィールド(そのページに掲載)に加えて、パートナー国の絞り込みについての1つがあります。
| フィールド | 意味 |
|---|---|
country | 回答の対象である報告国のISO 3166-1 alpha-3コード。 |
partner | 行が絞り込まれているパートナー国。partner が送られなかった場合は null。 |
basis | 回答したソース:own、third_(UN Comtrade)、partner_。 |
source | 公表元。例:HM Revenue & Customs、Eurostat Comext、UN Comtrade、Customs reports of other countries。 |
reporters_ | partner_ の場合:回答に入れ替えて反映された報告の報告国の count と countries。他のソースでは null。 |
note | 数値を使う前にお読みください。パートナー国報告の回答に設定され、それ以外は null です。 |
coverage | full または partial。パートナー国報告の回答は partial です。 |
partner_ | すべてのパートナー国が掲載される場合は all、公表元が上位のパートナー国と残りの1行のみを表示する場合は top_。パートナー国報告の回答では null。 |
scope | goods。 |
currency | 回答内のすべての値のISO 4217コード。 |
classification | HS(Harmonized System)。 |
edition | 指定したすべての月を1つの版が対象とする場合のHS版(2007、2012、2017、2022)。月によって異なる場合は null で、各行にそれぞれの版が示されます。 |
edition_ | 公表元が版を示している場合は as_、Narwhalが年から割り出した場合は inferred_。 |
valuation_ | 公表元が貿易をどのように評価しているか。例:輸出はFOB、輸入はCIF。示されていない場合は not_。 |
trade_ | 公表元が示している場合は general または special。それ以外は not_。 |
partner_ | パートナー国が、公表元が示すとおりに、原産地、積出地、仕向地のどれで数えられているか。示されていない場合は not_。 |
trade_ | 数値が何を対象としているか。例:all_、extra_、intra_。 |
latest_ | Narwhalがこの国とソースについて保有する最新の月。 |
total_ | official_ の基準:customs、balance_、eurostat_。公表元が合計を示していない場合は null。 |
totals | 月と方向ごとに1項目:period、flow、official_(公表元自身の財の合計。存在しない場合は null)、sum_(その月と方向について、グループ行を除くすべてのパートナー国の行の合計。算出値)。hs がない場合は、partner が行を絞り込む場合も含め、その月の財の合計全体を保持します。hs がある場合(および1品目ルートでは)、代わりにその品目の合計を保持します。sum_ は、回答の全ページの行の合計(partner が指定されていればその国の行。top とページングでは減りません)で、公表元は1つの品目の合計を表示しないため、official_ は null です。 |
fx | currency=USD の場合、および複数の通貨にまたがるパートナー国報告の回答の場合:各月に使われたレート。period、from_、to_、rate、平均に使った days を含みます。それ以外は null。 |
calculated | Narwhalが算出したフィールドの名前。例:sum_、rank、share、value、official_。 |
total | 全ページにわたる、一致する行数。 |
next_ | 次のページのカーソル。最後のページでは null。 |
rows の各項目は、1つのHSコードの、1つの月と方向です。
| フィールド | 意味 |
|---|---|
flow | export または import。 |
period | 月(YYYY-MM)。年初来の場合は、その最後の月。 |
period_ | month または year_。 |
period_ | その行が対象とする最初の日と最後の日(YYYY-MM-DD)。 |
value | currency の整数単位。小数の文字列です。 |
net_ | 公表元が提供している場合の、キログラム単位の正味重量。それ以外は null。 |
rank, share, change | パートナー国ルートと同じです。top、share、change を指定した場合に設定され、それ以外は null。 |
product_ | HSコード(2桁、4桁、6桁)。HS品目ではない公表元独自の行は、公表元のコードのままです。例:船用品と個人向けの貨物の 00。 |
product_ | 類は 2、項は 4、号は 6。 |
product_ | コードの名称。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"{
"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_ が設定されています。totals は9つの号の合計を保持し、official_ は 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"{
"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_、パートナー国の合計のみ)、次に、その国について他国が報告した内容で方向を入れ替えたもの(partner_)。他国の報告がUN Comtradeより先になるのは、その国について200以上の報告国が行を持つ場合に限られますが、これはNarwhalが保有する数を上回るため、最後になります。品目別では、UN Comtradeは何も保有していないため、順序は own、次に partner_ で、partner_ は類(2桁)までしか届きません。basis はソースを名前で1つ求めます。回答の basis、source、note フィールドが、どのソースが回答したかを示し、ソースが1つの回答の中で混在することはありません。パートナー国報告の回答は、その国自身の数値とは別の測定であり、公式の数値ではありません。船用品や個人向けの貨物など、HS品目ではない公表元独自の行は、公表元のコード(類のレベルでは 00、号のレベルでは 999999)のまま、product_ を null として返ります。HSコードのルート(/)はこれらのコードを知らず、これらには404を返します。1品目ルート(/)は、これらを行つきで、product_ を null として返します。
通貨
値は currency に示される通貨の整数単位で、小数の文字列で表されます。デフォルトでは、ソースが公表している通貨です。例:英国歳入関税庁(HM Revenue & Customs)ではGBP。currency=USD は、各月をその月の日次為替レートの平均で換算します。月ごとに使用したレートは fx に挙がり、calculated が換算したフィールドを示します。レートのない月には404 rate_ が返ります。為替レートのソースが回答できない場合は、503 upstream_ が返ります。すでにUSDの回答は、そのまま返されます。
ページング
limit は1ページの最大行数を1〜1000で指定し、デフォルトは500です。さらに行が一致する場合、next_ に次のページのカーソルが入ります。他のパラメータは変えずに、それを cursor として送ってください。別のリクエストのカーソルを使うと400 invalid_ が返ります。total は、全ページにわたる一致行数を数えます。MCPツールは1回の結果で最大200行を返します。
価格
1行以上を返すリクエストは1回の呼び出しで、1,000回あたり$2です。長い回答の各ページは、limit にかかわらず1回の呼び出しです。行のない回答は無料で、すべてのエラーも無料です。
エラー
これらのエラーは、request_ を含む共通のエラー形式で返されます。キーがない、または無効な場合(401)、残高が呼び出しの料金に満たない場合(402)、1分あたりのリクエストが多すぎる場合(429)は、すべてのルートに共通するアカウントのエラーです。APIエラーとクレジットを参照してください。
| ステータス | コード | 発生する場面 |
|---|---|---|
400 | invalid_query | パラメータが不足している、形式が不正、または許容値の範囲外の場合。例:level=3、start=2026-13、end より後の start、start と併せて送られた ytd、level より長い hs、送られた as_ または version(これらのルートは現在保有している内容を返します)。パートナー国報告の回答に top、share、ytd、change を求めた場合も同様です。 |
400 | invalid_cursor | カーソルがこのリクエストが返したものではない、またはその後に別のパラメータが変更された場合。 |
400 | unknown_partner | partner が、指定した月においてその国のパートナー国ではない場合。例:ZZZ is not a partner of GBR. |
400 | range_too_large | top、share、ytd、change が12か月を超える場合、パートナー国報告の回答が12か月を超える場合、または、あらゆるレベル(2桁、4桁、6桁)の品目の回答が、hs も partner もなしに、保有する12か月を超える場合。オープンクエリは、12か月を超える期間を invalid_ として拒否します。 |
404 | country_not_covered | Narwhalは、どのソースにもその国の貿易の行を保有していません。 |
404 | period_not_published | 指定した月が保有されていない場合(No trade rows for 2026-10.)、または ytd や change に必要な月が欠けている場合。 |
404 | basis_not_available | 求められたソース、または順序内のすべてのソースが、その問い合わせに該当するものを何も保有していない場合。detail に理由が示されます。例:その国自身の機関がパートナー国の合計のみで品目を提供していない場合や、パートナー国報告の回答が類(2桁)までしか届かない場合や、タイ自身の機関が4桁で保有しているのに6桁を求められた場合。カバレッジルートを参照してください。 |
404 | rate_not_available | currency=USD が求められ、ある月の為替レートがない場合。 |
503 | upstream_unavailable | 為替レートのソースが回答できません。currency=USD と、換算が必要なパートナー国報告の回答に影響します。しばらくしてからもう一度お試しください。 |
503 | trade_data_unavailable | 品目ファイルを現在読み取れません。しばらくしてからもう一度お試しください。 |
このページは役に立ちましたか?