# pyhscodes
A Python package for working with Harmonized System (HS) codes from the World Customs Organization. Built on the foundation of the popular [pycountry](https://github.com/flyingcircusio/pycountry) package, pyhscodes provides a similar API for HS codes with hierarchical structure and search capabilities.
## Features
- **Complete HS Code Database**: Contains 6,940+ HS codes with full hierarchical structure
- **Section Support**: All 21 HS code sections with descriptions
- **Hierarchical Navigation**: Navigate from chapters (2-digit) to headings (4-digit) to subheadings (6-digit)
- **Fuzzy Search**: Find codes by description text
- **Fast Lookups**: Optimized indexing for quick code retrieval
- **Pythonic API**: Clean, intuitive interface similar to pycountry
## Installation
```bash
pip install pyhscodes
```
## Quick Start
```python
import pyhscodes
# Basic statistics
print(f"Total HS codes: {len(pyhscodes.hscodes)}")
print(f"Total sections: {len(pyhscodes.sections)}")
# Get a specific code
animals = pyhscodes.hscodes.get(hscode="01")
print(f"{animals.hscode}: {animals.description}")
# Get children of a code
children = pyhscodes.hscodes.get_children("01")
for child in children:
print(f" {child.hscode}: {child.description}")
# Get full hierarchy
hierarchy = pyhscodes.hscodes.get_hierarchy("010121")
for code in hierarchy:
print(f"{code.hscode}: {code.description} (Level {code.level})")
# Fuzzy search
results = pyhscodes.hscodes.search_fuzzy("dairy")
for result in results[:3]:
print(f"{result.hscode}: {result.description}")
```
## API Reference
### HS Codes
#### `pyhscodes.hscodes`
The main database of HS codes.
**Properties:**
- `hscode`: The HS code (e.g., "010121")
- `description`: Description of the code
- `section`: Which section this code belongs to
- `parent`: Parent code in the hierarchy
- `level`: Code level ("2", "4", or "6")
- `is_chapter`: True if this is a 2-digit chapter
- `is_heading`: True if this is a 4-digit heading
- `is_subheading`: True if this is a 6-digit subheading
**Methods:**
- `get(hscode="01")`: Get a specific code
- `lookup("01")`: Lookup by code or description
- `search_fuzzy("horses")`: Fuzzy search by description
- `get_by_level("2")`: Get all codes at a specific level
- `get_children("01")`: Get child codes
- `get_hierarchy("010121")`: Get full hierarchy path
### Sections
#### `pyhscodes.sections`
Database of HS code sections.
**Properties:**
- `section`: Section identifier (e.g., "I", "II")
- `name`: Section name/description
**Methods:**
- `get(section="I")`: Get a specific section
## Data Structure
HS codes follow a hierarchical structure:
- **Sections**: 21 major groupings (I through XXI)
- **Chapters**: 97 two-digit codes (01, 02, ..., 97)
- **Headings**: 1,229+ four-digit codes (0101, 0102, ...)
- **Subheadings**: 5,613+ six-digit codes (010121, 010122, ...)
Example hierarchy:
```
Section I: Live animals; animal products
├── 01: Animals; live
├── 0101: Horses, asses, mules and hinnies; live
├── 010121: Horses; live, pure-bred breeding animals
└── 010129: Horses; live, other than pure-bred breeding animals
```
## Examples
See `example.py` for a comprehensive demonstration of the package features.
## Development
### Setting up for development
```bash
git clone https://github.com/yourusername/pyhscodes.git
cd pyhscodes
pip install -e .
```
### Running tests
```bash
pytest src/pyhscodes/tests/
```
### Data Updates
To update the HS codes database:
1. Place your CSV files in the project root:
- `harmonized-system.csv` (columns: section, hscode, description, parent, level)
- `sections.csv` (columns: section, name)
2. Run the conversion script:
```bash
python convert_csv_to_json.py
```
## License
This project is licensed under the LGPL-2.1 License - see the LICENSE file for details.
## Acknowledgments
- Built on the foundation of [pycountry](https://github.com/flyingcircusio/pycountry)
- HS codes from the World Customs Organization
- Inspired by the need for a Python package similar to pycountry but for trade classification codes
Raw data
{
"_id": null,
"home_page": null,
"name": "pyhscodes",
"maintainer": "David Sigley",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "david@coolset.com",
"keywords": "hs codes, harmonized system, customs, trade, tariff, classification, wco, world customs organization, EUDR, CBAM",
"author": "David Sigley",
"author_email": "david@coolset.com",
"download_url": "https://files.pythonhosted.org/packages/05/65/a071de22a6ad5bfc03758b18bdc347eaa3a07e92f647aff8bea1e86d4a64/pyhscodes-1.0.2.tar.gz",
"platform": null,
"description": "# pyhscodes\n\nA Python package for working with Harmonized System (HS) codes from the World Customs Organization. Built on the foundation of the popular [pycountry](https://github.com/flyingcircusio/pycountry) package, pyhscodes provides a similar API for HS codes with hierarchical structure and search capabilities.\n\n## Features\n\n- **Complete HS Code Database**: Contains 6,940+ HS codes with full hierarchical structure\n- **Section Support**: All 21 HS code sections with descriptions\n- **Hierarchical Navigation**: Navigate from chapters (2-digit) to headings (4-digit) to subheadings (6-digit)\n- **Fuzzy Search**: Find codes by description text\n- **Fast Lookups**: Optimized indexing for quick code retrieval\n- **Pythonic API**: Clean, intuitive interface similar to pycountry\n\n## Installation\n\n```bash\npip install pyhscodes\n```\n\n## Quick Start\n\n```python\nimport pyhscodes\n\n# Basic statistics\nprint(f\"Total HS codes: {len(pyhscodes.hscodes)}\")\nprint(f\"Total sections: {len(pyhscodes.sections)}\")\n\n# Get a specific code\nanimals = pyhscodes.hscodes.get(hscode=\"01\")\nprint(f\"{animals.hscode}: {animals.description}\")\n\n# Get children of a code\nchildren = pyhscodes.hscodes.get_children(\"01\")\nfor child in children:\n print(f\" {child.hscode}: {child.description}\")\n\n# Get full hierarchy\nhierarchy = pyhscodes.hscodes.get_hierarchy(\"010121\")\nfor code in hierarchy:\n print(f\"{code.hscode}: {code.description} (Level {code.level})\")\n\n# Fuzzy search\nresults = pyhscodes.hscodes.search_fuzzy(\"dairy\")\nfor result in results[:3]:\n print(f\"{result.hscode}: {result.description}\")\n```\n\n## API Reference\n\n### HS Codes\n\n#### `pyhscodes.hscodes`\n\nThe main database of HS codes.\n\n**Properties:**\n- `hscode`: The HS code (e.g., \"010121\")\n- `description`: Description of the code\n- `section`: Which section this code belongs to\n- `parent`: Parent code in the hierarchy\n- `level`: Code level (\"2\", \"4\", or \"6\")\n- `is_chapter`: True if this is a 2-digit chapter\n- `is_heading`: True if this is a 4-digit heading \n- `is_subheading`: True if this is a 6-digit subheading\n\n**Methods:**\n- `get(hscode=\"01\")`: Get a specific code\n- `lookup(\"01\")`: Lookup by code or description\n- `search_fuzzy(\"horses\")`: Fuzzy search by description\n- `get_by_level(\"2\")`: Get all codes at a specific level\n- `get_children(\"01\")`: Get child codes\n- `get_hierarchy(\"010121\")`: Get full hierarchy path\n\n### Sections\n\n#### `pyhscodes.sections`\n\nDatabase of HS code sections.\n\n**Properties:**\n- `section`: Section identifier (e.g., \"I\", \"II\")\n- `name`: Section name/description\n\n**Methods:**\n- `get(section=\"I\")`: Get a specific section\n\n## Data Structure\n\nHS codes follow a hierarchical structure:\n\n- **Sections**: 21 major groupings (I through XXI)\n- **Chapters**: 97 two-digit codes (01, 02, ..., 97)\n- **Headings**: 1,229+ four-digit codes (0101, 0102, ...)\n- **Subheadings**: 5,613+ six-digit codes (010121, 010122, ...)\n\nExample hierarchy:\n```\nSection I: Live animals; animal products\n\u251c\u2500\u2500 01: Animals; live\n \u251c\u2500\u2500 0101: Horses, asses, mules and hinnies; live\n \u251c\u2500\u2500 010121: Horses; live, pure-bred breeding animals\n \u2514\u2500\u2500 010129: Horses; live, other than pure-bred breeding animals\n```\n\n## Examples\n\nSee `example.py` for a comprehensive demonstration of the package features.\n\n## Development\n\n### Setting up for development\n\n```bash\ngit clone https://github.com/yourusername/pyhscodes.git\ncd pyhscodes\npip install -e .\n```\n\n### Running tests\n\n```bash\npytest src/pyhscodes/tests/\n```\n\n### Data Updates\n\nTo update the HS codes database:\n\n1. Place your CSV files in the project root:\n - `harmonized-system.csv` (columns: section, hscode, description, parent, level)\n - `sections.csv` (columns: section, name)\n\n2. Run the conversion script:\n ```bash\n python convert_csv_to_json.py\n ```\n\n## License\n\nThis project is licensed under the LGPL-2.1 License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built on the foundation of [pycountry](https://github.com/flyingcircusio/pycountry)\n- HS codes from the World Customs Organization\n- Inspired by the need for a Python package similar to pycountry but for trade classification codes \n",
"bugtrack_url": null,
"license": "LGPL-2.1-only",
"summary": "Harmonized System (HS) codes from the World Customs Organization with hierarchical structure and search capabilities",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/sigularusrex/pyhscodes#readme",
"Homepage": "https://github.com/sigularusrex/pyhscodes",
"Repository": "https://github.com/sigularusrex/pyhscodes"
},
"split_keywords": [
"hs codes",
" harmonized system",
" customs",
" trade",
" tariff",
" classification",
" wco",
" world customs organization",
" eudr",
" cbam"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "465cea58fbd2938f6f8437ce0d3082667a279fbe2c05d0ead5bd1ca3c693fe00",
"md5": "15f0ac98b5efa5c1994d56a4ced40c02",
"sha256": "599aaa06f910618d9ab5d213bcf2654ca8ac8d0189baf4f9d6c21d446524a4f6"
},
"downloads": -1,
"filename": "pyhscodes-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15f0ac98b5efa5c1994d56a4ced40c02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 184031,
"upload_time": "2025-07-31T08:48:22",
"upload_time_iso_8601": "2025-07-31T08:48:22.601914Z",
"url": "https://files.pythonhosted.org/packages/46/5c/ea58fbd2938f6f8437ce0d3082667a279fbe2c05d0ead5bd1ca3c693fe00/pyhscodes-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0565a071de22a6ad5bfc03758b18bdc347eaa3a07e92f647aff8bea1e86d4a64",
"md5": "857963dda9e7128aa890292aa0606823",
"sha256": "c7199a7b1fb30d8686a48e66ea875b04771329abf353b809ba511d22a09c485b"
},
"downloads": -1,
"filename": "pyhscodes-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "857963dda9e7128aa890292aa0606823",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 177042,
"upload_time": "2025-07-31T08:48:26",
"upload_time_iso_8601": "2025-07-31T08:48:26.885515Z",
"url": "https://files.pythonhosted.org/packages/05/65/a071de22a6ad5bfc03758b18bdc347eaa3a07e92f647aff8bea1e86d4a64/pyhscodes-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 08:48:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sigularusrex",
"github_project": "pyhscodes#readme",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "pyhscodes"
}
JSON
