Documentation
Pincode API Documentation
The Pincode API provides a comprehensive set of endpoints to retrieve information about pincodes, states, districts, and tehsils in India. This API is designed for applications that require accurate and up-to-date location-based data for Indian postal addresses.
Base URL
https://pincodes.nskmultiservices.in/api
Authentication
API Key: This API requires an API key for access. You can obtain an API key by registering on our platform.
Authentication Method: Include the API key in the request header as:
Authorization:
Bearer YOUR_API_KEY
Rate Limiting
Premium Users: 120 requests per minute.
Regular Users: 60 requests per minute.
Error Response: HTTP 429 - Too many requests.
Endpoints
1. Get Pincode Information
Retrieve details about a specific pincode. Standalone API endpoint to retrieve pincode details of a specific pincode number.
Request:
GET /pincode/441901
Authorization: Bearer YOUR_API_KEY
Response (in JSON Format):
{
"status": "success",
"data": [
{
"postalCircle": "Maharashtra Circle",
"postalCode": 441901,
"postalRegion": "Nagpur Region",
"postalDivision": "Nagpur Moffusil Division",
"postOfficeName": "Dawki",
"branchType": "BO",
"deliveryStatus": "Delivery",
"districtName": "GONDIA",
"stateName": "MAHARASHTRA"
},
{
"postalCircle": "Maharashtra Circle",
"postalCode": 441901,
"postalRegion": "Nagpur Region",
"postalDivision": "Nagpur Moffusil Division",
"postOfficeName": "Kadikasa",
"branchType": "BO",
"deliveryStatus": "Delivery",
"districtName": "GONDIA",
"stateName": "MAHARASHTRA"
},
{
"postalCircle": "Maharashtra Circle",
"postalCode": 441901,
"postalRegion": "Nagpur Region",
"postalDivision": "Nagpur Moffusil Division",
"postOfficeName": "Nilaj",
"branchType": "BO",
"deliveryStatus": "Delivery",
"districtName": "GONDIA",
"stateName": "MAHARASHTRA"
},
{
"postalCircle": "Maharashtra Circle",
"postalCode": 441901,
"postalRegion": "Nagpur Region",
"postalDivision": "Nagpur Moffusil Division",
"postOfficeName": "Deori(Gondia)",
"branchType": "PO",
"deliveryStatus": "Delivery",
"districtName": "GONDIA",
"stateName": "MAHARASHTRA"
}
]
}
Error Codes:
404 Not Found: Pincode not found.
429 Too Many Requests: Rate limit exceeded.
2. Get State Names
Retrieve a list of states matching the provided state name.
Request Example:
GET /pincodes/state/pradesh
Authorization: Bearer YOUR_API_KEY
Response (in JSON Format):
[
{
"id": 1,
"name": "Andhra Pradesh"
},
{
"id": 2,
"name": "Arunachal Pradesh"
},
{
"id": 13,
"name": "Himachal Pradesh"
},
{
"id": 19,
"name": "Madhya Pradesh"
},
{
"id": 34,
"name": "Uttar Pradesh"
}
]
Error Codes:
404 Not Found: State not found.
3. Get District Names
Retrieve a list of districts matching the provided district name.
Request Example:
GET /pincodes/district/gondia
Authorization: Bearer YOUR_API_KEY
Response Example:
[
"Bengaluru Rural",
"Bengaluru Urban"
]
4. Get Tehsil Names
Retrieve a list of tehsils matching the provided state, district, and tehsil names.
Parameters:
- state_name (string, required): The name of the state.
- district_name (string, required): The name of the district.
- tehsil_name (string, required): Partial or full name of the tehsil.
Request Example:
GET /pincodes/tehsil/maharashtra/gondia/gaon
Authorization: Bearer YOUR_API_KEY
Response Example:
[
"Amgaon",
"Arjuni Morgaon",
"Goregaon(Gondia)",
"Navegaon Bandh"
]
5. Get Pincodes by using Post Office Name
Retrieve post office details with a specific post office name. (Includes State name, District name, Tehsil name)
Why do we require state_name, district_name and tehsil_name along with post_office_name?
There are many post offices with the same name. To avoid conflicts between two post office names, we require state_name, district_name and tehsil_name along with post_office_name to retrieve accurate data.
After getting State name, District and Tehsil name (using autocomplete functionality), you can easily get Post office details by post office name.
Parameters:
- state_name (string, required): The name of the state.
- district_name (string, required): The name of the district.
- post_office_name (string, required): Full name of the post office (Exact match NOT partial match).
Request Example:
GET /pincodes/details/maharashtra/gondia/Dongargaon
Authorization: Bearer YOUR_API_KEY
Response Example:
{
"status": "success",
"data": {
"postalCircle": "Maharashtra Circle",
"postalCode": 441614,
"postalRegion": "Nagpur Region",
"postalDivision": "Nagpur Moffusil Division",
"postOfficeName": "Dongargaon",
"branchType": "BO",
"deliveryStatus": "Delivery",
"districtName": "GONDIA",
"stateName": "MAHARASHTRA",
"location": {
"latitude": "21.3678710",
"longitude": "79.9933980"
}
}
}
Error Handling
The API uses standard HTTP status codes to indicate the success or failure of a request. Common error codes include:
- 400 Bad Request: The request was malformed or invalid.
- 401 Unauthorized: The request lacked proper authentication.
- 403 Forbidden: The user does not have permission to access the resource.
- 404 Not Found: The requested resource was not found.
- 429 Too Many Requests: The rate limit was exceeded.
- 500 Internal Server Error: An unexpected error occurred on the server.
Changelog
v1.1.0 - March 2024
- Added location coordinates (latitude/longitude) to post office details
- Improved search accuracy for post office names
- Enhanced rate limiting system
v1.0.1 - January 2024
- Fixed district name autocomplete functionality
- Added support for special characters in post office names
- Performance optimization for large data queries
v1.0.0 - December 2023
- Initial release with basic pincode, state, district, and tehsil information
- Implemented RESTful API endpoints
- Added authentication system
- Introduced rate limiting
Support and Contact Information
For support, please contact our team at [email protected] or visit our support page.
Live Demo
- Github (Javascript): https://github.com/Nandeshwar750/india-pincode-api-demo
- Live (With PHP backend): https://mostlyusedtools.com/tool/post-office-search-by-name
Postman Test Collection
Test API Endpoints with Postman
Download our pre-configured Postman collection to quickly test all API endpoints with example requests.
✓ Contains all API endpoints
✓ Includes example requests and responses
✓ Environment variables pre-configured
Error Handling
The API uses standard HTTP status codes to indicate the success or failure of a request. Common error codes include:
- 400 Bad Request: The request was malformed or invalid.
- 401 Unauthorized: The request lacked proper authentication.
- 403 Forbidden: The user does not have permission to access the resource.
- 404 Not Found: The requested resource was not found.
- 429 Too Many Requests: The rate limit was exceeded.
- 500 Internal Server Error: An unexpected error occurred on the server.
Changelog
- v1.0: Initial release with basic pincode, state, district, and tehsil information.
Support and Contact Information
You can test the API using Postman. Here's a sample collection: Download Postman Collection
Best Practices and Security
- Use HTTPS for secure communication.
- Do not expose your API key in client-side code.
- Handle errors gracefully and provide meaningful messages to the end user.