Geocoding, Indian addresses and DIGIPIN

A survey typed “Station Road” for a house, and the geocoder answered with the middle of the street, 1,257 m from the door, without a warning. Every geocoding answer has a precision, and you must read it before you trust the point.

Here you judge answers by what they matched and where they landed, keep a public geocoder’s rules, and see why a PIN code names an area. Then you take DIGIPIN, ten symbols for every square of about 4 m across India, from its specification to an encoder.

Geocoding turns an address into a point, and every answer has a precision

Geocodinggeocoding: Turning text, such as an address or a place name, into coordinates. Reverse geocoding turns coordinates back into the nearest address or place. turns text, an address or a place name, into coordinates; reverse geocoding turns coordinates back into an address. The answer is the geocoder’s best match: for a reverse query Nominatim, OpenStreetMap’s geocoder, finds the closest suitable object and returns its address, not one computed for the exact point (Nominatim, reverse geocoding). It reports what each answer matched as its place_rank: 30 for a house or a point of interest, 28 for an interpolated address, 26 and 27 for streets, 20 for a neighbourhood, 17 and 18 for a town and 13 to 16 for a city (Nominatim, place ranking). Here are six made-up answers in Nominatim’s format, beside doors a survey measured:

"""Six made-up first answers in the shape of a Nominatim jsonv2 search result, one for each address of a survey in the
track's town, beside the door of each address as the survey measured it (WGS 84 degrees). No service produced them."""

TOWN_BOX = (18.0887, 75.0, 18.1430, 75.0757)  # south, west, north, east of the town
LICENCE = "Made-up sample for this lesson; a real answer carries its service's licence here"

SURVEY = [
    # (the address as typed, the surveyed door, the geocoder's first answer)
    ("H0001, Hill Street", (18.1261627, 75.0196281),
     {"lat": "18.1261139", "lon": "75.0196621", "place_rank": 30, "addresstype": "house", "display_name": "H0001, Hill Street"}),
    ("45 Station Road", (18.1367008, 75.0323310),
     {"lat": "18.1360229", "lon": "75.0327658", "place_rank": 28, "addresstype": "house", "display_name": "45, Station Road"}),
    ("Station Road", (18.0991005, 75.0327022),
     {"lat": "18.1103986", "lon": "75.0330824", "place_rank": 26, "addresstype": "road", "display_name": "Station Road"}),
    ("Ward W07", (18.1185301, 75.0482080),
     {"lat": "18.1158188", "lon": "75.0472620", "place_rank": 20, "addresstype": "neighbourhood", "display_name": "W07"}),
    ("The town", (18.1040638, 75.0642720),
     {"lat": "18.1158209", "lon": "75.0378096", "place_rank": 18, "addresstype": "town", "display_name": "The town"}),
    ("12 Hill Stret", (18.1250428, 75.0202292),
     {"lat": "18.3442330", "lon": "74.6829325", "place_rank": 30, "addresstype": "house", "display_name": "12, Hill Street, another town"}),
]

"""Judge six geocoder answers the way a survey can: what each answer is, from its place rank, how far it lies from the
door the survey measured, and whether it lies in the town at all."""
import math

from answers import SURVEY, TOWN_BOX

# The lowest search rank of each kind of place, as Nominatim's ranking documentation groups them.
KINDS = [(30, "house or place"), (28, "address range"), (26, "street"), (21, "dwelling or block"),
         (20, "neighbourhood"), (19, "village or suburb"), (17, "town"), (13, "city"), (0, "region or country")]


def kind(rank):
    return next(name for low, name in KINDS if rank >= low)


def metres(a, b):
    """Great-circle distance on a sphere of the Earth's mean radius, 6,371,008.8 m: close enough to rate a match."""
    (la1, lo1), (la2, lo2) = (map(math.radians, p) for p in (a, b))
    h = math.sin((la2 - la1) / 2) ** 2 + math.cos(la1) * math.cos(la2) * math.sin((lo2 - lo1) / 2) ** 2
    return 2 * 6_371_008.8 * math.asin(math.sqrt(h))


def in_town(p):
    s, w, n, e = TOWN_BOX
    return s <= p[0] <= n and w <= p[1] <= e


print(f"{'address':<20}{'answer':<20}{'rank':>4}  {'from the door':>13}  in the town")
good = 0
for address, door, answer in SURVEY:
    at = (float(answer["lat"]), float(answer["lon"]))
    off = metres(door, at)
    usable = answer["place_rank"] >= 28 and in_town(at)
    good += usable
    print(f"{address:<20}{kind(answer['place_rank']):<20}{answer['place_rank']:>4}  {off:>11,.0f} m  {'yes' if in_town(at) else 'NO'}")
print(f"\nanswers at address level and inside the town: {good} of {len(SURVEY)}")

address             answer              rank  from the door  in the town
H0001, Hill Street  house or place        30            7 m  yes
45 Station Road     address range         28           88 m  yes
Station Road        street                26        1,257 m  yes
Ward W07            neighbourhood         20          318 m  yes
The town            town                  18        3,087 m  yes
12 Hill Stret       house or place        30       43,162 m  NO

answers at address level and inside the town: 2 of 6

Only 2 of the 6 answers can stand for a house. The rank says what was matched, not how far it lies: ward W07’s rank-20 answer landed 318 m from the door, the rank-26 street 1,257 m. The misspelt “12 Hill Stret” came back at rank 30, 43 km away in another town: a confident wrong answer that only the town’s box caught.

A public geocoder sets rules: one request a second, a name, a cache and credit

OpenStreetMap’s public Nominatim service is shared, and its usage policy sets the terms:

The policy may change without notice, so read it before each new use. The programs of this lesson never call the service: they use made-up answers.

