GET /search/hsn
================

Search HSN codes by keyword with hierarchical grouping. Returns up to the top 6 headings, each with up to 6 best-matching items.

Request
-------

- Method: ``GET``
- Path: ``/search/hsn``
- Auth: ``X-API-Key: <your_key>``

Query Parameters
----------------

- ``query`` (string, required): Keyword or phrase (min 2 chars)

Curl Example
------------

.. code-block:: bash

  curl --location 'https://api.taxlookup.fastgst.in/search/hsn?query=milk' \
  --header 'X-API-Key: *****'

Successful Response
-------------------

.. code-block:: json

  {
    "success": true,
    "data": [
      {
        "hierarchy": "0401",
        "description": "Milk and Cream Not Concentrated nor Containing Added Sugar or Other Sweetening Matter",
        "match_score": 0.98,
        "matches": [
          { "hsn_code": "040110", "description": "Of a Fat Content by Weight Not Exceeding 1", "match_score": 0.88 },
          { "hsn_code": "04011000", "description": "Of a Fat Content by Weight Not Exceeding 1", "match_score": 0.88 },
          { "hsn_code": "040120", "description": "Of a Fat Content by Weight Exceeding 1 but Not Exceeding 6", "match_score": 0.88 },
          { "hsn_code": "04012000", "description": "Of a Fat Content by Weight Exceeding 1 but Not Exceeding 6", "match_score": 0.88 },
          { "hsn_code": "04015000", "description": "Of a Fat Content by Weight Exceeding 10", "match_score": 0.88 },
          { "hsn_code": "040140", "description": "Of a Fat Content by Weight Exceeding 6 but Not Exceeding 10", "match_score": 0.88 }
        ]
      }
      // ... more groups ...
    ],
    "meta": {
      "api_version": "v1",
      "timestamp": "2025-10-12",
      "request_id": "req_0HNG9G0COVSG5:00000001"
    }
  }

Notes
-----

- Advanced fuzzy search and local model tuned for semantic matching
- Up to 6 matches per hierarchy group
- ``match_score`` ranges from 0 to 1
- Use this endpoint to identify candidate HSN codes before retrieving details or tax rates

Errors
------

See :doc:`../conventions` for common errors and shapes.