PIN Code API
Branch Office Lookup

PIN Code API Documentation

This API provides postal branch office information by pincode. It loads a small index first and then downloads only the required shard file for the requested pincode. This keeps initial page load lightweight and avoids fetching the entire dataset at once.

Base URL: https://cdn.sarbeswarpanda.in/pincode/data/pincode_api_shards Index file: index.json Search mode: 6-digit pincode

Overview

The API is organized as a set of shard JSON files. Each shard contains postal office records, and the main index maps a pincode to the specific shard file that should be fetched.

The front-end implementation uses a two-step workflow:

  1. Load index.json to determine the shard for a pincode.
  2. Fetch the relevant shard and filter records for branch offices.
  • Primary endpointindex.json
  • Shard folderpincode_api_shards/
  • Search format6 digits
  • Office filterofficetype = BO

Base URL

https://cdn.sarbeswarpanda.in/pincode/data/pincode_api_shards

All index and shard files are served from this base directory. The application uses a small dataset index instead of loading the full database immediately.

Index Structure

The API exposes an index.json file containing pincode-to-shard mappings. The key is the pincode, and the value is the shard file name that contains the records for that pincode.

{ "504273": "504.json", "752077": "752.json" }

Example interpretation:

The client loads only this file at startup and then fetches the requested shard only when a pincode is searched.

Shard Data Format

A shard file contains an array of postal office records. Each record includes office metadata such as pincode, office type, district, state, name, and geographic coordinates.

[ { "officename": "DHLW Branch", "pincode": "504273", "officetype": "BO", "district": "Adilabad", "statename": "TELANGANA", "circlename": "SOUTHERN CIRCLE", "regionname": "HYDERABAD REGION", "divisionname": "ADILABAD DIVISION", "delivery": "Delivery", "latitude": "19.0972", "longitude": "79.0765" } ]

The client filters records using:

String(record.pincode).trim() === pin && String(record.officetype).trim().toUpperCase() === "BO"

Search Flow

  1. User submits a 6-digit pincode.
  2. Client validates input using /^\d{6}$/.
  3. Client checks whether the pincode exists in index.json.
  4. If found, it fetches the assigned shard file.
  5. Client filters records where office type is BO.
  6. All matching branch offices are rendered into cards and the first result is opened.

Response / Data Model

Field Type Description
officename string Name of the branch office.
pincode string 6-digit postal pincode.
officetype string Office type, such as BO, HO, SO, etc. The app filters for BO.
district string District name.
statename string State name.
circlename string Postal circle name.
regionname string Regional name.
divisionname string Division name.
delivery string Delivery availability or status.
latitude string / number Latitude; used for a Google Maps embed when valid.
longitude string / number Longitude; used with latitude for map location.

Example JavaScript Usage

const API_BASE = "https://cdn.sarbeswarpanda.in/pincode/data/pincode_api_shards"; async function fetchBranchOffices(pin) { const indexResponse = await fetch(`${API_BASE}/index.json`); const index = await indexResponse.json(); const shard = index[pin]; if (!shard) { console.log("Pincode not found"); return []; } const shardResponse = await fetch(`${API_BASE}/${encodeURIComponent(shard)}`); const shardData = await shardResponse.json(); return shardData.filter(record => String(record.pincode).trim() === pin && String(record.officetype).trim().toUpperCase() === "BO" ); } const offices = await fetchBranchOffices("504273"); console.log(offices);

Map Integration

When both latitude and longitude are valid numbers, the client builds a Google Maps URL in embed mode:

https://www.google.com/maps?q=19.0972,79.0765&t=h&z=17&output=embed

A clickable link is also generated to open the same coordinates in Google Maps in a new tab.

Security & Validation Notes

The frontend includes HTML escaping before rendering values from API data into the page. This reduces the risk of malformed HTML or script injection when displaying office names and metadata.

function escapeHTML(value) { return String(value ?? "").replace(/[&<>"']/g, char => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" }[char])); }
Input is limited to exactly 6 digits before a search is performed.

Error Handling

The client handles several failure states:

Notes