전체 문서 탐색

상대국별 무역 API 레퍼런스

한 국가의 상대국별 수출입을 읽습니다. 상대국, 월, 흐름마다 행 하나이며, 행 합계 옆에 발행 기관 자체 합계가 함께 나옵니다.

개요

GET /v1/trade/{country}/partners

GET /v1/trade/{country}/partners는 한 국가의 상대국별 상품 무역을 반환합니다. 상대국, 월, 흐름마다 행 하나입니다. start와 end가 없으면 응답은 보유한 가장 최신 월입니다.

한 국가가 누구와 얼마나 거래하는지 확인할 때 사용합니다. 같은 국가의 품목별 데이터는 품목 경로를, 품목 하나의 모든 상대국 데이터는 단일 품목 경로를 사용합니다. 여러 국가를 한 번의 호출로 비교하려면 자유 쿼리 경로를 사용합니다.

모든 응답은 basis와 source에 출처를 명시하며, totals에 행 합계 옆에 발행 기관 자체 합계를 담습니다. hs를 지정하면 totals는 해당 품목의 합계이며 official_total은 null입니다. MCP 도구는 trade_get_partners이며 동일한 매개변수를 받습니다.

요청

2026년 6월 영국의 수출 상대국 상위 3곳과 실제 응답:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"
영국, 수출 상대국 상위 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"
  ],
  "total": 3,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "5316654916",
      "net_weight_kg": "76287894",
      "rank": 1,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "4735227787",
      "net_weight_kg": "341314142",
      "rank": 2,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

페이지에는 3개 행 중 처음 2개가 표시됩니다. basis가 own이므로 영국 세입관세청(HM Revenue & Customs)이 응답했으며, official_total은 sum_of_rows와 같습니다. top을 보냈으므로 rank가 설정되며 calculated에 나열됩니다.

매개변수

매개변수위치유형필수기본값허용 값과 의미
country경로문자열예없음보고국의 ISO 3166-1 alpha-3 코드이며 대문자로 씁니다. 예: GBR. 국가가 아닌 코드는 400을 반환합니다. 수치가 없는 국가는 404 country_not_covered를 반환합니다.
partner쿼리문자열아니요모든 상대국상대국 한 곳의 ISO 3166-1 alpha-3 코드이며 대문자로 씁니다. 해당 국가의 상대국이 아닌 코드는 400 unknown_partner를 반환합니다.
flow쿼리문자열아니요두 흐름export 또는 import.
start쿼리문자열, YYYY-MM아니요보유한 가장 최신 월첫 월이며 해당 월을 포함합니다. start만 있고 end가 없으면 응답은 보유한 가장 최신 월까지입니다. end보다 뒤인 start는 400을 반환합니다.
end쿼리문자열, YYYY-MM아니요보유한 가장 최신 월마지막 월이며 해당 월을 포함합니다. end만 있으면 응답은 그 월 또는 그 이전 중 보유한 가장 최신 월입니다.
hs쿼리문자열아니요모든 품목이 품목의 무역만 반환하며, 코드는 2자리, 4자리 또는 6자리(85, 8517, 851713)입니다. 각 상대국이 차지하는 비중이 나옵니다. 다른 자릿수의 코드는 400을 반환합니다. 태국은 4자리로 보유하고 있어, 태국에 6자리 코드를 보내면 404 basis_not_available를 반환합니다.
basis쿼리문자열아니요보유한 최상의 출처own, third_party 또는 partner_reported. 출처 하나를 이름으로 지정하며 순서를 건너뜁니다. 해당 질의에 대한 행이 없는 출처는 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개월을 다룹니다. 상대국 보고 응답에는 사용할 수 없습니다.
include_groups쿼리불리언아니요falsetrue이면 EU나 ASEAN처럼 발행 기관이 게재하는 그룹 행도 함께 반환합니다. 그룹 행은 합계, 순위, 비중에 포함되지 않습니다.
limit쿼리정수아니요5001에서 1000 사이. 한 페이지의 최대 행 수.
cursor쿼리문자열아니요없음이전 페이지의 next_cursor이며, 다른 매개변수는 그대로 둡니다.

응답

응답에는 다음 필드가 있습니다. 모든 행에 공통인 내용은 여기에 한 번만 나옵니다.