A PIN code names a delivery area, and a DIGIPIN names a square of about 4 m

Indian addresses take many forms, and the six-digit PIN codePIN code (Postal Index Number): India's six-digit postal code: its digits give the zone, the sub-zone and sorting district, the route and the delivery post office, so a code names the area one office delivers to. is the part the post sorts by: its digits give the zone, the sub-zone and sorting district, the route, and the delivery post office (India Post, Tamil Nadu Circle). A PIN names the area one office delivers to. The directory copy in MySmartCoPilot’s PIN code tool lists 165,601 post offices under 19,586 PIN codes, about 8.5 to a code, so a point for a PIN is at best one office’s point.

DIGIPINDIGIPIN: The Department of Posts' code for any point in a box around India: ten symbols, each naming one of 4 by 4 cells at one level, down to a cell of about 4 m., from the Department of Posts with IIT Hyderabad and NRSC, ISRO, names places by their coordinates instead (DIGIPIN). Its box runs from 63.5° to 99.5° E and from 2.5° to 38.5° N, in WGS 84. It is cut into 4 by 4 cells ten times over, and each cell takes one of 16 symbols from the same grid at every level (technical document):

Ten symbols name a cell of about 3.8 m at the equator. Follow the document’s own example, Dak Bhawan, down the ten levels:

A DIGIPIN adds a location to an address; it does not replace one. Indian addresses can carry both: the PIN code for the post, the DIGIPIN for the door. Three things decide whether such codes and points can be trusted:

• The grid-line rules give the code of a point that lies exactly between two cells.
• Measured precision turns a cell’s degrees, and a phone’s error, into metres.
• A position audit finds directory points that are missing, swapped, copied or wrong.

DIGIPIN to the letter: an encoder, a decoder and their edge cases Pro: opens with a Pro, Premium or Ultimate pass

A geocoder client that keeps the usage rules, run against a stand-in Pro: opens with a Pro, Premium or Ultimate pass

Auditing PIN code positions before you map them, reproduced Pro: opens with a Pro, Premium or Ultimate pass

Practise: DIGIPIN from both ends

Encode a point, then decode a code back to the centre of its cell:

GRID = ["FC98", "J327", "K456", "LMPT"]  # rows from north to south, columns from west to east
SOUTH, NORTH, WEST, EAST = 2.5, 38.5, 63.5, 99.5


def encode(lat, lon):
    """The DIGIPIN of a point in WGS 84 degrees, written XXX-XXX-XXXX."""
    # Replace this line: cut the box into 4 x 4 cells ten times and add the symbol of the cell the point is in.
    return ""

from encode import encode


def test_dak_bhawan():
    """gives Dak Bhawan the code of the technical document, 39J-49L-L8T4"""
    assert encode(28.622788, 77.213033) == "39J-49L-L8T4"


def test_the_official_readme_example():
    """encodes the example of the official code's README"""
    assert encode(13.11179621, 80.20264269) == "4T3-96F-42L7"


def test_a_point_on_two_grid_lines():
    """sends a point on two lines of the first level to the cell to its north-east"""
    assert encode(29.5, 72.5) == "CLL-LLL-LLLL"


def test_the_corners_of_the_box():
    """keeps the corners of the box inside it, the north-east one included"""
    assert encode(2.5, 63.5) == "LLL-LLL-LLLL"
    assert encode(38.5, 99.5) == "888-888-8888"
    assert encode(38.5, 63.5) == "FFF-FFF-FFFF"


def test_a_point_outside_the_box():
    """refuses a point west of 63.5° E"""
    try:
        encode(28.6, 60.0)
    except ValueError:
        return
    raise AssertionError("encode(28.6, 60.0) should raise ValueError")

GRID = ["FC98", "J327", "K456", "LMPT"]  # rows from north to south, columns from west to east
SOUTH, NORTH, WEST, EAST = 2.5, 38.5, 63.5, 99.5


def decode(code):
    """The centre (lat, lon) of the cell a DIGIPIN names, in degrees rounded to 6 decimals."""
    # Replace this line: find each symbol's row and column in GRID and keep that cell of the current box.
    return (0.0, 0.0)

from decode import decode


def test_dak_bhawan():
    """decodes 39J-49L-L8T4 to the centre of Dak Bhawan's cell"""
    assert decode("39J-49L-L8T4") == (28.622793, 77.213049)


def test_the_official_readme_example():
    """decodes the example of the official code's README"""
    assert decode("4P3JK852C9") == (12.971601, 77.594584)


def test_lower_case_without_hyphens():
    """reads a code in lower case, written without its hyphens"""
    assert decode("39j49ll8t4") == (28.622793, 77.213049)


def test_codes_that_are_not_digipins():
    """refuses a code with a symbol outside the grid, and one with nine symbols"""
    for bad in ("39J-49L-L8TG", "39J-49L-L8T"):
        try:
            decode(bad)
        except ValueError:
            continue
        raise AssertionError(f"decode({bad!r}) should raise ValueError")

Interview questions

Warm-up (fresher): Why can a PIN code not stand in for a household’s location?

A PIN code names the area one delivery post office serves, and the directory lists about 8.5 offices for each code: an area of many streets, not a point. A point stored for a PIN is at best one office’s. Use the PIN to join an address to its district; for a location, geocode the address, or record coordinates or a DIGIPIN at the door.

Three longer geocoding questions live in the module’s question bank, each with its first step:

Key takeaways

• A geocoder answers with its best match: keep each answer’s rank, and test it against the area it should fall in.
• A public geocoder’s rules are part of using it: one request a second, your application’s name, a cache and the credit.
• A PIN code names a delivery area; a DIGIPIN names a cell of about 4 m from coordinates alone.