pinsearch-sdk 0.1.0

search Indian postal information by PIN code, state, or district

pinsearch-sdk

A lightweight Python SDK for searching Indian Postal Index Number (PIN) code data.

pinsearch-sdk provides fast offline access to Indian postal information, including:

• PIN code lookups
• State-based searches
• District-based searches
• Office information
• Geographic coordinates (when available)

The SDK ships with a pre-indexed dataset and requires no external API or internet connection.

---

Installation

pip install pinsearch-sdk

or with uv:

uv add pinsearch-sdk

---

Quick Start

from pinsearch_sdk import PinSearch

client = PinSearch()

record = client.get("504273")

print(record.officename)
print(record.district)
print(record.statename)

Output:

Karjibheempur B.O
MANCHERIAL
TELANGANA

---

Lookup by PIN Code

from pinsearch_sdk import PinSearch

client = PinSearch()

record = client.get("504273")

print(record)

Returns:

PincodeData(
    circlename='Telangana Circle',
    regionname='Hyderabad Region',
    divisionname='Adilabad Division',
    officename='Karjibheempur B.O',
    pincode='504273',
    officetype='BO',
    delivery='Delivery',
    district='MANCHERIAL',
    statename='TELANGANA',
    latitude=19.335427,
    longitude=79.4928856
)

If the PIN code does not exist:

record = client.get("000000")

print(record)

None

---

Search by State

from pinsearch_sdk import PinSearch

client = PinSearch()

for office in client.by_state("TELANGANA"):
    print(office.officename)

The method returns an iterator and yields PincodeData objects lazily.

Convert to a list if needed:

results = list(client.by_state("TELANGANA"))

---

Search by District

from pinsearch_sdk import PinSearch

client = PinSearch()

for office in client.by_district("MANCHERIAL"):
    print(office.pincode)

---

Iterate Over the Entire Dataset

from pinsearch_sdk import PinSearch

client = PinSearch()

for office in client:
    print(office.pincode)

---

Data Model

Every search method returns a PincodeData object.

@dataclass
class PincodeData:
    circlename: str
    regionname: str
    divisionname: str
    officename: str
    pincode: str
    officetype: str
    delivery: str
    district: str
    statename: str
    latitude: float | None
    longitude: float | None

---

Example

from pinsearch_sdk import PinSearch

client = PinSearch()

record = client.get("504273")

print(record.officename)
print(record.latitude)
print(record.longitude)

Output:

Karjibheempur B.O
19.335427
79.4928856

---

Performance

• PIN code lookups are O(1)
• State searches use pre-built indexes
• District searches use pre-built indexes
• Search results are yielded lazily to reduce memory usage

---

Data Source

The information is derived from publicly available dataset from Open Government Data (OGD) Platform India The data is intended for informational purposes and may not always reflect the latest changes made by India Post.

---

License

This project is licensed under the MIT License. See LICENSE for details.