gst-validator

Validate Indian GSTINs offline and pull taxpayer details from the public GST portal.

Install · CLI · Library · Data · Contributing

A typed Python library and CLI for the Indian GST taxpayer search. It checks a GSTIN's structure and checksum without touching the network, and wraps the portal's undocumented endpoints in objects you can actually hold.

from gst_validator import GSTIN, GSTClient

GSTIN.is_valid("27AAACR5055K1Z7")  # True, offline, no network

with GSTClient() as client:
    client.fetch_goods_and_services("27AAACR5055K1Z7")  # no captcha needed

Why this exists

The GST portal has no public API for taxpayer search. What it has is a captcha-gated web form and a handful of undocumented JSON endpoints that return "NA" for null, dd/mm/yyyy for dates, two different shapes for the same field, and HTTP 200 for errors. This package absorbs that so your code sees datetime.date, None and exceptions.

What it does

Documentation

A taste of it

Validate a whole spreadsheet column without touching the network:

gst-validator - --offline --column gstin --format csv < suppliers.csv > checked.csv

Add the portal data that needs no captcha:

gst-validator - --offline --enrich --format json < gstins.txt -o enriched.json

Look one up properly, solving a captcha once:

gst-validator 27AAACR5055K1Z7 --json | jq -r .legal_name

List every GSTIN a company holds, found by its PAN:

gst-validator --pan AAACR5055K --json

From Python:

from gst_validator import GSTIN, validate_many

GSTIN.is_valid("27AAACR5055K1Z7")  # True, offline

for row in validate_many(["27AAACR5055K1Z7", "nope"]):
    print(row.value, row.is_valid, row.error)

Install

uv add gst-validator          # into a uv project
pip install gst-validator     # or plain pip
uvx gst-validator --help      # or run it without installing

Python 3.13 or newer. Two runtime dependencies: httpx for the HTTP layer and rich for the CLI output.

Then read the CLI guide or the library guide, depending on how you mean to use it.

Development

uv sync              # install, including dev dependencies
uv run pytest        # fully offline, via httpx.MockTransport
uv run mypy          # strict
uv run pyright       # strict
uv run ruff check .

Tests parse payloads with the exact shape the live portal returns (tests/fixtures/: a service provider, a manufacturer, a statutory body, a cancelled registration, a composition dealer, a UIN holder and a goods list) and assert unmapped == {}, so a portal schema change fails the suite instead of quietly losing data.

The GSTINs used here and in the tests are of two kinds, both deliberate. Some are real, published registrations of large organisations - 27AAACR5055K1Z7 is Reliance Industries, and the suite also covers ones belonging to Amazon, Indian Railways, GoDaddy and UNICEF - which are printed on the invoices those bodies issue and are corporate records, not anyone's personal data. The rest are invented and checksum-valid, used wherever a payload had to be made up. No individual's registration appears anywhere in the repository, and the fixtures captured from live lookups have their identifying values replaced.

Releasing

Releases are automated with release-please. Commits on main follow Conventional Commits (feat:, fix:, portal:, ...); a bot keeps a release pull request up to date with the next version number and the changelog. Merging it bumps the version, tags, publishes to PyPI and creates the GitHub release. Nothing is tagged or edited by hand. Details in CONTRIBUTING.md.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the setup and the house rules; the short version:

uv sync
uv run pytest -q && uv run ruff check . && uv run mypy && uv run pyright

Two rules matter more than the rest: tests never touch the network (everything goes through httpx.MockTransport), and no real taxpayer's data in the repo - fixtures use a public company's registration or a fictional, checksum-valid GSTIN.

If the portal changes shape, that is a portal change issue; include the output of --raw with the identifying values replaced.

Everyone taking part is expected to follow the Code of Conduct.

Security reports go through private advisories, not public issues. See SECURITY.md.

Links

• CLI guide · Library guide · Recipes · Portal reference
• PyPI
• Changelog
• Contributing · Code of Conduct · Security policy
• Official GST developer portal - the licensed GSP route for unattended, high-volume use

License

MIT. See LICENSE.