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.
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:
- Load index.json to determine the shard for a pincode.
- Fetch the relevant shard and filter records for branch offices.
Base URL
https://cdn.sarbeswarpanda.in/pincode/data/pincode_api_shardsAll 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:
- 504273 → data for pincode 504273 is in 504.json
- 752077 → data for pincode 752077 is in 752.json
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
- User submits a 6-digit pincode.
- Client validates input using /^\d{6}$/.
- Client checks whether the pincode exists in index.json.
- If found, it fetches the assigned shard file.
- Client filters records where office type is BO.
- 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=embedA 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]));
}Error Handling
The client handles several failure states:
- Index could not be loaded.
- Requested shard could not be fetched.
- Pincode not found in the index.
- No branch office record found for the given pincode.
- Latitude/longitude not available for a selected office.
Notes
- The API is designed for lightweight client-side loading.
- Only the needed shard is downloaded after a pincode search.
- Only branch office records are displayed for the search result.
- The API is best used in combination with a frontend that validates, filters, and displays records.