필드의미
country응답이 다루는 보고국의 ISO 3166-1 alpha-3 코드.
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_coverageall은 모든 상대국이 나열된 경우, top_n은 발행 기관이 상위 상대국과 기타 행 1개만 게재하는 경우입니다. 상대국 보고 응답에서는 null입니다.
scopegoods.
currency응답의 모든 값에 적용되는 ISO 4217 코드.
classificationHS, Harmonized System.
edition요청한 모든 월을 하나의 개정판이 다루는 경우의 HS 개정판(2007, 2012, 2017 또는 2022). 월마다 다르면 null이며, 각 행에 해당 개정판이 명시됩니다.
edition_basisas_published는 발행 기관이 개정판을 밝힌 경우, inferred_from_year는 Narwhal이 연도로 추정한 경우입니다.
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_period이 국가와 출처에 대해 Narwhal이 보유한 가장 최신 월.
total_basisofficial_total의 기준: customs, balance_of_payments 또는 eurostat_concept. 발행 기관이 합계를 제공하지 않으면 null.
totals월과 흐름마다 항목 하나: period, flow, official_total(발행 기관 자체 상품 합계이며 없으면 null), sum_of_rows(그룹 행을 제외한 해당 월·흐름의 모든 상대국 행의 합계, 계산값). hs가 없으면 partner가 행을 제한하는 경우에도 해당 월의 전체 상품 합계가 들어갑니다. hs가 있으면(그리고 단일 품목 경로에서는) 대신 해당 품목의 합계가 들어갑니다. sum_of_rows는 모든 페이지에 걸친 응답 행의 합계(partner를 지정했다면 그 상대국의 행이며, top과 페이징으로 줄어들지 않음)이고, 발행 기관이 품목 하나에 대한 합계를 게재하지 않으므로 official_total은 null입니다.
fxcurrency=USD인 경우, 그리고 둘 이상의 통화를 쓰는 상대국 보고 응답에서: 월별 적용 환율이며 period, from_currency, to_currency, rate, 평균에 사용한 days를 포함합니다. 그 외에는 null.
calculatedsum_of_rows, rank, share, value, official_total처럼 Narwhal이 계산한 필드의 이름.
total모든 페이지에 걸쳐 일치하는 행 수.
next_cursor다음 페이지의 커서. 마지막 페이지에서는 null.

rows의 각 항목은 한 월·흐름의 상대국 하나입니다.

필드의미
flowexport 또는 import.
period월, YYYY-MM. 연초 이후는 그 마지막 월.
period_typemonth 또는 year_to_date.
period_start, period_end행이 다루는 첫날과 마지막 날, YYYY-MM-DD.
valuecurrency의 정수 단위, 십진수 문자열.
net_weight_kg발행 기관이 제공하는 경우 킬로그램 단위의 순중량이며 십진수 문자열. 그 외에는 null.
ranktop인 경우: 행의 순위이며 가장 큰 값이 1. 그 외에는 null.
shareshare인 경우: 합계에서 행이 차지하는 비율이며 소수 6자리. 그 외에는 null.
changechange인 경우: previous_period, previous_value, absolute(값에서 이전 값을 뺀 값), percent(퍼센트 단위, 소수 4자리이며 이전 값이 0이면 null), release_status, previous_release_status(preliminary, revised, final, 발행 기관이 밝히지 않으면 null)를 가진 객체. 1년 전 행이 없거나 change를 요청하지 않았으면 null.
partner상대국의 ISO 3166-1 alpha-3 코드, EUU 같은 그룹 코드, 또는 국가가 없는 라인이면 빈 값.
partner_label발행 기관이 사용하는 상대국 이름.
partner_kindcountry, group 또는 unallocated.
unallocated_reason미배분 행인 경우: not_specified, confidential, stores_bunkers, free_zone, other 또는 rest. 그 외에는 null.

추가 예시

상대국 한 곳의 두 흐름

