Skip to main content

gstinapi

Python client for gstinapi.in — search any Indian GST number (GSTIN) and get back the legal name, trade name, GST status, taxpayer type and registered address, live from India's official GSP network.

No dependencies beyond the standard library. Python 3.9+.

pip install gstinapi

Quick start

import os
from gstinapi import GstinApi

client = GstinApi(api_key=os.environ["GSTIN_API_KEY"])

result = client.lookup("33AAACC1206D1ZN")

print(result["data"]["legal_name"])   # CENTRAL WAREHOUSING CORPORATION
print(result["data"]["status"])       # Active
print(result["credits_remaining"])    # 9

Get an API key at gstinapi.in/register — every account gets up to 100 free lookups, no card required.

Why use this instead of calling the API directly

It refuses to spend a credit on a GSTIN that cannot exist. The 15th character of a GSTIN is a checksum over the first 14. This client verifies it locally before making a request, so a mistyped number fails instantly and for free:

from gstinapi import is_valid_gstin

is_valid_gstin("33AAACC1206D1ZN")  # True
is_valid_gstin("22AAAAA0000A1Z5")  # False — pattern is fine, checksum is not

The API itself only checks the pattern, so that second number would have cost you a request.

It retries the right failures. A 429 or 502 is worth asking again with backoff. A 402 or 404 is not — repeating those only wastes time, so it doesn't.

Errors

Each HTTP failure raises a specific exception, all subclassing GstinError:

from gstinapi import GstinApi, NotFound, InsufficientCredits, InvalidFormat, GstinError

try:
    result = client.lookup(gstin)
except NotFound:
    print("This GST number is not registered.")
except InsufficientCredits:
    print("Out of credits — top up to continue.")
except InvalidFormat:
    print("That does not look like a GST number.")
except GstinError as exc:
    print(exc.status, exc.code, exc.message)
Exception HTTP Meaning
InvalidFormat 400 Not a valid GSTIN. No credit charged.
Unauthorized 401 Missing or wrong API key.
InsufficientCredits 402 Out of credits.
AccountDeactivated 403 Account disabled.
NotFound 404 GSTIN is not in the GST database.
RateLimited 429 Over 60 requests/minute. Retried automatically.
ProviderUnavailable 502 Upstream GST network hiccup. Retried automatically.

Taxpayer profile (include="profile")

Pass include="profile" to get the taxpayer's profile in the same call, at no extra credit:

result = client.lookup("33AAACC1206D1ZN", include="profile")
data = result["data"]

data["business_constitution"]    # constitution of business
data["state_jurisdiction"]       # state jurisdiction (and _code)
data["centre_jurisdiction"]      # centre jurisdiction (and _code)
data["nature_of_business"]       # list of activities at the principal place
data["einvoice_status"]          # "Yes" | "No"
data["last_updated"]             # date the GST network last updated the record
data["additional_addresses"]     # additional places of business
data["address_details"]["city"]  # district and city are filled only with the profile
result["profile_complete"]       # False = lookup succeeded, profile could not be fetched

The profile is best-effort: if it cannot be fetched, the lookup still succeeds, the profile fields come back None and profile_complete is False. It works with bulk lookups too:

client.lookup_many(gstins, concurrency=5, include="profile")

Bulk lookups

lookup_many runs a thread pool and settles each entry separately, so one bad number never sinks the batch:

for r in client.lookup_many(gstins, concurrency=5):
    if r.ok:
        print(r.gstin, r.data["data"]["legal_name"])
    else:
        print(r.gstin, r.error.code)

Usage stats

client.usage()
# {'total_calls': 42, 'success': 40, 'errors': 2, 'credits_used': 40}

This does not consume a credit.

Options

GstinApi(
    api_key=os.environ["GSTIN_API_KEY"],  # required
    timeout=15.0,            # per attempt, seconds
    retries=2,               # 429/502 only
    validate_checksum=True,  # set False to match the API exactly
)

What you get back

{
    "success": True,
    "gstin": "33AAACC1206D1ZN",
    "credits_remaining": 9,
    "response_ms": 182,
    "data": {
        "gstin": "33AAACC1206D1ZN",
        "legal_name": "CENTRAL WAREHOUSING CORPORATION",
        "trade_name": "CENTRAL WAREHOUSING CORPORATION",
        "status": "Active",
        "taxpayer_type": "Regular",
        "business_constitution": None,
        "registration_date": "2017-07-01",
        "cancellation_date": None,
        "state_code": "33",
        "state_jurisdiction": None,
        "address": "No.4, North Avenue, Saidapet, Chennai",
        "pincode": "600015",
        "nature_of_business": None,
        "block_status": "Unblocked",
    },
}

business_constitution, state_jurisdiction and nature_of_business are usually None on a plain lookup. Pass include="profile" (see above) to have them filled.

Working with pandas

import pandas as pd

df = pd.read_csv("vendors.csv")
results = {r.gstin: r for r in client.lookup_many(df["gstin"].tolist())}

df["legal_name"] = df["gstin"].map(lambda g: results[g].data["data"]["legal_name"] if results[g].ok else None)
df["gst_status"] = df["gstin"].map(lambda g: results[g].data["data"]["status"] if results[g].ok else results[g].error.code)

Keep your key on the server

The API key is a credential: anyone holding it can spend your credits. Read it from an environment variable — never commit it, and never ship it in client-side code.

License

MIT

Metadata

Release files for gstinapi 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gstinapi 1.1.0
File Size Uploaded Provenance Actions
gstinapi-1.1.0.tar.gz 11.0 kB Without provenance Details for gstinapi-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gstinapi 1.1.0
File Interpreter ABI Platform Actions
gstinapi-1.1.0-py3-none-any.whl Python 3 none any Details for gstinapi-1.1.0-py3-none-any.whl

Total release size: 19.8 kB

Release files / gstinapi-1.1.0.tar.gz

Download URL gstinapi-1.1.0.tar.gz
Size 11.0 kB
Tags Source
SHA-256 checksum
How to use checksums
87705ef7ed5fd1343c36710048b4a2a7a3499544f6ca835f32e44617ecf3bce4
BLAKE2b-256 checksum
How to use checksums
01542416951263c1904c30f616c89c37117a3d04800e9d9cc73a437142e3bb95
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / gstinapi-1.1.0-py3-none-any.whl

Download URL gstinapi-1.1.0-py3-none-any.whl
Size 8.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
537dd0a1bec136cf7c894abad82d814658939cd50b2b1e6ffdc948db971f5c33
BLAKE2b-256 checksum
How to use checksums
0c767712b250e5cda994b6cc6cd521ecb4623344a89e321a9571dd79698b13a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for gstinapi 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page