indian-address-parser
Parse raw, unstructured Indian address strings into 13 structured fields. Three model backends, all downloaded automatically from Hugging Face — this package ships only inference code, no weights:
tinybert(default) — a full fine-tune of huawei-noah/TinyBERT_General_4L_312D (model card). ~14M params, token classification (BIO tagging) rather than JSON generation — by far the smallest and fastest option.t5— a full fine-tune of google/flan-t5-small (model card). ~77M params, single download, a couple points more accurate thantinybert, at noticeably higher inference cost.qwen— a LoRA adapter on Qwen/Qwen3-0.6B (model card). ~596M params, needs both the adapter and the base model, the most accurate option.
Input: "FLAT NO.32, UTTARA TOWERS, MG ROAD GUWAHATI , Kamrup Unclassified AS 781029"
Output: {"houseNumber": "FLAT NO.32", "houseName": "UTTARA TOWERS", "poi": null,
"street": "MG ROAD", "subsubLocality": null, "subLocality": null, "locality": null,
"village": null, "subDistrict": null, "district": "Kamrup", "city": "GUWAHATI",
"state": "AS", "pincode": "781029"}
Install
pip install indian-address-parser
Usage
Python
from indian_address_parser import AddressParser
parser = AddressParser() # default backend "tinybert" — downloads model weights from HF on first use
result = parser.parse("FLAT NO.32, UTTARA TOWERS, MG ROAD GUWAHATI , Kamrup Unclassified AS 781029")
print(result)
# Batch
results = parser.parse_batch([addr1, addr2, addr3])
# A couple points more accurate, slower
parser = AddressParser(backend="t5")
# Most accurate model
parser = AddressParser(backend="qwen")
CLI
# Single address (defaults to the tinybert backend)
indian-address-parser "FLAT NO.32, UTTARA TOWERS, MG ROAD GUWAHATI , Kamrup Unclassified AS 781029"
# Batch from stdin
cat addresses.txt | indian-address-parser --stdin
# Batch from a file, JSONL output
indian-address-parser --file addresses.txt --out results.jsonl
# A couple points more accurate, slower
indian-address-parser --backend t5 "..."
# Most accurate model
indian-address-parser --backend qwen "..."
Fields
houseNumber, houseName, poi, street, subsubLocality, subLocality,
locality, village, subDistrict, district, city, state, pincode
Any field not present in the address is null. For the generative backends (t5,
qwen), output that can't be parsed as JSON leaves all fields null and a
_parse_error key holds the raw model output; tinybert is token classification, not
generation, so it always produces a well-formed dict and _parse_error never applies.
Choosing a backend
tinybert (default) |
t5 |
qwen |
|
|---|---|---|---|
| Base model | TinyBERT_General_4L_312D | google/flan-t5-small | Qwen/Qwen3-0.6B + LoRA |
| Task | token classification (BIO) | JSON generation | JSON generation |
| Params | ~14M | ~77M | ~596M |
| Download | single model | single model | adapter + base model |
| Mean field accuracy (held-out test) | 78.8% | 80.6% | 82.4% |
tinybert is the default — at ~14M params (5x smaller than t5, 40x smaller than
qwen) it's by far the cheapest to download and run, a single forward pass instead of
autoregressive generation, and still lands within 2-4 points of both larger models on
mean field accuracy (though its village/subLocality recall is essentially 0% — see
its model card for the full breakdown). Reach for t5 when those couple of points
matter and the extra inference cost is acceptable, or qwen when accuracy matters most
(its edge is largest on the lower-recall fields like poi, subDistrict, subLocality).
Model details, evaluation metrics, and known limitations
See the model cards for training data, config, full per-field evaluation results, and known limitations (locality/subLocality/subsubLocality/village field-boundary ambiguity, etc.):
- gagan1985/tinybert-4l-312d-indian-address-parser (tinybert, default)
- gagan1985/flan-t5-small-indian-address-parser (t5)
- gagan1985/qwen3-0.6b-indian-address-parser (qwen)
Datasets
- gagan1985/indian-addresses-gold — the gold-labeled training data behind all three models
- gagan1985/indian-addresses-raw — the 4.37M-record raw, unlabeled corpus this gold set was drawn from (PII-redacted; see the dataset card for methodology)
Comparison to other models
benchmarks/ has two head-to-head comparisons against Shiprocket's
models on a shared, 237-example held-out gold test set (both models use
different field taxonomies than ours, so only overlapping fields are scored):
- All three of our backends vs
open-modernbert-indian-address-ner
— see
benchmarks/README.md - Our
tinybertbackend vs Shiprocket's other model, open-tinybert-indian-address-ner — a same-name matchup (though not the same architecture size: ours is ~14M params, theirs ~66.4M). Our model wins on all 9 shared fields. Seebenchmarks/TINYBERT_COMPARISON.md
Apple Silicon (MLX) users
This package uses transformers (+peft for the qwen backend), which works on CUDA,
MPS, and CPU but is not the fastest path on Apple Silicon. For MLX-native inference of
the qwen backend, see the mlx/ subfolder of its
Hugging Face repo
instead.
License
Apache 2.0 (matching the base models: google/flan-t5-small, Qwen/Qwen3-0.6B, huawei-noah/TinyBERT_General_4L_312D).
Metadata
Release files for indian-address-parser 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| indian_address_parser-0.3.0.tar.gz | 98.8 kB | Without provenance | Details for indian_address_parser-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| indian_address_parser-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for indian_address_parser-0.3.0-py3-none-any.whl |
Total release size: 112.7 kB
Release files / indian_address_parser-0.3.0.tar.gz
| Download URL | indian_address_parser-0.3.0.tar.gz |
|---|---|
| Size | 98.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f876a1728e9426876648c7008cf1b569c08269f3c00553f4e2a744ca9f63398
|
|
BLAKE2b-256 checksum How to use checksums |
054a8af1c27cea159d9e9f700aa9e06869ef8199ca9b0adc4ba439f21a2cb9e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / indian_address_parser-0.3.0-py3-none-any.whl
| Download URL | indian_address_parser-0.3.0-py3-none-any.whl |
|---|---|
| Size | 14.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc297428f74e342d28affab2ca7dd1185f1d8aec28389c6ac8fc923565c76f6c
|
|
BLAKE2b-256 checksum How to use checksums |
1425b6e9fb4d851a9578cc392add475d8a90cfa7866da04e79647a7356139d9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for indian-address-parser 0.3.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.