HS 코드 검색 API 레퍼런스
한 개정판의 Harmonized System 코드(2자리, 4자리, 6자리)를 이름, 단계 또는 상위 코드로 검색하거나 나열합니다.
개요
GET /
GET /는 한 개정판의 Harmonized System(HS) 코드를 나열합니다. HS 코드는 거래되는 품목을 가리키며, 2자리는 류, 4자리는 호, 6자리는 소호입니다. 무역 경로는 이 코드를 반환하며, 이 경로는 필요한 코드를 찾아 줍니다.
q는 이름을 검색합니다. 류가 먼저, 그다음 호, 그다음 소호이며, 같은 단계 안에서는 가장 잘 일치하는 항목이 먼저 옵니다. parent는 코드의 하위 코드를 나열하고 level은 한 자릿수만 유지합니다. 개정판은 2007, 2012, 2017, 2022의 네 가지입니다. 개정판끼리는 서로 환산하지 않으므로 2022년에 생긴 코드는 2017년 목록에 없습니다. 2022년 개정판에는 96개 류, 1,228개 호, 5,612개 소호가 있습니다. MCP 도구는 trade_이며 동일한 매개변수를 받습니다.
요청
2022년 개정판에서 cheese(치즈)를 검색한 결과, 첫 페이지(3개 코드)와 실제 응답:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=cheese&limit=3"{
"classification": "HS",
"edition": "2022",
"total": 6,
"codes": [
{
"code": "0406",
"level": 4,
"label": "Cheese and curd",
"parent": "04"
},
{
"code": "040690",
"level": 6,
"label": "Cheese (excl. fresh cheese, incl. whey cheese, curd, processed cheese, blue-veined cheese and other cheese containing veins produced by \"Penicillium roqueforti\", and grated or powdered cheese)",
"parent": "0406"
}
],
"next_cursor": "eyJiIjoiaHM6MjAyMjpjaGVlc2U6Tm9uZTpOb25lOjMiLCJvIjozfQ"
}페이지에는 3개 코드 중 처음 2개가 표시됩니다. total은 6이므로 next_가 설정됩니다. 호가 소호보다 순위가 높으므로 0406호가 그 소호인 040690보다 앞에 옵니다.
매개변수
| 매개변수 | 위치 | 유형 | 필수 | 기본값 | 허용 값과 의미 |
|---|---|---|---|---|---|
q | 쿼리 | 문자열, 2자에서 100자 | 아니요 | 없음 | 코드명에서 찾을 텍스트. |
edition | 쿼리 | 문자열 | 아니요 | 2022 | 2007, 2012, 2017 또는 2022. 다른 값은 400을 반환합니다. |
level | 쿼리 | 정수 | 아니요 | 모든 단계 | 2, 4 또는 6. 이 자릿수의 코드만. |
parent | 쿼리 | 문자열 | 아니요 | 없음 | 2자리, 4자리 또는 6자리 HS 코드. 이 코드의 하위 코드만. 류와 호에는 하위 코드가 있고 소호에는 없습니다. |
limit | 쿼리 | 정수 | 아니요 | 100 | 1에서 1000 사이. 한 페이지의 최대 코드 수. |
cursor | 쿼리 | 문자열 | 아니요 | 없음 | 이전 페이지의 next_이며, 다른 매개변수는 그대로 둡니다. |
응답
응답에는 다음 필드가 있습니다.
| 필드 | 의미 |
|---|---|
classification | HS. |
edition | 목록의 개정판. |
total | 모든 페이지에 걸쳐 일치하는 코드 수. |
codes | 이 페이지의 코드. 각 코드에는 code, level(2, 4 또는 6), label(개정판 표기에 따른 코드명), parent(한 단계 위의 코드이며 류는 null)가 있습니다. |
next_ | 다음 페이지의 커서. 마지막 페이지에서는 null. |
추가 예시
일치 항목 없음
일치하는 항목이 없는 검색은 빈 목록과 함께 200을 반환하며 무료입니다:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/hs-codes?q=zzzzqqq"{
"classification": "HS",
"edition": "2022",
"total": 0,
"codes": [],
"next_cursor": null
}출처
이 경로는 코드를 나열하며 무역 수치는 없으므로 적용되는 출처가 없습니다.
통화
이 경로는 값을 반환하지 않으므로 적용되는 통화가 없습니다.
페이징
limit은 한 페이지의 최대 코드 수를 1에서 1000 사이로 정하며 기본값은 100입니다. 일치하는 코드가 더 있으면 next_에 다음 페이지의 커서가 들어 있으며, 다른 매개변수는 그대로 두고 cursor로 보냅니다. 다른 요청의 커서는 400 invalid_를 반환합니다. total은 모든 페이지에 걸쳐 일치하는 행 수입니다. MCP 도구는 한 결과에 최대 200행을 반환합니다.
가격
코드를 하나 이상 반환하는 요청은 호출 1회이며 1,000회 호출당 $2입니다. 긴 목록의 각 페이지도 호출 1회입니다. 일치하는 항목이 없는 검색은 무료이며, 모든 오류도 무료입니다.
오류
이 오류는 request_가 포함된 공통 problem 형식을 사용합니다. 키가 없거나 유효하지 않은 경우(401), 잔액이 호출 요금보다 적은 경우(402), 분당 요청이 너무 많은 경우(429)는 모든 경로가 공통으로 가지는 계정 오류입니다. 자세한 내용은 API 오류 코드와 크레딧을 참고하세요.
| 상태 | 코드 | 발생 조건 |
|---|---|---|
400 | invalid_query | edition, level, limit이 허용 값을 벗어났거나, q가 2자보다 짧거나, parent가 2자리, 4자리 또는 6자리 코드가 아닙니다. |
400 | invalid_cursor | 커서가 이 요청이 반환한 것이 아니거나, 그 이후 다른 매개변수가 바뀐 경우입니다. |
이 페이지가 도움이 되었나요?