The Library has 2 Client function wrappers with JavaScript as per the Technical Documentation shared in https://www.indiapost.gov.in/VAS/Pages/digipin.aspx

This document provides technical details for two core JavaScript functionalities related to the DIGIPIN (Digital Postal Index Number) system:

1. Get_DIGIPIN(lat, lon): Generates a DIGIPIN from given latitude and longitude coordinates.

2. Get_LatLng_By_Digipin(vDigiPin): Converts a DIGIPIN back into its corresponding latitude and longitude coordinates.

Both functions operate based on a hierarchical grid system as defined in the official DIGIPIN technical specifications.

1. Get_DIGIPIN(lat, lon) - DIGIPIN Generation Function

Purpose

This function takes geographic coordinates (latitude and longitude) as input and encodes them into a 10-digit alphanumeric DIGIPIN code. This code represents a specific 4x4 meter (approx.) grid cell within the defined bounding box of India.

Function Signature

function Get_DIGIPIN(lat, lon) { /* ... */ }

Parameters

• lat (number): The latitude coordinate in decimal degrees. Expected range: 2.50 to 38.50.

• lon (number): The longitude coordinate in decimal degrees. Expected range: 63.50 to 99.50.

Returns

• string: The 10-digit alphanumeric DIGIPIN code, formatted with hyphens after the 3rd and 6th characters (e.g., "39J-49L-L8T4").

• string: An empty string ('') if the input coordinates are out of the valid bounding box.

• string: The string "Out of Bound" if the calculated grid cell for the first level falls into a designated 'out of bound' area within the L matrix (though for valid coordinates within the bounding box, this specific case is less likely to be triggered by the initial lat/lon checks).

Logic Description

1. Initialization:

   • Defines a 4×4 L (Labelling Grid) matrix containing 16 alphanumeric characters used for encoding: [['F', 'C', '9', '8'], ['J', '3', '2', '7'], ['K', '4', '5', '6'], ['L', 'M', 'P', 'T']].

   • Initializes vDIGIPIN as an empty string, row and column to 0.

   • Sets the initial MinLat, MaxLat, MinLon, MaxLon for the entire bounding box (2.50∘ to 38.50∘ latitude, 63.50∘ to 99.50∘ longitude).

   • LatDivBy and LonDivBy are set to 4, representing the division into 4×4 sub-regions at each level.

2. Input Validation:

   • Checks if lat is within [2.50, 38.50] and lon is within [63.50, 99.50]. If not, it displays an error message (via showMessage function) and returns an empty string.

3. Iterative Encoding (10 Levels):

   • A loop runs for 10 levels (Lvl from 1 to 10), corresponding to the 10 characters of the DIGIPIN.

   • In each level:

     • LatDivDeg and LonDivDeg are calculated to determine the angular size of each sub-cell in the current bounding box.

     • The code iteratively finds the row and column within the current 4×4 grid that lat and lon fall into. This involves narrowing down the MinLat/MaxLat and MinLon/MaxLon for the next level.

     • Special handling for boundary conditions (e.g., coordinates exactly on a grid line) ensures they are assigned to the correct cell as per DIGIPIN specifications.

     • The character L[row][column] corresponding to the identified cell is appended to vDIGIPIN.

     • Hyphens (-) are inserted after the 3rd and 6th characters (Lvl == 3 || Lvl == 6).

     • The MinLat, MaxLat, MinLon, MaxLon are updated to reflect the boundaries of the specific sub-cell found in the current level, which then becomes the new bounding box for the next iteration.

4. Final Output:

   • Returns the complete vDIGIPIN string.

Considerations

• Precision: The function's output precision depends on the floating-point precision of the input lat and lon values and the internal calculations. The DIGIPIN is designed to represent approximately a 3.8m×3.8m area at level 10.

• Error Handling: Uses an internal showMessage function (not part of the core logic, but for UI feedback) to indicate out-of-range inputs.

2. Get_LatLng_By_Digipin(vDigiPin) - DIGIPIN Reverse Lookup Function

Purpose

This function takes a 10-digit alphanumeric DIGIPIN code as input and decodes it to determine the approximate latitude and longitude coordinates (center point) of the corresponding grid cell.

Function Signature

function Get_LatLng_By_Digipin(vDigiPin) { /* ... */ }

Parameters

• vDigiPin (string): The 10-digit alphanumeric DIGIPIN code. It can include or exclude hyphens (e.g., "39J-49L-L8T4" or "39J49LL8T4").

Returns

• object: An object { latitude: number, longitude: number } containing the decoded coordinates if successful. The coordinates are returned with a precision of 6 decimal places.

• string: An error message string (e.g., "Invalid DIGIPIN Length", "Invalid DIGIPIN Character") if the input is invalid or a character is not recognized.

Logic Description

1. Normalization and Validation:

   • Hyphens (-) are removed from the input vDigiPin to simplify processing.

   • The length of the normalized vDigiPin is checked; it must be exactly 10 characters. If not, an error is returned.

2. Initialization:

   • Defines the same 4×4 L (Labelling Grid) matrix used in the generation function.

   • Sets the initial MinLat, MaxLat, MinLng, MaxLng to the full bounding box extent of India.

   • LatDivBy and LngDivBy are set to 4.

3. Iterative Decoding (10 Levels):

   • A loop runs for 10 levels (Lvl from 0 to 9), processing each character of the DIGIPIN.

   • In each level:

     • digipinChar is extracted from the vDigiPin at the current level.

     • LatDivVal and LngDivVal are calculated based on the current bounding box.

     • The L matrix is iterated to find the ri (row index) and ci (column index) that correspond to the digipinChar. If the character is not found, an error is returned.

     • Based on the ri and ci, the Lat1, Lat2, Lng1, Lng2 values are calculated. These represent the specific sub-cell boundaries that the digipinChar identifies within the current level's bounding box.

     • MinLat, MaxLat, MinLng, MaxLng are updated to these newly calculated boundaries, effectively zooming into the identified sub-cell for the next iteration.

4. Final Coordinate Calculation:

   • After 10 iterations, MinLat, MaxLat, MinLng, MaxLng define the smallest 4×4 meter grid cell.

   • The center latitude (cLat) is calculated as (MaxLat + MinLat) / 2.

   • The center longitude (cLng) is calculated as (MaxLng + MinLng) / 2.

5. Output:

   • Returns an object containing the latitude and longitude, formatted to 6 decimal places.

Considerations

• Accuracy: The returned latitude and longitude represent the center of the final 4x4 meter grid cell. Due to the discrete nature of the DIGIPIN grid, any point within that 4×4 meter cell will map to the same DIGIPIN.

• Error Handling: The function includes checks for invalid DIGIPIN length and unrecognized characters within the L matrix. These errors are propagated as string messages.