Skip to content

API_CONTRACT.md

Latest commit

 

History

History
176 lines (112 loc) · 3.41 KB

API_CONTRACT.md

File metadata and controls

176 lines (112 loc) · 3.41 KB

DIGIPIN Library API Contract

This document defines the canonical public interface that all DIGIPIN language libraries must implement. The goal is consistency, predictability, and cross-language parity.

1. Core concepts

  • DIGIPIN is a pure, deterministic encoding
  • No I/O, no networking, no external dependencies
  • Same input → same output in every language
  • No hidden state

2. Public functions (mandatory)

2.1 Encode: latitude/longitude → DIGIPIN

Purpose Convert geographic coordinates to a 10-character DIGIPIN code.

Signature (conceptual)

encode(latitude, longitude) → digipin

Parameters

  • latitude

    • Type: floating point number
    • Unit: decimal degrees
    • Range: 2.5 ≤ latitude ≤ 38.5

  • longitude

    • Type: floating point number
    • Unit: decimal degrees
    • Range: 63.5 ≤ longitude ≤ 99.5

Return value

  • digipin

    • Type: string
    • Format: 10 alphanumeric characters (optionally formatted with separators)
    • Example: 39J-49L-L8T4 or 39J49LL8T4

Behavior

  • Uses EPSG:4326 (WGS84)
  • Implements DIGIPIN hierarchical 4×4 grid exactly as per spec
  • Handles boundary conditions exactly as defined in the technical document

Errors

  • Invalid latitude or longitude → error/exception
  • Inputs outside bounding box → error/exception

2.2 Decode: DIGIPIN → geographic coordinates

Purpose Convert a DIGIPIN code to the geographic location it represents.

Signature (conceptual)

decode(digipin) → location

Parameters

  • digipin

    • Type: string
    • Length: 10 characters (separators may be ignored)
    • Case-insensitive (must be normalized internally)

Return value

  • location

    • latitude (float, decimal degrees)
    • longitude (float, decimal degrees)

The returned coordinates represent the center (centroid) of the DIGIPIN grid cell.

Errors

  • Invalid length
  • Invalid characters
  • Invalid grid sequence

3. Optional (but recommended) public helpers

These improve usability but must not change core behavior.

3.1 Normalize DIGIPIN

normalize(digipin) → digipin
  • Removes separators
  • Converts to uppercase
  • Validates character set

3.2 Validate DIGIPIN

is_valid(digipin) → boolean
  • Returns true if syntactically and semantically valid
  • Must not throw (pure validation)

4. Formatting rules

  • Internal representation: no separators

  • Optional formatting for display:

    • After 3rd and 6th character (e.g. XXX-XXX-XXXX)

  • Formatting must be cosmetic only

5. Error handling rules (important)

  • Libraries must use idiomatic error handling:

    • Exceptions (Python, Swift, C#)
    • Result / Option (Rust)
    • (value, error) (Go)

  • Error messages should be:

    • Deterministic
    • Human-readable
    • Not localized (English only)

6. What is explicitly out of scope

  • Address resolution
  • Reverse geocoding
  • Maps, tiles, or visualization
  • Persistence or databases
  • Network services or APIs

7. Versioning guarantee

  • This API contract is stable starting v1.0.0
  • Any breaking change requires a major version bump
  • All language SDKs must adhere to this contract

8. Compliance requirement

A DIGIPIN library is considered compliant if and only if:

  • It implements encode and decode
  • It passes all shared test vectors
  • It follows the boundary and labeling rules of the official specification