API and developer tools

Structured postal data for your applications. Authenticated access, consistent JSON, version-locked responses.

REST API

The pincode.fyi API provides read-only access to Indian PIN codes, post offices, states and districts. All responses are JSON with a consistent envelope format.

Base URL: https://api.pincode.fyi/v1

Authentication

Every request requires an API key passed in the Authorization header:

curl https://api.pincode.fyi/v1/pins/560001 \
  -H "Authorization: Bearer pin_key_prod_xxxxxxxxxxxxxxxx"

Keys use the prefix pin_key_prod_ for production and pin_key_test_ for sandbox. Keep your keys secret. Do not expose them in client-side code.

Get an API key

API access is available on request. Contact api@pincode.fyi with your use case and expected volume. We review every application and issue keys within 48 hours.

Versioning

The API uses date-based versioning. The current version is 2026-09-15, matching the data release. Every response includes an X-Pincode-Version header.

Your account is pinned to the version active when your key was issued. You can request a specific version via the Pincode-Version request header. We never introduce breaking changes within a version. New fields may be added; existing fields are never removed or renamed.

Endpoints

PIN codes

GET /v1/pins/560001
GET /v1/pins?state=karnataka&limit=20
GET /v1/pins?q=connaught&limit=10

States and districts

GET /v1/states
GET /v1/states/karnataka
GET /v1/districts
GET /v1/districts/bengaluru-urban

Post offices

GET /v1/offices/bengaluru-gpo

Search

GET /v1/search?q=bengaluru&limit=20

Bulk export

GET /v1/export/csv
GET /v1/export/json

Bulk exports are available to authenticated users. CSV and JSON downloads of the full dataset require a valid API key.

Response format

Every response follows the same envelope:

{
  "object": "pin",
  "code": "560001",
  "locality": "Bengaluru G.P.O.",
  "state": {
    "id": "karnataka",
    "name": "Karnataka"
  },
  "district": {
    "id": "bengaluru-urban",
    "name": "Bengaluru Urban"
  },
  "offices": [...],
  "office_count": 9,
  "release": "2026-09-15.1",
  "attribution": "Source: India Post via data.gov.in (GODL)"
}

List endpoints return object: "list" with data, has_more, total, page and limit fields.

Errors

{
  "error": {
    "type": "not_found",
    "message": "No PIN code found for 999999",
    "code": "pin_not_found"
  }
}

Type	Status	Meaning
`not_found`	404	Resource does not exist
`invalid_request`	400	Bad parameters
`authentication_error`	401	Missing or invalid key
`rate_limit_error`	429	Too many requests
`api_error`	500	Server error

Rate limits

Default: 100 requests per minute per key. Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1726444800

Need higher limits? Contact api@pincode.fyi.

Attribution

All data is sourced from India Post via data.gov.in under the Government Open Data License India (GODL). Every API response includes an attribution field. If you display data publicly, include the attribution.