단일 품목 무역 API 레퍼런스
한 국가의 HS 코드 하나에 대한 수출입을 모든 상대국과 함께 읽습니다. 상대국, 월, 흐름마다 행 하나이며 코드명이 함께 나옵니다.
개요
GET /
GET /는 한 국가의 HS 코드 하나에 대한 모든 상대국과의 무역을 반환합니다. 상대국, 월, 흐름마다 행 하나이며 코드명이 함께 나옵니다. hs는 2자리, 4자리 또는 6자리 코드입니다.
어느 상대국이 품목을 사고파는지 확인할 때 사용합니다. 상대국 경로와 같은 옵션을 받으며, hs를 지정한 상대국 요청도 같은 수치를 반환합니다.
HS 개정판에 없는 코드는 404 hs_를 반환합니다. MCP 도구는 trade_이며 동일한 매개변수를 받습니다.
요청
2026년 6월 영국과 미국 사이의 8517호(전화기 및 기타 데이터 송수신 기기)와 실제 응답:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products/8517?partner=USA&start=2026-06&end=2026-06"{
"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": "46135455"
},
{
"period": "2026-06",
"flow": "import",
"official_total": null,
"sum_of_rows": "89090099"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 2,
"product_code": "8517",
"product_level": 4,
"product_label": "Telephone sets, incl. telephones for cellular networks or for other wireless networks; other apparatus for the transmission or reception of voice, images or other data, incl. apparatus for communication in a wired or wireless network [such as a local or wide area network]; parts thereof (excl. than transmission or reception apparatus of heading 8443, 8525, 8527 or 8528)",
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "46135455",
"net_weight_kg": "74435",
"rank": null,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "89090099",
"net_weight_kg": "246068",
"rank": null,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}흐름마다 행이 하나씩 있습니다. totals에는 미국과의 8517호 합계, 즉 두 행의 합이 들어 있으며, 발행 기관이 품목 하나에 대한 합계를 게재하지 않으므로 official_은 null입니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 기본값 | 허용 값과 의미 |
|---|---|---|---|---|---|
country | 경로 | 문자열 | 예 | 없음 | 보고국의 ISO 3166-1 alpha-3 코드이며 대문자로 씁니다. 예: GBR. 국가가 아닌 코드는 400을 반환합니다. 수치가 없는 국가는 404 country_를 반환합니다. |
hs | 경로 | 문자열 | 예 | 없음 | 2자리, 4자리 또는 6자리 HS 코드. 예: 85, 8517, 851713. 다른 자릿수는 400을 반환합니다. HS 개정판에 이름이 없고 해당 국가에 행도 없는 코드는 404 hs_를 반환합니다. 태국은 4자리로 보유하고 있어, 태국에 6자리 코드를 보내면 404 basis_를 반환합니다. |
partner | 쿼리 | 문자열 | 아니요 | 모든 상대국 | 상대국 한 곳의 ISO 3166-1 alpha-3 코드이며 대문자로 씁니다. 해당 국가의 상대국이 아닌 코드는 400 unknown_를 반환합니다. |
flow | 쿼리 | 문자열 | 아니요 | 두 흐름 | export 또는 import. |
start | 쿼리 | 문자열, YYYY-MM | 아니요 | 보유한 가장 최신 월 | 첫 월이며 해당 월을 포함합니다. start만 있고 end가 없으면 응답은 보유한 가장 최신 월까지입니다. end보다 뒤인 start는 400을 반환합니다. |
end | 쿼리 | 문자열, YYYY-MM | 아니요 | 보유한 가장 최신 월 | 마지막 월이며 해당 월을 포함합니다. end만 있으면 응답은 그 월 또는 그 이전 중 보유한 가장 최신 월입니다. |
basis | 쿼리 | 문자열 | 아니요 | 보유한 최상의 출처 | own, third_ 또는 partner_. 출처 하나를 이름으로 지정하며 순서를 건너뜁니다. 해당 질의에 대한 행이 없는 출처는 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개월을 다룹니다. 상대국 보고 응답에는 사용할 수 없습니다. |
include_ | 쿼리 | 불리언 | 아니요 | false | true이면 EU나 ASEAN처럼 발행 기관이 게재하는 그룹 행도 함께 반환합니다. 그룹 행은 합계, 순위, 비중에 포함되지 않습니다. |
limit | 쿼리 | 정수 | 아니요 | 500 | 1에서 1000 사이. 한 페이지의 최대 행 수. |
cursor | 쿼리 | 문자열 | 아니요 | 없음 | 이전 페이지의 next_이며, 다른 매개변수는 그대로 둡니다. |
응답
응답에는 상대국 경로의 필드(해당 페이지에 나열)와 품목에 관한 다음 필드 3개가 있습니다. totals에는 해당 품목의 합계, 즉 모든 페이지에 걸친 행의 합이 들어 있으며 official_은 null입니다.
| 필드 | 의미 |
|---|---|
product_ | 요청한 HS 코드. |
product_ | 류는 2, 호는 4, 소호는 6. |
product_ | 코드명. HS 품목이 아닌 라인에서는 null이며, 예를 들어 칠레 발행 기관의 잔여 코드 999999는 행과 함께 응답합니다. |
rows의 각 항목은 한 월·흐름의 상대국 하나이며, 상대국 경로와 같은 필드를 가집니다.
| 필드 | 의미 |
|---|---|
flow | export 또는 import. |
period | 월, YYYY-MM. 연초 이후는 그 마지막 월. |
period_ | month 또는 year_. |
period_ | 행이 다루는 첫날과 마지막 날, YYYY-MM-DD. |
value | currency의 정수 단위, 십진수 문자열. |
net_ | 발행 기관이 제공하는 경우 킬로그램 단위의 순중량이며 십진수 문자열. 그 외에는 null. |
rank | top인 경우: 행의 순위이며 가장 큰 값이 1. 그 외에는 null. |
share | share인 경우: 합계에서 행이 차지하는 비율이며 소수 6자리. 그 외에는 null. |
change | change인 경우: previous_, previous_, absolute(값에서 이전 값을 뺀 값), percent(퍼센트 단위, 소수 4자리이며 이전 값이 0이면 null), release_, previous_(preliminary, revised, final, 발행 기관이 밝히지 않으면 null)를 가진 객체. 1년 전 행이 없거나 change를 요청하지 않았으면 null. |
partner | 상대국의 ISO 3166-1 alpha-3 코드, EUU 같은 그룹 코드, 또는 국가가 없는 라인이면 빈 값. |
partner_ | 발행 기관이 사용하는 상대국 이름. |
partner_ | country, group 또는 unallocated. |
unallocated_ | 미배분 행인 경우: not_, confidential, stores_, free_, other 또는 rest. 그 외에는 null. |
추가 예시
개정판에 없는 코드
이름도 행도 없는 HS 코드는 404를 반환하며 무료입니다:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products/999999?start=2026-06&end=2026-06&flow=export&limit=3"{
"type": "https://narwhalapi.com/problems/hs-code-not-found",
"title": "HS code not found",
"status": 404,
"detail": "HS 2022 has no code 999999.",
"code": "hs_code_not_found",
"request_id": "16a6db4e-d5d6-45ee-954b-4512cf137e63"
}출처
다음 순서에서 행을 가진 첫 번째 출처가 요청마다 응답합니다. 해당 국가의 자체 관세청 또는 통계청(basis는 own), UN Comtrade에 제출한 해당 국가의 자체 보고(third_, 상대국 합계만), 그다음 수출입 방향을 맞바꾼 다른 국가의 보고(partner_)입니다. 다른 국가의 보고는 해당 국가에 대해 행을 가진 보고국이 200곳 이상일 때만 UN Comtrade보다 앞서는데, 이는 Narwhal이 보유한 수보다 많으므로 가장 마지막에 옵니다. 품목별로는 UN Comtrade에 자료가 없으므로 순서는 own, 그다음 partner_이며, partner_는 류(2자리)까지만 제공합니다. basis로 출처 하나를 이름으로 지정할 수 있습니다. 응답의 basis, source, note 필드가 어느 출처가 응답했는지 알려 주며, 출처는 한 응답에서 절대 섞이지 않습니다. 상대국 보고 응답은 해당 국가 자체 수치와 다른 측정값이며 공식 수치가 아닙니다. 상대국 보고 응답은 류까지만 제공하므로, 자국 기관이 상대국 합계만 제공하는 국가에서 4자리 또는 6자리 코드는 404 basis_을 반환합니다.
통화
값은 currency에 명시된 통화의 정수 단위이며 십진수 문자열로 표기합니다. 기본값은 출처가 발표하는 통화로, 예를 들어 영국 세입관세청(HM Revenue & Customs)은 GBP입니다. currency=USD는 해당 월의 일별 환율 평균으로 월마다 환산합니다. 월별 적용 환율은 fx에 나열되며, calculated는 환산된 필드를 표시합니다. 환율이 없는 월은 404 rate_을 반환합니다. 환율 출처가 응답할 수 없으면 503 upstream_을 반환합니다. 이미 USD인 응답은 그대로 반환됩니다.
페이징
limit은 한 페이지의 최대 행 수를 1에서 1000 사이로 정하며 기본값은 500입니다. 일치하는 행이 더 있으면 next_에 다음 페이지의 커서가 들어 있으며, 다른 매개변수는 그대로 두고 cursor로 보냅니다. 다른 요청의 커서는 400 invalid_를 반환합니다. total은 모든 페이지에 걸쳐 일치하는 행 수입니다. MCP 도구는 한 결과에 최대 200행을 반환합니다.
가격
행을 하나 이상 반환하는 요청은 호출 1회이며, 1,000회 호출당 $2입니다. 긴 응답의 각 페이지는 limit과 관계없이 호출 1회입니다. 행이 없는 응답은 무료이고, 모든 오류도 무료입니다.
오류
이 오류는 request_가 포함된 공통 problem 형식을 사용합니다. 키가 없거나 유효하지 않은 경우(401), 잔액이 호출 요금보다 적은 경우(402), 분당 요청이 너무 많은 경우(429)는 모든 경로가 공통으로 가지는 계정 오류입니다. 자세한 내용은 API 오류 코드와 크레딧을 참고하세요.
| 상태 | 코드 | 발생 조건 |
|---|---|---|
400 | invalid_query | 매개변수가 누락되었거나 형식이 잘못되었거나 허용 값을 벗어난 경우입니다. 예를 들어 start=2026-13, end보다 뒤인 start, start와 함께 보낸 ytd, 또는 보낸 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 | hs_code_not_found | HS 개정판에 해당 코드의 이름이 없고 국가에도 해당 코드의 행이 없는 경우입니다. 예를 들어 영국과 코드 999999는 HS 2022 has no code 999999.를 반환합니다. 국가의 파일에는 있으나 이름이 없는 코드(발행 기관의 잔여 라인)는 product_ null과 함께 200을 반환합니다. |
404 | rate_not_available | currency=USD를 요청했는데 어떤 월에 환율이 없습니다. |
503 | upstream_unavailable | 환율 출처가 응답할 수 없습니다. currency=USD와 환산이 필요한 상대국 보고 응답에 영향을 줍니다. 잠시 후 다시 시도하세요. |
503 | trade_data_unavailable | 지금은 품목 파일을 읽을 수 없습니다. 잠시 후 다시 시도하세요. |
이 페이지가 도움이 되었나요?