{"openapi":"3.1.0","info":{"title":"HS Codes API","version":"1.0.0","description":"The World Customs Organization Harmonized System (HS) as an API — 6,900+ commodity classification codes used for customs, tariffs and international trade. Look up any HS code (2-digit chapter, 4-digit heading or 6-digit subheading) with its description and full ancestor chain, search the nomenclature by product, or drill into the sub-codes of a code. Ideal for logistics, customs, e-commerce and trade-compliance tooling.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/hscodes-api","description":"oanor gateway"}],"tags":[{"name":"HS Codes"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/children":{"get":{"operationId":"get_v1_children","tags":["HS Codes"],"summary":"The direct sub-codes of an HS code","description":"","parameters":[{"name":"hscode","in":"query","required":true,"description":"Parent HS code","schema":{"type":"string"},"example":"0901"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":5,"hscode":"0901","children":[{"level":"6","hscode":"090111","parent":"0901","section":"II","description":"Coffee; not roasted or decaffeinated"},{"level":"6","hscode":"090112","parent":"0901","section":"II","description":"Coffee; decaffeinated, not roasted"},{"level":"6","hscode":"090121","parent":"0901","section":"II","description":"Coffee; roasted, not decaffeinated"},{"level":"6","hscode":"090122","parent":"0901","section":"II","description":"Coffee; roasted, decaffeinated"},{"level":"6","hscode":"090190","parent":"0901","section":"II","description":"Coffee; husks and skins, coffee substitutes containing coffee in any proportion"}],"description":"Coffee, whether or not roasted or decaffeinated; husks and skins; coffee substitutes containing coffee in any proportion"},"meta":{"timestamp":"2026-05-31T02:53:35.048Z","request_id":"8f2bf873-c4fb-4017-a911-cf6ec1f3287a"},"status":"ok","message":"Children retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/code":{"get":{"operationId":"get_v1_code","tags":["HS Codes"],"summary":"An HS code with its description & ancestor chain","description":"","parameters":[{"name":"hscode","in":"query","required":true,"description":"HS code: 2, 4 or 6 digits","schema":{"type":"string"},"example":"090111"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"level":"6","hscode":"090111","parent":"0901","section":"II","ancestors":[{"level":"4","hscode":"0901","parent":"09","section":"II","description":"Coffee, whether or not roasted or decaffeinated; husks and skins; coffee substitutes containing coffee in any proportion"},{"level":"2","hscode":"09","parent":"TOTAL","section":"II","description":"Coffee, tea, mate and spices"},{"level":"5","hscode":"TOTAL","parent":"TOTAL","section":"TOTAL","description":"Total of all HS2022 commodities"}],"description":"Coffee; not roasted or decaffeinated"},"meta":{"timestamp":"2026-05-31T02:53:35.119Z","request_id":"9ce47e12-d007-4778-9abf-2a35ce6ab937"},"status":"ok","message":"HS code retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["HS Codes"],"summary":"Search HS codes by product/description","description":"","parameters":[{"name":"q","in":"query","required":true,"description":"Search text","schema":{"type":"string"},"example":"coffee"},{"name":"level","in":"query","required":false,"description":"Level: 2 (chapter), 4 (heading), 6 (subheading)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page (1-100, default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":12,"limit":20,"query":"coffee","total":12,"offset":0,"results":[{"level":"2","hscode":"09","parent":"TOTAL","section":"II","description":"Coffee, tea, mate and spices"},{"level":"4","hscode":"0901","parent":"09","section":"II","description":"Coffee, whether or not roasted or decaffeinated; husks and skins; coffee substitutes containing coffee in any proportion"},{"level":"6","hscode":"090111","parent":"0901","section":"II","description":"Coffee; not roasted or decaffeinated"},{"level":"6","hscode":"090112","parent":"0901","section":"II","description":"Coffee; decaffeinated, not roasted"},{"level":"6","hscode":"090121","parent":"0901","section":"II","description":"Coffee; roasted, not decaffeinated"},{"level":"6","hscode":"090122","parent":"0901","section":"II","description":"Coffee; roasted, decaffeinated"},{"level":"6","hscode":"090190","parent":"0901","section":"II","description":"Coffee; husks and skins, coffee substitutes containing coffee in any proportion"},{"level":"4","hscode":"2101","parent":"21","section":"IV","description":"Extracts, essences, concentrates of coffee, tea or mate; preparations with a basis of these products or with a basis of coffee, tea or mate; roasted chicory and other roasted coffee substitutes and extracts, essences and concentrates thereof"},{"level":"6","hscode":"210111","parent":"2101","section":"IV","description":"Extracts, essences and concentrates; of coffee, and preparations with a basis of these extracts, essences or concentrates or with a basis of coffee"},{"level":"6","hscode":"210112","parent":"2101","section":"IV","description":"Preparations with a basis of extracts, essences or concentrates or with a basis of coffee"},{"level":"6","hscode":"210130","parent":"2101","section":"IV","description":"Chicory, roasted and other roasted coffee substitutes; extracts, essences and concentrates thereof"},{"level":"6","hscode":"851671","parent":"8516","section":"XVI","description":"Electro-thermic appliances; coffee or tea makers, of a kind used for domestic purposes"}]},"meta":{"timestamp":"2026-05-31T02:53:35.189Z","request_id":"ad9a9767-ac9d-4b66-9112-6f19ba05a4d0"},"status":"ok","message":"Search completed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Totals, levels & source","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"total":6940,"fields":["hscode","description","section","parent","level"],"levels":[{"count":97,"label":"chapter","level":"2"},{"count":1229,"label":"heading","level":"4"},{"count":1,"label":"code","level":"5"},{"count":5613,"label":"subheading","level":"6"}],"source":"WCO Harmonized System (HS) nomenclature"},"meta":{"timestamp":"2026-05-31T02:53:35.262Z","request_id":"029b99c6-f53c-480a-87e3-711a6859ae72"},"status":"ok","message":"Meta retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":2000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":900,"monthly_call_quota":45000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2500,"monthly_call_quota":275000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6500,"monthly_call_quota":1100000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/hscodes-api"}