독일과 중국, 2026년 1월~6월, 두 흐름:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"
독일과 중국
{
  "country": "DEU",
  "basis": "own",
  "source": "Eurostat Comext",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "EUR",
  "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": "eurostat_concept",
  "totals": [
    {
      "period": "2026-01",
      "flow": "export",
      "official_total": "121792305000",
      "sum_of_rows": "121792305000"
    },
    {
      "period": "2026-01",
      "flow": "import",
      "official_total": "106754947046",
      "sum_of_rows": "106754947046"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 12,
  "rows": [
    {
      "flow": "export",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "5559611667",
      "net_weight_kg": "355538457",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "8853410701",
      "net_weight_kg": "1020758294",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

페이지에는 12개 행 중 처음 2개와 totals 항목 12개 중 처음 2개가 표시됩니다. 독일은 Eurostat Comext에서 유로로 응답합니다.

자국 기관이 제공하지 않는 품목

캐나다의 자국 기관은 상대국 합계만 제공합니다. 품목 하나를 요청하면 404를 반환하며 무료입니다:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"
캐나다, 품목 8517
{
  "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 answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}

출처

다음 순서에서 행을 가진 첫 번째 출처가 요청마다 응답합니다. 해당 국가의 자체 관세청 또는 통계청(basis는 own), UN Comtrade에 제출한 해당 국가의 자체 보고(third_party, 상대국 합계만), 그다음 수출입 방향을 맞바꾼 다른 국가의 보고(partner_reported)입니다. 다른 국가의 보고는 해당 국가에 대해 행을 가진 보고국이 200곳 이상일 때만 UN Comtrade보다 앞서는데, 이는 Narwhal이 보유한 수보다 많으므로 가장 마지막에 옵니다. 품목별로는 UN Comtrade에 자료가 없으므로 순서는 own, 그다음 partner_reported이며, partner_reported는 류(2자리)까지만 제공합니다. basis로 출처 하나를 이름으로 지정할 수 있습니다. 응답의 basis, source, note 필드가 어느 출처가 응답했는지 알려 주며, 출처는 한 응답에서 절대 섞이지 않습니다. 상대국 보고 응답은 해당 국가 자체 수치와 다른 측정값이며 공식 수치가 아닙니다. 출처의 상대국 목록이 짧을 수 있습니다. partner_coverage가 top_n이면 발행 기관이 상위 상대국과 기타 행 1개를 명시하며, 행의 합은 여전히 합계와 일치합니다.

통화

값은 currency에 명시된 통화의 정수 단위이며 십진수 문자열로 표기합니다. 기본값은 출처가 발표하는 통화로, 예를 들어 영국 세입관세청(HM Revenue & Customs)은 GBP입니다. currency=USD는 해당 월의 일별 환율 평균으로 월마다 환산합니다. 월별 적용 환율은 fx에 나열되며, calculated는 환산된 필드를 표시합니다. 환율이 없는 월은 404 rate_not_available을 반환합니다. 환율 출처가 응답할 수 없으면 503 upstream_unavailable을 반환합니다. 이미 USD인 응답은 그대로 반환됩니다.

페이징

limit은 한 페이지의 최대 행 수를 1에서 1000 사이로 정하며 기본값은 500입니다. 일치하는 행이 더 있으면 next_cursor에 다음 페이지의 커서가 들어 있으며, 다른 매개변수는 그대로 두고 cursor로 보냅니다. 다른 요청의 커서는 400 invalid_cursor를 반환합니다. total은 모든 페이지에 걸쳐 일치하는 행 수입니다. MCP 도구는 한 결과에 최대 200행을 반환합니다.

가격

행을 하나 이상 반환하는 요청은 호출 1회이며, 1,000회 호출당 $2입니다. 긴 응답의 각 페이지는 limit과 관계없이 호출 1회입니다. 행이 없는 응답은 무료이고, 모든 오류도 무료입니다.

오류

이 오류는 request_id가 포함된 공통 problem 형식을 사용합니다. 키가 없거나 유효하지 않은 경우(401), 잔액이 호출 요금보다 적은 경우(402), 분당 요청이 너무 많은 경우(429)는 모든 경로가 공통으로 가지는 계정 오류입니다. 자세한 내용은 API 오류 코드와 크레딧을 참고하세요.

상태코드발생 조건
400invalid_query매개변수가 누락되었거나 형식이 잘못되었거나 허용 값을 벗어난 경우입니다. 예를 들어 start=2026-13, end보다 뒤인 start, start와 함께 보낸 ytd, 또는 보낸 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 레퍼런스 · 무역 국가

이 페이지가 도움이 되었나요?