hscode

README

hscode

A Go package that ships the Harmonized Commodity Description and Coding System (HS) as an in-memory dataset with helpers for validation, lookup, and search. The data files are embedded at build time, so lookups stay fast and offline-friendly.

Features

• Exposes a strongly typed HSCode with helpers for validation and metadata lookups.
• Provides search utilities (FindOr, FindAnd) that operate on a pre-tokenised description index.
• Offers curated slices such as HSCodes, HSCodesRoots, and HSCodesLeafs for traversing the tariff tree.
• Publishes generated constants (HS010121, HorsesLivePurebredBreedingAnimals, …) for the full set of six-digit canonical codes available in separate packages.

Install

go get github.com/thetechpanda/hscode

Quickstart

package main

import (
    "fmt"

    "github.com/thetechpanda/hscode"
)

func main() {
    code := hscode.HS950450

    def := code.Definition()
    fmt.Printf("%s (%s) -> %s\n", def.Code, def.Section, def.Description)
    fmt.Printf("Canonical: %t | Parent: %s\n", code.Canonical(), def.Parent)

    matches := hscode.FindAnd("video", "game")
    fmt.Printf("Found %d HS codes containing both terms\n", len(matches))
    
    matches = hscode.FindOr("video", "game")
    fmt.Printf("Found %d HS codes containing one of the terms\n", len(matches))
}

Run go test ./... to verify the dataset and helper functions.

API Highlights

• HSCode.Definition(), Canonical(), Valid() expose metadata and validation helpers.
• HSCodes(), HSCodesRoots(), HSCodesLeafs() return sorted slices of the catalogue.
• FindOr() and FindAnd() search descriptions using case-insensitive token matches.
• Sections() returns a copy of the HS section map for reference data.
• Hierarchical() returns a map with all root, leafs and codes organised hierarchically.

The names and codes packages contains generated constants.

Data and Regeneration

This repository uses the CSV made available by datasets/harmonized-system, a few minor changes have been done to the files.

• The CSV sources under data/ are embedded and distributed under the Open Data Commons PDDL (data/LICENSE.md).
• To regenerate autogenerated.go after updating the data, run go generate ./tools from the repository root.

License

• Package code is released under the MIT license LICENSE.md.
• Embedded HS data follows the Open Data Commons PDDL terms data/LICENSE.md.

Documentation

Index

• func Hierarchical() map[HSCode]map[HSCode][]HSCode
• func Sections() map[string]string
• type Definition
• type HSCode
  • func FindAnd(terms ...string) (found []HSCode)
  • func FindOr(terms ...string) (found []HSCode)
  • func HSCodes() (list []HSCode)
  • func HSCodesLeafs() (list []HSCode)
  • func HSCodesRoots() (list []HSCode)
  • func (hs HSCode) Canonical() bool
  • func (hs HSCode) Definition() (def Definition)
  • func (hs HSCode) Valid() bool

Functions

func Hierarchical

func Hierarchical() map[HSCode]map[HSCode][]HSCode

Hierarchical returns all codes hierarchically ordered.

func Sections

func Sections() map[string]string

Sections returns HSCodes sections.

Types

type Definition

type Definition struct {
	// Code is the HSCode defined by this struct.
	Code HSCode
	// Section: section code.
	Section string
	// Description: code description.
	Description string
	// Terms: Description, without punctuation split at white spaces.
	Terms []string
	// Parent: HSCode that defines the parent of the code.
	Parent HSCode
	// Canonical: defines whatever the code is an header or a full code.
	Canonical bool
	// Count: codes in the section.
	Count int
}

Definition contains code definition

type HSCode

type HSCode string

HSCode: Harmonized Commodity Description and Coding System

func FindAnd

func FindAnd(terms ...string) (found []HSCode)

FindAnd searches HSCodes with a description that matches all of the terms in argument

func FindOr

func FindOr(terms ...string) (found []HSCode)

FindOr searches HSCodes with a description that matches any of the terms in argument

func HSCodes

func HSCodes() (list []HSCode)

HSCodes returns sorted HSCodes.

func HSCodesLeafs

func HSCodesLeafs() (list []HSCode)

HSCodesLeafs returns sorted HSCode leafs, codes with a parent and descendents.

func HSCodesRoots

func HSCodesRoots() (list []HSCode)

HSCodesRoots returns sorted HSCode roots, codes without a parent.

func (HSCode) Canonical

func (hs HSCode) Canonical() bool

Canonical is true is the code is a 6 digit HSCode.

func (HSCode) Definition

func (hs HSCode) Definition() (def Definition)

Definition returns HSCode definition. returns false if the code is not a valid HSCode.

func (HSCode) Valid

func (hs HSCode) Valid() bool

Valid is true is the code is a valid HSCode.