Metadata-Version: 2.4
Name: indian-pincode-geo
Version: 2.0.0
Summary: Geo companion for indian-pincode: post offices, coordinates, nearby search, reverse lookup. Offline, no runtime network calls.
Author-email: DevZoy <contact@devzoy.com>
License: MIT
Project-URL: Homepage, https://github.com/devzoy/indian-pincode
Project-URL: Repository, https://github.com/devzoy/indian-pincode
Project-URL: Issues, https://github.com/devzoy/indian-pincode/issues
Keywords: india,pincode,postal,geospatial,reverse-geocode,offline
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: indian-pincode==2.0.0

# indian-pincode-geo

Geo companion for `indian-pincode`: **post offices, coordinates, nearby search, and
reverse lookup**. Offline, no runtime network calls. Depends on `indian-pincode` (exact
same version). Importing it also enables `indian_pincode.lookup(...)` etc.

Requires Python **>=3.10**. Install via the core extra: `pip install "indian-pincode[geo]"`.

## Usage

```python
import indian_pincode_geo as geo

offices = geo.lookup("110001")
print(offices[0]["office_name"])              # New Delhi GPO
print(offices[0]["office_type"])              # HO
nearby = geo.find_nearby(28.6304, 77.2177, radius_km=2)
print(nearby[0]["office_name"])               # Connaught Place SO
```

- Result keys are **snake_case**: `pincode, office_name, office_type, delivery_status,
  district, state, state_source, latitude, longitude, geo_quality` (and `distance_km`
  from `find_nearby`).
- `find_nearby(lat, lon, radius_km=5, limit=20, include_suspect=False)` returns offices
  sorted by distance. `reverse_lookup(lat, lon)` returns the nearest pincode centroid
  `{pincode, distance_km}`. `get_centroid(pin)` returns `{latitude, longitude}`.

## Data quality

India Post coordinates are **approximate**. The pipeline flags points that are far from
their pincode's cluster as `geo_quality == "suspect"` — about **6.5%** of offices — and
`find_nearby`/`reverse_lookup` **exclude them by default**. Pass `include_suspect=True` to
include them. About 8.4% of offices have no usable coordinates after cleaning. Full stats:
[data/REPORT.md](https://github.com/devzoy/indian-pincode/blob/main/data/REPORT.md).

## License

- **Code:** MIT.
- **Data:** derived from India Post / data.gov.in under GODL-India (attribution
  required) — see [DATA_LICENSE.md](DATA_LICENSE.md).
