1. Exact Match

Use matching to retrieve all places and postal metadata tied to a pincode.

Important: The Pincode should be of 6 digits, in string format

indiapins.matching('110011')

[{'Name': 'Nirman Bhawan', 'BranchType': 'PO', 'DeliveryStatus': 'Delivery',
  'Circle': 'Delhi Circle', 'District': 'NEW DELHI', 'Division': 'New Delhi Central Division',
  'Region': 'Delhi Region', 'State': 'DELHI', 'Pincode': 110011,
  'Latitude': 28.6108611, 'Longitude': 77.2148611},
 {'Name': 'Udyog Bhawan', 'BranchType': 'PO', 'DeliveryStatus': 'Non Delivery',
  'Circle': 'Delhi Circle', 'District': 'NEW DELHI', 'Division': 'New Delhi Central Division',
  'Region': 'Delhi Region', 'State': 'DELHI', 'Pincode': 110011,
  'Latitude': 28.6111111, 'Longitude': 77.2127500}]

Records include these keys:

• Name, BranchType, DeliveryStatus

• Circle, Region, Division, District, State

• Pincode (integer in returned data)

• Latitude and Longitude (float or None)

If the pincode is well-formed but absent in the dataset, matching raises ValueError.

2. Valid Pincode

Use isvalid to quickly check whether a pincode exists in the dataset.

indiapins.isvalid('110011')

True

isvalid returns False for correctly formatted but unknown pincodes (for example "000000"), and raises validation errors only for malformed input.

3. District by Pincode

Use districtmatch when you only need district information.

indiapins.districtmatch('302005')

'Jaipur'

If multiple district values exist for a pincode, they are returned as a comma-separated string. If the pincode format is valid but absent in the dataset, districtmatch raises ValueError.

4. Coordinates of Pincode

Use coordinates to get office-level latitude/longitude mappings.

indiapins.coordinates('110011')

{'Udyog Bhawan': {'latitude': '28.6111111', 'longitude': '77.2127500'},
'Nirman Bhawan': {'latitude': '28.6108611', 'longitude': '77.2148611'}}

Notes:

• Entries with missing coordinates are excluded

• Latitude/longitude values are returned as strings for consistency

• Unknown but well-formed pincodes raise ValueError

5. Geospatial Queries

Compute geodesic distance between two pincodes:

indiapins.distance("110001", "400001", metric="km")

Find nearest pincodes from a location:

indiapins.nearest_pincodes(28.6139, 77.2090, k=5)

Find neighboring pincodes from a source pincode:

indiapins.nearest_to_pincode("110001", k=10)

Find pincodes or delivery offices within a radius:

indiapins.pincodes_in_radius("110001", radius_km=5)
indiapins.delivery_offices_in_radius((28.6139, 77.2090), radius_km=3)

Directional and matrix utilities:

indiapins.bearing("110001", "400001")
indiapins.midpoint("110001", "400001")
indiapins.distance_matrix(["110001", "400001", "560001"], metric="km")