무역 데이터 API 레퍼런스
Narwhal이 직접 보유한 국가는 해당 국가의 관세청 또는 통계청 자료로, 나머지 국가는 UN Comtrade 또는 다른 국가의 보고 자료로 상대국별·HS 품목별 상품 무역을 월 단위로 조회합니다.
개요
무역 데이터 API는 상대국별·품목별 상품 무역을 한 번에 한 달씩 반환합니다. 행 하나는 한 달 동안의 한 흐름(수출 또는 수입)이며, 상대국 또는 품목과 통화의 정수 단위 값이 들어 있습니다. 품목은 Harmonized System(HS)의 2자리, 4자리, 6자리 분류를 따릅니다. 이력은 출처가 공개하는 경우 2010년 1월부터 시작합니다. 이 API는 상품만 다룹니다.
수치는 Narwhal이 보유한 보고국의 관세청 또는 통계청에서, 그리고 제공 범위 목록에 있는 181개국 중 나머지는 UN Comtrade 또는 다른 국가의 보고에서 가져옵니다. 모든 응답에 어떤 출처에서 나왔는지 표시됩니다. 어느 국가가 어느 출처로 응답하는지는 무역 국가 페이지에서 확인할 수 있습니다.
응답하는 경로는 7개이며 모두 / 아래에 있고, 각 경로는 동일한 매개변수와 동일한 응답을 가진 MCP 도구이기도 합니다. 각 요청은 Narwhal의 다른 API와 같이 Authorization: Bearer 헤더에 키를 담아 보냅니다.
경로
| 경로 | MCP 도구 | 응답 내용 |
|---|---|---|
GET / | trade_ | 한 국가의 상대국별 수출입. |
GET / | trade_ | 한 국가의 HS 품목별 수출입(2자리, 4자리 또는 6자리). |
GET / | trade_ | 한 국가의 HS 코드 하나에 대한 모든 상대국과의 무역. |
GET / | trade_ | 여러 보고국, 상대국, 류에 걸친 자유 쿼리. |
GET / | trade_ | 국가별 응답 출처와 보유 월. 무료. |
GET / | trade_ | 이름, 단계 또는 상위 코드로 HS 코드를 검색하거나 나열. |
GET / | trade_ | HS 코드 하나와 그 상위 코드 및 하위 코드. |
각 경로에는 전용 페이지가 있으며, 모든 매개변수와 실제 응답이 담긴 작동하는 요청, 모든 오류가 실려 있습니다.
출처
각 응답은 basis와 source에 명시된 하나의 출처에서 나옵니다. basis 없이 요청하면 다음 순서에서 행을 가진 첫 번째 출처를 사용합니다. 출처는 한 응답에서 절대 섞이지 않으며, basis로 출처 하나를 이름으로 지정할 수 있습니다.
basis | 출처 | 의미 | 도달 |
|---|---|---|---|
own | 해당 국가의 관세청 또는 통계청 | 기관이 발표한 그대로의 자체 수치이며, 자체 통화로 제공합니다. | 상대국, 그리고 기관이 제공하는 경우 2자리, 4자리, 6자리 품목 |
third_ | UN Comtrade | 해당 국가가 유엔에 제출한 월간 자체 보고 자료이며, 출처를 명시해 제공합니다. | 상대국 합계만 |
partner_ | 다른 국가의 세관 보고 | 다른 국가가 해당 국가에 대해 보고한 내용으로, 수출입 방향이 맞바뀝니다. 즉 다른 국가의 해당 국가로부터의 수입이 해당 국가의 수출이 됩니다. 다른 방식의 측정값이며 공식 수치가 아닙니다. | 상대국, 그리고 2자리 품목 |
다른 국가의 보고는 해당 국가에 대해 행을 가진 보고국이 200곳 이상일 때만 UN Comtrade보다 앞서는데, 이는 Narwhal이 보유한 수보다 많으므로 가장 마지막에 옵니다. 품목별로는 UN Comtrade에 자료가 없으므로 순서는 own, 그다음 partner_입니다. 상대국 보고 응답은 공식 합계가 없고 top, share, ytd, change를 받지 않으며 최대 12개월만 다룹니다. GET /는 현재 각 국가에 응답하는 출처인 answers_를 보여줍니다.
어느 국가가 어느 출처로 응답하는지는 다음과 같습니다: 무역 국가.
통화
값은 currency에 명시된 통화의 정수 단위이며 십진수 문자열입니다. 기본값은 출처가 발표하는 통화입니다. currency=USD를 지정하면 해당 월의 일별 환율 평균으로 월마다 환산하고, 월별 적용 환율을 fx에 나열하며, 환산된 필드를 calculated에 표시합니다. 보고국마다 발표 통화가 다르므로 자유 쿼리 경로는 각 행에 통화를 명시합니다.
페이징
limit은 한 페이지의 최대 행 수를 1에서 1000 사이로 정합니다. 상대국, 품목, 단일 품목, 자유 쿼리 경로에서는 기본값이 500이고 GET /에서는 100입니다. 일치하는 행이 더 있으면 next_에 다음 페이지의 커서가 들어 있으며, 다른 매개변수는 그대로 두고 이를 cursor로 보냅니다. 다른 요청의 커서는 400 invalid_를 반환합니다. total은 모든 페이지에 걸쳐 일치하는 행 수입니다. MCP 도구는 한 결과에 최대 200행을 반환합니다.
가격
무역 API 호출은 1,000회 호출당 $2입니다. 행을 하나 이상 반환하는 요청은 호출 1회이며, 긴 응답의 각 페이지도 호출 1회입니다. 행이 없는 응답은 무료이고, 모든 오류도 무료이며, 제공 범위 경로도 무료입니다. 크레딧과 충전은 요금 페이지를 참고하세요.
오류
오류는 request_가 포함된 공통 problem 형식을 사용합니다. 각 경로 페이지에는 해당 경로가 반환할 수 있는 오류가 나와 있습니다. 아래가 전체 목록입니다.
| 상태 | 코드 | 발생 조건 |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | 키가 없거나 유효하지 않은 경우, 잔액이 호출 요금보다 적은 경우, 또는 분당 요청이 너무 많은 경우입니다. 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 | hs_code_not_found | HS 개정판에 해당 코드가 없습니다. |
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 | 지금은 품목 파일을 읽을 수 없습니다. 잠시 후 다시 시도하세요. |
MCP 도구
각 경로는 동일한 매개변수와 동일한 응답을 가진 별도의 MCP 도구입니다. MCP 도구는 한 결과에 최대 200행을 반환하므로 cursor로 페이지를 넘기세요. 도구는 다음과 같습니다:
trade_ list_ hs_ codestrade_ get_ hs_ codetrade_ get_ coveragetrade_ get_ partnerstrade_ get_ productstrade_ get_ producttrade_ get_ flows이 페이지가 도움이 되었나요?