├── docs ├── images │ ├── digipin-level-1.png │ ├── digipin-level-10.png │ ├── digipin-level-2.png │ ├── digipin-level-3.png │ ├── digipin-level-4.png │ ├── digipin-level-5.png │ ├── digipin-level-6.png │ ├── digipin-level-7.png │ ├── digipin-level-8.png │ ├── digipin-level-9.png │ ├── digipin-grid-labels.png │ └── digipin-grid-bounding-box.png └── DIGIPIN_Technical_Document.md ├── .gitignore ├── server.js ├── package.json ├── src ├── app.js ├── routes │ └── digipin.routes.js └── digipin.js ├── swagger.yaml ├── README.md └── LICENSE /docs/images/digipin-level-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-1.png -------------------------------------------------------------------------------- /docs/images/digipin-level-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-10.png -------------------------------------------------------------------------------- /docs/images/digipin-level-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-2.png -------------------------------------------------------------------------------- /docs/images/digipin-level-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-3.png -------------------------------------------------------------------------------- /docs/images/digipin-level-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-4.png -------------------------------------------------------------------------------- /docs/images/digipin-level-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-5.png -------------------------------------------------------------------------------- /docs/images/digipin-level-6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-6.png -------------------------------------------------------------------------------- /docs/images/digipin-level-7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-7.png -------------------------------------------------------------------------------- /docs/images/digipin-level-8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-8.png -------------------------------------------------------------------------------- /docs/images/digipin-level-9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-level-9.png -------------------------------------------------------------------------------- /docs/images/digipin-grid-labels.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-grid-labels.png -------------------------------------------------------------------------------- /docs/images/digipin-grid-bounding-box.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/INDIAPOST-gov/digipin/HEAD/docs/images/digipin-grid-bounding-box.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Node.js 2 | node_modules/ 3 | .env 4 | .env.local 5 | .DS_Store 6 | logs 7 | *.log 8 | npm-debug.log* 9 | yarn-debug.log* 10 | yarn-error.log* 11 | 12 | # Editor folders 13 | .vscode/ 14 | .idea/ 15 | -------------------------------------------------------------------------------- /server.js: -------------------------------------------------------------------------------- 1 | require('dotenv').config(); 2 | const app = require('./src/app'); 3 | 4 | const PORT = process.env.PORT || 5000; 5 | 6 | app.listen(PORT, () => { 7 | console.log(`DIGIPIN API is running and API docs can be found at at http://localhost:${PORT}/api-docs`); 8 | }); 9 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "digipin", 3 | "version": "1.0.0", 4 | "description": "", 5 | "main": "server.js", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1", 8 | "start": "node server.js", 9 | "dev": "nodemon server.js" 10 | }, 11 | "keywords": [], 12 | "author": "", 13 | "license": "ISC", 14 | "dependencies": { 15 | "cors": "^2.8.5", 16 | "digipin": "file:", 17 | "dotenv": "^16.4.7", 18 | "express": "^5.1.0", 19 | "morgan": "^1.10.0", 20 | "swagger-ui-express": "^5.0.1", 21 | "yaml": "^2.7.1", 22 | "yamljs": "^0.3.0" 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /src/app.js: -------------------------------------------------------------------------------- 1 | const express = require('express'); 2 | const cors = require('cors'); 3 | const morgan = require('morgan'); 4 | const digipinRoutes = require('./routes/digipin.routes'); 5 | const swaggerUi = require('swagger-ui-express'); 6 | const YAML = require('yaml'); 7 | const fs = require('fs'); 8 | const path = require('path'); 9 | 10 | // const swaggerDocument = YAML.load(path.join(__dirname, '../swagger.yaml')); 11 | const swaggerDocument = YAML.parse(fs.readFileSync(path.join(__dirname, '../swagger.yaml'), 'utf8')); 12 | 13 | const app = express(); 14 | 15 | // Middleware 16 | app.use(cors()); 17 | app.use(express.json()); 18 | app.use(morgan('dev')); 19 | 20 | // Swagger Docs Route 21 | app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); 22 | 23 | // DIGIPIN API Routes 24 | app.use('/api/digipin', digipinRoutes); 25 | 26 | module.exports = app; 27 | -------------------------------------------------------------------------------- /src/routes/digipin.routes.js: -------------------------------------------------------------------------------- 1 | const express = require('express'); 2 | const router = express.Router(); 3 | const { getDigiPin, getLatLngFromDigiPin } = require('../digipin'); 4 | 5 | router.post('/encode', (req, res) => { const { latitude, longitude } = req.body; try { const code = getDigiPin(latitude, longitude); res.json({ digipin: code }); } catch (e) { res.status(400).json({ error: e.message }); } }); 6 | 7 | router.post('/decode', (req, res) => { const { digipin } = req.body; try { const coords = getLatLngFromDigiPin(digipin); res.json(coords); } catch (e) { res.status(400).json({ error: e.message }); } }); 8 | 9 | router.get('/encode', (req, res) => { 10 | const { latitude, longitude } = req.query; 11 | try { 12 | const code = getDigiPin(parseFloat(latitude), parseFloat(longitude)); 13 | res.json({ digipin: code }); 14 | } catch (e) { 15 | res.status(400).json({ error: e.message }); 16 | } 17 | }); 18 | 19 | router.get('/decode', (req, res) => { 20 | const { digipin } = req.query; 21 | try { 22 | const coords = getLatLngFromDigiPin(digipin); 23 | res.json(coords); 24 | } catch (e) { 25 | res.status(400).json({ error: e.message }); 26 | } 27 | }); 28 | 29 | 30 | module.exports = router; -------------------------------------------------------------------------------- /swagger.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: DIGIPIN API 4 | description: Encode and decode DIGIPIN based on latitude and longitude 5 | version: 1.0.0 6 | servers: 7 | - url: http://localhost:5000/api 8 | 9 | paths: 10 | /digipin/encode: 11 | post: 12 | summary: Encode lat/lon into DIGIPIN 13 | requestBody: 14 | required: true 15 | content: 16 | application/json: 17 | schema: 18 | type: object 19 | properties: 20 | latitude: 21 | type: number 22 | longitude: 23 | type: number 24 | responses: 25 | '200': 26 | description: Successfully encoded DIGIPIN 27 | content: 28 | application/json: 29 | schema: 30 | type: object 31 | properties: 32 | digipin: 33 | type: string 34 | '400': 35 | description: Invalid input 36 | get: 37 | summary: Encode latitude and longitude into DIGIPIN 38 | parameters: 39 | - in: query 40 | name: latitude 41 | required: true 42 | schema: 43 | type: number 44 | - in: query 45 | name: longitude 46 | required: true 47 | schema: 48 | type: number 49 | responses: 50 | '200': 51 | description: Successfully encoded DIGIPIN 52 | content: 53 | application/json: 54 | schema: 55 | type: object 56 | properties: 57 | digipin: 58 | type: string 59 | '400': 60 | description: Invalid input 61 | 62 | /digipin/decode: 63 | post: 64 | summary: Decode DIGIPIN to coordinates 65 | requestBody: 66 | required: true 67 | content: 68 | application/json: 69 | schema: 70 | type: object 71 | properties: 72 | digipin: 73 | type: string 74 | responses: 75 | '200': 76 | description: Successfully decoded DIGIPIN 77 | content: 78 | application/json: 79 | schema: 80 | type: object 81 | properties: 82 | latitude: 83 | type: number 84 | longitude: 85 | type: number 86 | '400': 87 | description: Invalid DIGIPIN 88 | get: 89 | summary: Decode DIGIPIN to coordinates 90 | parameters: 91 | - in: query 92 | name: digipin 93 | required: true 94 | schema: 95 | type: string 96 | responses: 97 | '200': 98 | description: Successfully decoded DIGIPIN 99 | content: 100 | application/json: 101 | schema: 102 | type: object 103 | properties: 104 | latitude: 105 | type: number 106 | longitude: 107 | type: number 108 | '400': 109 | description: Invalid DIGIPIN 110 | -------------------------------------------------------------------------------- /src/digipin.js: -------------------------------------------------------------------------------- 1 | /** 2 | * DIGIPIN Encoder and Decoder Library 3 | * Developed by India Post, Department of Posts 4 | * Released under an open-source license for public use 5 | * 6 | * This module contains two main functions: 7 | * - getDigiPin(lat, lon): Encodes latitude & longitude into a 10-digit alphanumeric DIGIPIN 8 | * - getLatLngFromDigiPin(digiPin): Decodes a DIGIPIN back into its central latitude & longitude 9 | */ 10 | 11 | const DIGIPIN_GRID = [ 12 | ['F', 'C', '9', '8'], 13 | ['J', '3', '2', '7'], 14 | ['K', '4', '5', '6'], 15 | ['L', 'M', 'P', 'T'] 16 | ]; 17 | 18 | const BOUNDS = { 19 | minLat: 2.5, 20 | maxLat: 38.5, 21 | minLon: 63.5, 22 | maxLon: 99.5 23 | }; 24 | 25 | function getDigiPin(lat, lon) { 26 | if (lat < BOUNDS.minLat || lat > BOUNDS.maxLat) throw new Error('Latitude out of range'); 27 | if (lon < BOUNDS.minLon || lon > BOUNDS.maxLon) throw new Error('Longitude out of range'); 28 | 29 | let minLat = BOUNDS.minLat; 30 | let maxLat = BOUNDS.maxLat; 31 | let minLon = BOUNDS.minLon; 32 | let maxLon = BOUNDS.maxLon; 33 | 34 | let digiPin = ''; 35 | 36 | for (let level = 1; level <= 10; level++) { 37 | const latDiv = (maxLat - minLat) / 4; 38 | const lonDiv = (maxLon - minLon) / 4; 39 | 40 | // REVERSED row logic (to match original) 41 | let row = 3 - Math.floor((lat - minLat) / latDiv); 42 | let col = Math.floor((lon - minLon) / lonDiv); 43 | 44 | row = Math.max(0, Math.min(row, 3)); 45 | col = Math.max(0, Math.min(col, 3)); 46 | 47 | digiPin += DIGIPIN_GRID[row][col]; 48 | 49 | if (level === 3 || level === 6) digiPin += '-'; 50 | 51 | // Update bounds (reverse logic for row) 52 | maxLat = minLat + latDiv * (4 - row); 53 | minLat = minLat + latDiv * (3 - row); 54 | 55 | minLon = minLon + lonDiv * col; 56 | maxLon = minLon + lonDiv; 57 | } 58 | 59 | return digiPin; 60 | } 61 | 62 | 63 | function getLatLngFromDigiPin(digiPin) { 64 | const pin = digiPin.replace(/-/g, ''); 65 | if (pin.length !== 10) throw new Error('Invalid DIGIPIN'); 66 | 67 | let minLat = BOUNDS.minLat; 68 | let maxLat = BOUNDS.maxLat; 69 | let minLon = BOUNDS.minLon; 70 | let maxLon = BOUNDS.maxLon; 71 | 72 | for (let i = 0; i < 10; i++) { 73 | const char = pin[i]; 74 | let found = false; 75 | let ri = -1, ci = -1; 76 | 77 | // Locate character in DIGIPIN grid 78 | for (let r = 0; r < 4; r++) { 79 | for (let c = 0; c < 4; c++) { 80 | if (DIGIPIN_GRID[r][c] === char) { 81 | ri = r; 82 | ci = c; 83 | found = true; 84 | break; 85 | } 86 | } 87 | if (found) break; 88 | } 89 | 90 | if (!found) throw new Error('Invalid character in DIGIPIN'); 91 | 92 | const latDiv = (maxLat - minLat) / 4; 93 | const lonDiv = (maxLon - minLon) / 4; 94 | 95 | const lat1 = maxLat - latDiv * (ri + 1); 96 | const lat2 = maxLat - latDiv * ri; 97 | const lon1 = minLon + lonDiv * ci; 98 | const lon2 = minLon + lonDiv * (ci + 1); 99 | 100 | // Update bounding box for next level 101 | minLat = lat1; 102 | maxLat = lat2; 103 | minLon = lon1; 104 | maxLon = lon2; 105 | } 106 | 107 | const centerLat = (minLat + maxLat) / 2; 108 | const centerLon = (minLon + maxLon) / 2; 109 | 110 | return { 111 | latitude: centerLat.toFixed(6), 112 | longitude: centerLon.toFixed(6) 113 | }; 114 | } 115 | 116 | 117 | if (typeof module !== 'undefined') module.exports = { getDigiPin, getLatLngFromDigiPin }; -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DIGIPIN API by Department of Posts 2 | 3 |
4 | Ministry of Communications 5 | India Post 6 |
7 | 8 | ## A Geospatial Addressing Solution by India Post 9 | 10 | DIGIPIN (Digital PIN) is a 10-character alphanumeric geocode developed by the Department of Posts, India. It provides a precise, user-friendly way to encode geographic coordinates that can be easily shared and decoded back to latitude/longitude pairs. 11 | 12 | This open-source Node.js project exposes a public API to generate and decode DIGIPINs, supporting geolocation services, postal logistics, and spatial analysis applications. 13 | 14 | [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) 15 | [![Node.js](https://img.shields.io/badge/Node.js-v14+-green.svg)](https://nodejs.org/) 16 | [![Express](https://img.shields.io/badge/Express-v4.x-blue.svg)](https://expressjs.com/) 17 | 18 | --- 19 | 20 | ## 🏛️ About DIGIPIN 21 | 22 | The Department of Posts has undertaken an initiative to establish a Digital Public Infrastructure (DPI) for a standardized, geo-coded addressing system in India. DIGIPIN represents the foundation layer of this infrastructure. 23 | 24 | Developed in collaboration with IIT Hyderabad and NRSC (National Remote Sensing Centre, ISRO), DIGIPIN is an open-source national-level addressing grid that serves as a key component of India's digital address ecosystem. 25 | 26 | After extensive public consultation and expert review, the DIGIPIN Grid has been finalized to provide simplified addressing solutions for seamless delivery of public and private services, enabling "Address as a Service" (AaaS) across the country. 27 | 28 | ### Key Highlights 29 | 30 | - **Uniform Referencing Framework**: Provides logical, precise location identification both offline and online 31 | - **GIS Integration**: Bridges the gap between physical and digital addresses 32 | - **Cross-Sector Support**: Enhances service delivery across emergency response, e-commerce, logistics, BFSI, and governance 33 | - **Policy Alignment**: Complies with the National Geospatial Policy 2022, enriching India's geospatial knowledge stack 34 | 35 | DIGIPIN simplifies address management and enhances service delivery accuracy, promoting a thriving geospatial ecosystem for India's digital economy. 36 | 37 | --- 38 | 39 | ## ✨ Features 40 | 41 | - **Encode**: Convert latitude and longitude into a compact 10-character DIGIPIN 42 | - **Decode**: Transform a DIGIPIN back to its center-point coordinates 43 | - **Lightweight**: Optimized for performance and minimal resource usage 44 | - **RESTful API**: Clean, standard-compliant endpoints 45 | - **Interactive Documentation**: Comprehensive Swagger UI for easy exploration 46 | - **Production-Ready**: Built with Node.js and Express for reliability 47 | 48 | --- 49 | 50 | ## 📦 Installation 51 | 52 | ### Prerequisites 53 | 54 | - Node.js (v14 or higher) 55 | - npm (v6 or higher) 56 | 57 | ### Getting Started 58 | 59 | 1. **Clone the Repository** 60 | 61 | ```bash 62 | git clone https://github.com/INDIAPOST-gov/digipin.git 63 | cd digipin 64 | ``` 65 | 66 | 2. **Install Dependencies** 67 | 68 | ```bash 69 | npm install 70 | ``` 71 | 72 | 3. **Environment Setup** 73 | 74 | Create a `.env` file in the project root with the following variables: 75 | 76 | ``` 77 | PORT=5000 78 | NODE_ENV=development 79 | ``` 80 | 81 | 4. **Start the Server** 82 | 83 | ```bash 84 | npm start 85 | ``` 86 | 87 | For development with hot reloading: 88 | 89 | ```bash 90 | npm run dev 91 | ``` 92 | 93 | The API will be available at `http://localhost:5000`. 94 | 95 | --- 96 | 97 | ## 🚀 API Usage 98 | 99 | ### Encode Coordinates to DIGIPIN 100 | 101 | ``` 102 | GET /api/digipin/encode?latitude=12.9716&longitude=77.5946 103 | ``` 104 | 105 | **Response:** 106 | 107 | ```json 108 | {"digipin":"4P3-JK8-52C9"} 109 | ``` 110 | 111 | ### Decode DIGIPIN to Coordinates 112 | 113 | ``` 114 | GET /api/digipin/decode?digipin=4P3-JK8-52C9 115 | ``` 116 | 117 | **Response:** 118 | 119 | ```json 120 | {"latitude":"12.971601","longitude":"77.594584"} 121 | ``` 122 | 123 | ### Interactive API Documentation 124 | 125 | Access the Swagger UI documentation at: 126 | 127 | ``` 128 | http://localhost:5000/api-docs 129 | ``` 130 | 131 | --- 132 | 133 | ## 🔧 Contributing 134 | 135 | Contributions are welcome! Please feel free to submit a Pull Request. 136 | 137 | 1. Fork the repository 138 | 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 139 | 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 140 | 4. Push to the branch (`git push origin feature/amazing-feature`) 141 | 5. Open a Pull Request 142 | 143 | Please ensure your code adheres to the existing style and passes all tests. 144 | 145 | --- 146 | 147 | ## 📜 License 148 | 149 | This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details. 150 | 151 | --- 152 | 153 | ## 🙏 Acknowledgements 154 | 155 | - Department of Posts, Government of India 156 | - Indian Institute of Technology, Hyderabad 157 | - National Remote Sensing Centre, ISRO 158 | 159 | --- 160 | 161 | *Transforming addresses for Digital India* 162 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity 13 | authorized by the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works that 101 | You distribute, all copyright, patent, trademark, and attribution 102 | notices from the Source form of the Work, excluding those notices 103 | that do not pertain to any part of the Derivative Works; and 104 | 105 | (d) If the Work includes a "NOTICE" text file as part of its 106 | distribution, then any Derivative Works that You distribute must 107 | include a readable copy of the attribution notices contained 108 | within such NOTICE file, excluding those notices that do not 109 | pertain to any part of the Derivative Works, in at least one 110 | of the following places: within a NOTICE file distributed as 111 | part of the Derivative Works; within the Source form or 112 | documentation, if provided along with the Derivative Works; or, 113 | within a display generated by the Derivative Works, if and 114 | wherever such third-party notices normally appear. The contents 115 | of the NOTICE file are for informational purposes only and 116 | do not modify the License. You may add Your own attribution 117 | notices within Derivative Works that You distribute, alongside 118 | or as an addendum to the NOTICE text from the Work, provided 119 | that such additional attribution notices cannot be construed 120 | as modifying the License. 121 | 122 | 5. Submission of Contributions. Unless You explicitly state otherwise, 123 | any Contribution intentionally submitted for inclusion in the Work 124 | by You to the Licensor shall be under the terms and conditions of 125 | this License, without any additional terms or conditions. 126 | Notwithstanding the above, nothing herein shall supersede or modify 127 | the terms of any separate license agreement you may have executed 128 | with Licensor regarding such Contributions. 129 | 130 | 6. Trademarks. This License does not grant permission to use the trade 131 | names, trademarks, service marks, or product names of the Licensor, 132 | except as required for describing the origin of the Work and 133 | reproducing the content of the NOTICE file. 134 | 135 | 7. Disclaimer of Warranty. Unless required by applicable law or 136 | agreed to in writing, Licensor provides the Work (and each 137 | Contributor provides its Contributions) on an "AS IS" BASIS, 138 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 139 | implied, including, without limitation, any warranties or conditions 140 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 141 | PARTICULAR PURPOSE. You are solely responsible for determining the 142 | appropriateness of using or redistributing the Work and assume any 143 | risks associated with Your exercise of permissions under this License. 144 | 145 | 8. Limitation of Liability. In no event and under no legal theory, 146 | whether in tort (including negligence), contract, or otherwise, 147 | unless required by applicable law (such as deliberate and grossly 148 | negligent acts) or agreed to in writing, shall any Contributor be 149 | liable to You for damages, including any direct, indirect, special, 150 | incidental, or consequential damages of any character arising as a 151 | result of this License or out of the use or inability to use the 152 | Work (including but not limited to damages for loss of goodwill, 153 | work stoppage, computer failure or malfunction, or any and all 154 | other commercial damages or losses), even if such Contributor 155 | has been advised of the possibility of such damages. 156 | 157 | 9. Accepting Warranty or Additional Liability. While redistributing 158 | the Work or Derivative Works thereof, You may choose to offer, 159 | and charge a fee for, acceptance of support, warranty, indemnity, 160 | or other liability obligations and/or rights consistent with this 161 | License. However, in accepting such obligations, You may act only 162 | on Your own behalf and on Your sole responsibility, not on behalf 163 | of any other Contributor, and only if You agree to indemnify, 164 | defend, and hold each Contributor harmless for any liability 165 | incurred by, or claims asserted against, such Contributor by reason 166 | of your accepting any such warranty or additional liability. 167 | 168 | END OF TERMS AND CONDITIONS 169 | 170 | APPENDIX: How to apply the Apache License to your work. 171 | 172 | To apply the Apache License, Version 2.0 to your work, attach the 173 | following boilerplate notice, with the fields enclosed by brackets 174 | "[]" replaced with your own identifying information. The text should 175 | be enclosed in the appropriate comment syntax for your file. We also 176 | recommend that a file or class name and a short description of the 177 | purpose of the file be included on the same "printed page" as the 178 | license notice for easier identification within third-party archives. 179 | 180 | Copyright 08.04.2025 Department of Posts 181 | 182 | Licensed under the Apache License, Version 2.0 (the "License"); 183 | you may not use this file except in compliance with the License. 184 | You may obtain a copy of the License at 185 | 186 | http://www.apache.org/licenses/LICENSE-2.0 187 | 188 | Unless required by applicable law or agreed to in writing, 189 | software distributed under the License is distributed on an 190 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 191 | KIND, either express or implied. See the License for the 192 | specific language governing permissions and limitations 193 | under the License. 194 | -------------------------------------------------------------------------------- /docs/DIGIPIN_Technical_Document.md: -------------------------------------------------------------------------------- 1 | # Digital Postal Index Number (DIGIPIN) 2 | ## National Level Addressing Grid 3 | 4 | ### Technical Document – Final version 5 | 6 | #### Ministry of Communications Department of Posts 7 | 8 | **March, 2025** 9 | 10 | ## 1. INTRODUCTION 11 | 12 | The Department of Posts has undertaken an initiative to establish a Digital Public Infrastructure (DPI) for a standardized, geo-coded addressing system in India. As a part of this initiative, the Department is releasing final version of DIGIPIN – the foundation layer of the DPI. This initiative seeks to provide simplified addressing solutions for seamless delivery of public and private services and to enable "Address as a Service" (AaaS) across the country. 13 | 14 | DIGIPIN is an open-source national level addressing grid developed by Department of Posts in collaboration with IIT Hyderabad and NRSC, ISRO and is a key component of the digital address ecosystem. The beta version of the technical document on DIGIPIN was placed for public comments and expert opinion. 15 | 16 | After thorough analysis of the comments received through various stakeholder consultations, the Department has now finalized the DIGIPIN Grid that incorporates the relevant inputs. The DIGIPIN layer will serve as a uniform address referencing framework available both offline and online, enabling logical and precise location identification with directional attributes across India, offering significant advantages of ensuring precise geographic identification and thus complementing the conventional addressing system by providing an additional attribute. This would bridge the gap between physical locations and their digital representation. 17 | 18 | Incorporating DIGIPIN as an additional address attribute enables the leveraging of GIS capabilities, laying the foundation for future GIS-based digitalization of service delivery across various organizations in a cost-effective manner. The DIGIPIN would enhance location accuracy across various sectors by providing precise geographic coordinates, ensuring accurate service delivery and reducing emergency response times. By integrating DIGIPIN, Banking Financial Services and Insurance sector can leverage the additional address attribute, DIGIPIN, to enhance accuracy and efficiency in their KYC processes. DIGIPIN can simplify address management thus enhancing citizen convenience. 19 | 20 | A standardized geo-coded addressing system would enhance India's geo-spatial ecosystem. It would add to the geospatial knowledge stack of the country in line with the National Geospatial Policy 2022, which seeks to strengthen the geospatial sector to support national development, economic prosperity and a thriving information economy. 21 | 22 | This document outlines the technical details of **DIGIPIN**, the National-Level Addressing Grid. 23 | 24 | ## 2. DESIGN APPROACH 25 | 26 | ### 2.1 Core Concept 27 | 28 | The DIGIPIN layer is the cornerstone of the entire digital address ecosystem. 29 | 30 | DIGIPIN is visualised as an alpha numeric offline grid system that divides the geographical territory of India into uniform 4-meter by 4-meter(approx.) units. Each of these 4m X 4m units (approx.) is assigned a unique 10-digit alphanumeric code, derived from the latitude and longitude coordinates of the unit. This alphanumeric code serves as the offline addressing reference for any specific location within the DIGIPIN system. DIGIPIN is thus strictly a function of the latitude and longitude of the location represented as a grid value. The system is designed to be scalable, adaptable, and integrated with existing GIS applications. 31 | 32 | ### 2.2 DIGIPIN layer 33 | 34 | DIGIPIN layer will act as the addressing reference system which will be available offline and can be used for locating addresses in a logical manner with directional properties built into it due to the logical naming pattern followed in its construction. DIGIPIN Grid system being an addressing referencing system, can be used as the base stack for development of other ecosystems where addressing is one of the processes in the workflow. Since DIGIPIN solely represents a location and does not store any personal information, it respects privacy. 35 | 36 | ## 3. DIGIPIN : Code Architecture 37 | 38 | The detailed structure is such that the DIGIPIN is essentially an encoding of the latitude and longitude of the address into a sequence of alphanumeric symbols using the following 16 symbols: 2, 3, 4, 5, 6, 7, 8, 9, C, J, K, L, M, P, F, T. 39 | 40 | The process of identifying the cells is done in a hierarchical fashion. The encoding is performed at various levels, and the basic idea is the following: 41 | 42 | * A bounding box is used that covers the entire country. 43 | 44 | * The bounding box is split into 16 (i.e., 4x4) regions. Each region is labeled by one of symbols 2, 3, 4, 5, 6, 7, 8, 9, C, F, J, K, L, M, P, T. The first character in the code would identify one of these regions. This is called the *level-1* partition. 45 | 46 | * Each region is then subdivided into 16 subregions in a similar fashion. Each of the 16 subregions are labeled by the 16 characters. For a given region, the subregion is identified by the second character of the code. Therefore, the first two characters of the code uniquely identify one of the 16^2=256 subregions. This is called the *level-2* partition. 47 | 48 | * The encoding of successive characters, and therefore the next 8 levels is done in an identical fashion. The 10-symbol code therefore uniquely identifies one of the 16^10 cells within the bounding box. 49 | 50 | ### 3.1 Bounding box 51 | 52 | Following are the details of the bounding box used: 53 | 54 | DIGIPIN grid bounding box 55 | *Figure 1: DIGIPIN level-1 grid lines (yellow) overlaid over the Indian region showing the extent of DIGIPIN bounding box* 56 | 57 | * Longitude 63.5 – 99.5 degrees east 58 | * Latitude 2.5 – 38.5 degrees north 59 | * The Coordinate Reference System (CRS) used in the proposed code design is EPSG:4326. Using EPSG:4326 (WGS84 datum at epoch 2005) has several advantages like wide recognition and adoption, simplicity and global coverage. 60 | 61 | The choice of the corner points of the bounding box are based on the following considerations: 62 | 63 | * This includes the entire territory of India. 64 | 65 | * Since the proposed extent has latitudinal and longitudinal extent of 36°, the final grid size after 10th iteration is a perfect square and has smaller size of 3.8m x 3.8m. 66 | 67 | * This bounding box ensures alignment of DIGIPIN level-1 grid lines with Survey of India's 0.25° x 0.25° toposheets (topographical sheet numbering system), which are used for mapping at 1:50K scale 68 | 69 | * Includes the maritime Exclusive Economic Zone (EEZ), and therefore DIGIPIN allows to provide addresses to Indian assets in the sea (oil rigs, future man-made islands, etc.), or even potentially be used to locate regions in the sea by the maritime sector. The maritime EEZ is computed assuming 200 nautical miles extent from the coastline. 70 | 71 | * Level-1 grid lines do not cut through cities with very large population 72 | 73 | * The level-10 cells would be almost rectangular, but the dimensions would vary based on the latitude. This would translate to a cell of size smaller than 3.8-meter x 3.8-meter if measured at the equator, and this is reasonable given the accuracy of most current commercially available Global Navigation Satellite System (GNSS). 74 | 75 | ### 3.2 Properties of DIGIPIN 76 | 77 | * DIGIPIN contains the geographic location of the area. It is possible to extract the latitude and longitude of the address from the DIGIPIN with low complexity. 78 | 79 | * DIGIPIN has been designed for the Indian context. All points of interest to India (including maritime regions) can be assigned codes, and it is possible to assign code even in areas that are very densely populated. 80 | 81 | * The format of the DIGIPIN is intuitive and human-readable. Effort was made to infuse a sense of directionality within the format of DIGIPIN. 82 | 83 | * DIGIPIN is independent of the land use pattern and the structure built. Note that DIGIPIN is designed as a permanent digital infrastructure, that does not change with changes in the names of state, city or locality, or with changes in the road network in an area. The DIGIPIN is designed to be robust to accommodate future developments and changes. The arrival of a new building in a community, or even a new village or city in a district, or changes in the name of a road or locality will not affect the underlying DIGIPIN. 84 | 85 | * The length of the DIGIPIN is designed to be as small as possible in order to provide an efficient digital representation of addresses. 86 | 87 | ### 3.3 Labelling of regions at various levels 88 | 89 | DIGIPIN grid labels 90 | *Figure 2: Labelling of DIGIPIN level-1 grids (left) and 4x4 grid used for labelling (right)* 91 | 92 | * In first iteration (level-1), the bounding box is divided into 16 regions using a 4x4 grid and each region is labelled using 16 symbols, 2, 3, 4, 5, 6, 7, 8, 9, C, F, J, K, L, M, P, and T, as shown in ***Figure 2***. 93 | 94 | * A consistent gridding and labelling scheme is applied across all subsequent iterations (Levels 2 to 10). For these levels, the same labelled grid is utilized, with the labelling process carried out in a hierarchical manner. 95 | 96 | * Each Level-1 region is further split into 16 sub-regions called Level-2 regions as illustrated in the ***Figure 3***. The regions are hierarchically partitioned into sub-regions in an identical fashion. 97 | 98 | * Symbols are assigned in anticlockwise fashion, spiraling outwards. The grid provides some sense of directionality and adjacency cells labeled by consecutive symbols (such as 6 and 7) are geographical neighbors. 99 | 100 | DIGIPIN grid labels 101 | *Figure 3: Labelling of DIGIPIN level-2 grids (left) and 4x4 grid used for labelling (right)* 102 | 103 | ### 3.4 Assigning DIGIPIN to coordinates coinciding with DIGIPIN Grid Lines 104 | 105 | In some of the cases, coordinates of a location may coincide with DIGIPIN grid lines. In such scenario, the location is assigned a DIGIPIN symbol of the adjoining right-side (eastward) grid, if it falls on a vertical (north-south) grid line. Similarly, a DIGIPIN symbol of adjoining up- side (northward) grid is assigned, if location coincides with a horizontal (east-west) grid line. The coordinates coinciding with DIGIPIN line intersection are assigned to adjoining top-right grid. The exception is made to coordinates coinciding with top-most (38.5° N) and right-most (99.5° E) grid lines wherein DIGIPIN symbols of the adjoining bottom-side (southward) grid and left- side (westward) grids are assigned, respectively. 106 | 107 | ### 3.5 Grid sizes at various levels 108 | 109 | As explained above, the DIGIPIN generation is an iterative procedure. At level-1, the bounding box is divided into 16 (4x4) regions. The total latitudinal and longitudinal width of bounding box is 36°, resulting in 9° x 9° regions at level-1. Similarly, at level-2, each 9° x 9° region is further divided into 16 (4x4) sub-regions, resulting in 2.25° x 2.25° regions. The same process is carried out up to 10 levels. The table below shows a relation between the DIGIPIN code length, corresponding grid size and approximate linear distance at the equator. It gives an estimate of the positional uncertainty associated with DIGIPIN code length. For instance, a DIGIPIN code of length 6 represents a ~ 1km x 1km region. It requires an additional 4 digits to precisely locate a 3.8m x 3.8m region inside this region. 110 | 111 | | Code Length | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 112 | |-------------|---|---|---|---|---|---|---|---|---|---| 113 | | Grid Width | 9° | 2.25° | 33.75′ | 8.44′ | 2.11′ | 0.53′ | 0.13′ | 0.03′ | 0.5″ | 0.12″ | 114 | | Approx. Distance | 1000 km | 250 km | 62.5 km | 15.6 km | 3.9 km | 1 km | 250 m | 60 m | 15 m | 3.8 m | 115 | 116 | *Table 1: DIGIPIN grid size at different levels* 117 | 118 | ## 4. Key differences between Beta version and Final Version of DIGIPIN 119 | 120 | * A modification in the extent of the DIGIPIN bounding box from 63.5° - 99°E & 1.5°- 39°N to 63.5°- 99.5°E & 2.5°- 38.5°N) 121 | 122 | * The replacement of characters G, W, and X with C, F and T to maintain the phonetic and visual clarity of DIGIPIN, while maintaining the sequence of characters. 123 | 124 | * A uniform gridding and labelling scheme across all iterations (1-10). 125 | 126 | ## 5. Illustration of DIGIPIN Generation Process 127 | 128 | The ***figure 4*** illustrates the complete procedure for generating DIGIPIN for a specific location. For example, the geographical coordinates of Dak Bhawan (28.622788°N, 77.213033°E) are marked with a red star on the India base map. The figure demonstrates the selection of DIGIPIN symbols at each level, based on the grid encompassing Dak Bhawan. The DIGIPIN of Dak Bhawan is 39J 49L L8T4. 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 139 | 142 | 143 | 144 | 145 | 146 | 147 |
Level-1Level-2
137 | DIGIPIN Level 1 138 | 140 | DIGIPIN Level 2 141 |
39
148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 158 | 161 | 162 | 163 | 164 | 165 | 166 |
Level-3Level-4
156 | DIGIPIN Level 3 157 | 159 | DIGIPIN Level 4 160 |
J4
167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 177 | 180 | 181 | 182 | 183 | 184 | 185 |
Level-5Level-6
175 | DIGIPIN Level 5 176 | 178 | DIGIPIN Level 6 179 |
9L
186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 196 | 199 | 200 | 201 | 202 | 203 | 204 |
Level-7Level-8
194 | DIGIPIN Level 7 195 | 197 | DIGIPIN Level 8 198 |
L8
205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 215 | 218 | 219 | 220 | 221 | 222 | 223 |
Level-9Level-10
213 | DIGIPIN Level 9 214 | 216 | DIGIPIN Level 10 217 |
T4
224 | 225 | *Figure 4: Illustration of procedure for deriving DIGIPIN of a known location* 226 | --------------------------------------------------------------------------------