자유 무역 쿼리 API 레퍼런스
여러 보고국, 상대국, HS 류를 한 번의 호출로 조회합니다. 예: 품목별 상위 수출국, 국가 간 비교.
개요
GET /
GET /는 지정한 보고국, 상대국, HS 류의 수출입을 한 번의 호출로 반환합니다. reporter, partner, hs 각각은 최대 10개의 쉼표 구분 목록을 받습니다. 행 하나는 보고국, 월, 흐름, 상대국, 류의 한 조합입니다.
국가나 품목에 걸친 질문에 사용합니다. 어느 국가가 어떤 류를 수출하는지, 한 국가가 다른 국가와 어떻게 거래하는지, 두 국가를 나란히 비교하는 경우 등입니다. reporter, partner, hs 중 하나 이상을 지정하세요. reporter를 생략하면 자국 기관 또는 UN Comtrade에서 Narwhal이 직접 보유한 모든 국가를 뜻합니다.
각 행에 basis, source, currency가 명시됩니다. 보고국마다 다른 출처에서 응답할 수 있기 때문입니다. 서로 다른 출처의 행은 절대 합산하지 않습니다. 기간은 최대 12개월이며, start와 end가 없으면 보고국마다 가장 최신 월로 응답합니다. hs가 없으면 행은 상대국 합계이고, hs가 있으면 류 행입니다. MCP 도구는 trade_이며 동일한 매개변수를 받습니다.
요청
2026년 6월 영국과 독일의 85류(전기기기) 수출, 첫 페이지(5행):
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"DEU"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 396,
"rows": [
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "ABW",
"partner_label": "Aruba",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "108666",
"net_weight_kg": "731"
},
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "AFG",
"partner_label": "Afghanistan",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "153236",
"net_weight_kg": "2893"
}
],
"next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}페이지에는 5개 행 중 처음 2개가 표시됩니다. total은 396이므로 이후 페이지가 이어집니다. 1페이지에는 독일의 행만 있으며 reporters는 페이지에 있는 보고국을 나열하므로, 2곳을 요청했더라도 DEU만 표시됩니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 기본값 | 허용 값과 의미 |
|---|---|---|---|---|---|
reporter | 쿼리 | 문자열 | 아니요 | 직접 보유한 모든 국가 | 보고국. ISO 3166-1 alpha-3 코드를 대문자로, 최대 10개의 쉼표 구분 목록으로 씁니다. 예: GBR,DEU. 국가가 아닌 코드는 400을 반환하고 해당 코드를 명시합니다. 제공 범위 목록에 없는 국가는 404 country_를 반환합니다. 자체 출처가 없는 보고국은 다른 국가의 보고 자료로 응답하며 명시적으로 지정해야 합니다. |
partner | 쿼리 | 문자열 | 아니요 | 모든 상대국 | 상대국. ISO 3166-1 alpha-3 코드를 대문자로, 최대 10개의 쉼표 구분 목록으로 씁니다. |
hs | 쿼리 | 문자열 | 아니요 | 없음 | HS 류, 2자리, 최대 10개의 쉼표 구분 목록. 예: 85,87. 이 경우 행은 류 행입니다. 생략하면 행은 상대국 합계입니다. 자유 쿼리에는 류만 보유합니다. |
flow | 쿼리 | 문자열 | 아니요 | 두 흐름 | export 또는 import. |
start | 쿼리 | 문자열, YYYY-MM | 아니요 | 보고국별 가장 최신 월 | 첫 월이며 해당 월을 포함합니다. start부터 end까지는 최대 12개월입니다. |
end | 쿼리 | 문자열, YYYY-MM | 아니요 | 보고국별 가장 최신 월 | 마지막 월이며 해당 월을 포함합니다. start와 end 중 하나만 있으면 그 월 하나만 해당됩니다. |
basis | 쿼리 | 문자열 | 아니요 | 보고국이 보유한 최상의 출처 | own, third_ 또는 partner_. 이 출처만 응답합니다. 해당 질의에 대한 행이 없는 출처는 404 basis_을 반환합니다. |
currency | 쿼리 | 문자열 | 아니요 | 보고국 자체 통화, 각 행에 명시 | USD. 각 행을 해당 월의 일평균 환율로 환산합니다. |
include_ | 쿼리 | 불리언 | 아니요 | false | true이면 EU나 ASEAN처럼 발행 기관이 게재하는 그룹 행도 함께 반환합니다. 그룹 행은 합계, 순위, 비중에 포함되지 않습니다. |
limit | 쿼리 | 정수 | 아니요 | 500 | 1에서 1000 사이. 한 페이지의 최대 행 수. |
cursor | 쿼리 | 문자열 | 아니요 | 없음 | 이전 페이지의 next_이며, 다른 매개변수는 그대로 둡니다. |
응답
응답에는 다음 필드가 있습니다.
| 필드 | 의미 |
|---|---|
scope | goods. |
bases | 이 응답의 행이 나온 출처이며, 각각 own, third_ 또는 partner_입니다. |
reporters | 이 페이지에 행이 있는 보고국이며 정렬되어 있습니다. 이후 페이지에서 더 나열될 수 있습니다. |
latest_ | 직접 보유한 행 중 가장 최신 월. 없으면 null. |
note | 수치를 사용하기 전에 읽으세요. 행이 상대국 보고일 때 설정되며, 그 외에는 null입니다. |
fx | currency=USD인 경우: 월별 적용 환율이며 period, from_, to_, rate, days를 포함합니다. 그 외에는 null. |
calculated | Narwhal이 계산한 필드의 이름. |
total | 모든 페이지에 걸쳐 일치하는 행 수. |
next_ | 다음 페이지의 커서. 마지막 페이지에서는 null. |
rows의 각 항목은 보고국, 월, 흐름, 상대국, 류의 한 조합입니다.
| 필드 | 의미 |
|---|---|
reporter | 보고국의 ISO 3166-1 alpha-3 코드. |
basis | 이 행의 출처: own, third_ 또는 partner_. |
source | 이 행의 발행 기관. |
currency | 이 행 값의 ISO 4217 코드. |
flow | export 또는 import. |
period | 월, YYYY-MM. |
period_ | month. |
period_ | 행이 다루는 첫날과 마지막 날, YYYY-MM-DD. |
partner, partner_ | 상대국 경로와 같습니다. |
product_ | hs를 보낸 경우의 류. 상대국 합계이면 null. |
value | currency의 정수 단위, 십진수 문자열. |
net_ | 발행 기관이 제공하는 경우 킬로그램 단위의 순중량. 그 외에는 null. |
추가 예시
상대국 합계만 있는 보고국은 건너뜁니다
중국으로부터의 미국 85류 수입이며, 캐나다와 멕시코도 함께 지정했습니다. 이들의 자국 기관은 상대국 합계만 제공하므로 미국만 응답합니다:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"USA"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 1,
"rows": [
{
"reporter": "USA",
"basis": "own",
"source": "US Census Bureau",
"currency": "USD",
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "5834371932",
"net_weight_kg": null
}
],
"next_cursor": null
}상대국 합계만 있는 보고국
지정한 모든 보고국이 상대국 합계만 제공하고 hs를 보낸 경우 호출은 404를 반환하며 무료입니다:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"{
"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. See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}출처
각 보고국은 보유한 최상의 출처에서 응답합니다. 먼저 자국 기관, 그다음 UN Comtrade 제출 자료(상대국 합계만)이며, 둘 다 없는 보고국은 partner_로 표시되는 다른 국가의 보고 자료로 응답합니다. 류별로는 UN Comtrade에 자료가 없습니다. basis는 모든 보고국에 출처 하나를 강제합니다. 자국 기관이 상대국 합계만 제공하는 보고국에는 류 행이 없으며, 다른 보고국이 응답할 수 있으면 건너뛰고 아무도 응답할 수 없으면 호출은 404 basis_을 반환합니다.
통화
각 행은 보고국 자체 통화이며 행의 currency에 명시됩니다. currency=USD는 모든 행을 해당 월의 일평균 환율로 환산하고 fx에 환율을 나열합니다. 환율이 없는 월은 404 rate_을 반환하고, 환율 출처를 사용할 수 없으면 503 upstream_을 반환합니다.
페이징
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 | reporter, partner, hs를 하나도 지정하지 않았거나(an open query with none is the whole store), end가 start보다 앞이거나, 기간이 12개월을 초과하거나, 목록에 항목이 10개를 초과하거나, 보고국이 국가가 아니거나, 매개변수가 허용 값을 벗어나거나, as_ 또는 version을 보낸 경우입니다. 또한 상대국 보고 응답에 보고국·상대국·류 조합이 30개를 초과해 필요한 경우에도 해당됩니다. |
400 | invalid_cursor | 커서가 이 요청이 반환한 것이 아니거나, 그 이후 다른 매개변수가 바뀐 경우입니다. |
400 | range_too_large | 응답이 200,000행을 초과하거나, 상대국 없이 류 행이 36개 보고국·월을 초과하는 경우입니다. 보고국, 상대국 또는 류를 줄이거나 기간을 줄이세요. |
404 | country_not_covered | 지정한 보고국이 제공 범위 목록에 없습니다(ATA is not in the trade coverage list.). |
404 | basis_not_available | basis가 해당 질의에 대한 행이 없는 출처를 지정했거나, 지정한 모든 보고국이 상대국 합계만 보유하고 hs를 보낸 경우입니다. |
404 | rate_not_available | currency=USD를 요청했는데 어떤 월에 환율이 없습니다. |
503 | upstream_unavailable | 환율 출처가 응답할 수 없습니다. currency=USD와 환산이 필요한 상대국 보고 응답에 영향을 줍니다. 잠시 후 다시 시도하세요. |
503 | trade_data_unavailable | 지금은 품목 파일을 읽을 수 없습니다. 잠시 후 다시 시도하세요. |
이 페이지가 도움이 되었나요?