DigiPIN for Developers: Algorithm, Offline Encoding, APIs, and Integration

-

DigiPIN for Developers: Algorithm, Offline Encoding, APIs, and Integration

DigiPIN is useful to developers because its core operation is deterministic. A coordinate can be converted into a 10-character code, and a valid code can be decoded into the centre of its grid cell without a central lookup database.

Official Parameters

  • Bounding box longitude: 63.5°E to 99.5°E.
  • Bounding box latitude: 2.5°N to 38.5°N.
  • Coordinate reference system: EPSG:4326/WGS84.
  • Partitioning: 4×4 at every level.
  • Levels: 10.
  • Alphabet: 2, 3, 4, 5, 6, 7, 8, 9, C, J, K, L, M, P, F, T.

Labelling Matrix

F C 9 8
J 3 2 7
K 4 5 6
L M P T

Rows are selected from north to south and columns from west to east. At each level, the current latitude-longitude rectangle is divided into sixteen smaller cells. The symbol in the selected row and column is appended to the code.

Coordinate-to-Code Process

  1. Validate latitude and longitude against the official bounding box.
  2. Calculate the current latitude and longitude step sizes.
  3. Determine the row using the distance from the northern boundary.
  4. Determine the column using the distance from the western boundary.
  5. Append the matrix symbol.
  6. Replace the current rectangle with the selected cell.
  7. Repeat ten times.

Code-to-Coordinate Process

  1. Remove optional hyphens and spaces.
  2. Normalize letters to uppercase.
  3. Validate exactly ten characters.
  4. Find each character in the official matrix.
  5. Update the latitude-longitude rectangle at each level.
  6. Return the centre of the final cell.

The decoded point is the centre of the cell, not necessarily the original GPS observation.

Reference TypeScript Encoder

const GRID = [
  ["F", "C", "9", "8"],
  ["J", "3", "2", "7"],
  ["K", "4", "5", "6"],
  ["L", "M", "P", "T"]
];

function encode(lat: number, lon: number): string {
  let minLat = 2.5, maxLat = 38.5;
  let minLon = 63.5, maxLon = 99.5;
  let code = "";

  if (lat < minLat || lat > maxLat || lon < minLon || lon > maxLon) {
    throw new Error("Coordinates outside DigiPIN bounds");
  }

  for (let level = 0; level < 10; level++) {
    const latStep = (maxLat - minLat) / 4;
    const lonStep = (maxLon - minLon) / 4;
    const row = Math.max(0, Math.min(3, Math.floor((maxLat - lat) / latStep)));
    const column = Math.max(0, Math.min(3, Math.floor((lon - minLon) / lonStep)));

    code += GRID[row][column];
    const oldMaxLat = maxLat;
    maxLat = maxLat - row * latStep;
    minLat = oldMaxLat - (row + 1) * latStep;
    minLon = minLon + column * lonStep;
    maxLon = minLon + lonStep;
  }

  return code;
}

Production code should follow India Post’s official implementation, particularly for boundary coordinates and floating-point edge cases.

Normalization and Validation

Accept display formats such as 39J-49L-L8T4 but store the canonical form 39J49LL8T4. Remove spaces and hyphens, uppercase letters, enforce ten characters, and reject characters outside the official alphabet.

Database Design

Store DigiPIN as a fixed-length indexed string. Also store latitude, longitude, horizontal accuracy, capture time, source, and purpose when the code is linked to a user or operational record.

digipin VARCHAR(10) NOT NULL
latitude DECIMAL(10,7)
longitude DECIMAL(10,7)
horizontal_accuracy_m DECIMAL(8,2)
captured_at TIMESTAMP
consent_status VARCHAR(32)

Prefix searches can support hierarchical grouping, but a prefix is not the same as a district, ward, city, or postal boundary.

Offline Architecture

The encoder and decoder can run inside a mobile app, browser, desktop program, or backend service. No central lookup is required for the mathematical conversion.

Other features may still need network access, including maps, routing, account synchronization, address sharing, consent management, reverse geocoding, and delivery status.

Accuracy Metadata

Do not confuse grid size with measurement accuracy. Store the device’s horizontal accuracy separately. A 3.8-metre cell may be generated from a location estimate that is accurate to 10 metres, 30 metres, or worse.

Security and Privacy

  • Treat a DigiPIN linked to a person as sensitive location data.
  • Encrypt stored records and transport traffic.
  • Separate location codes from identity fields when possible.
  • Use role-based access and audit logs.
  • Do not expose residential DigiPINs in public URLs unnecessarily.
  • Collect location only for a clear purpose.

Testing Checklist

  • Test the official Dak Bhawan example.
  • Test all bounding-box edges.
  • Test coordinates on vertical and horizontal grid lines.
  • Test the top-most and right-most boundaries.
  • Test invalid symbols and incorrect lengths.
  • Test round-trip encode-decode behaviour.
  • Compare independent implementations against official vectors.

Conclusion

DigiPIN is straightforward to integrate at the algorithmic level, but production quality depends on precise validation, correct boundary handling, reliable location metadata, privacy controls, and a clear separation between location, identity, property, and access information.

Comments

Post a Comment