Offline codes

AfriHex codes are pure maths: a code is the grid cell's number written in letters and digits. So an app can create and read codes on the phone, with no internet, and get exactly the same codes as the API.

That helps where coverage is poor: riders, field and health workers, surveys and village deliveries. A phone's GPS works without mobile data, and the share message below goes by an ordinary text message.

The toolkit is open source (MIT): npm and GitHub.

Install

npm install @afrihex/offline

It runs in browsers, React Native and Node.js 18 or newer (as an ES module).

Create and read codes

import { encode, decode, shortCode } from '@afrihex/offline'

encode(5.6221843, -0.1729361, 7)   // 'AF-GH-7-0GXTJJBDZZZZZ'
shortCode('AF-GH-7-0GXTJJBDZZZZZ') // 'AF-GH-7-0GXTJJBD'
decode('AF-GH-7-0GXTJJBD')         // { lat, lng, level: 7, boundary, areaM2, ... }

encode refuses points outside Ghana. decode accepts the full or short form and rejects mistyped codes. Store the full code; show people the short form. Both work everywhere in the API.

Share a location from GPS

import { shareMessage } from '@afrihex/offline'

const m = shareMessage({ lat: 5.63194, lng: -0.13998, accuracyM: 8, at: new Date(), label: 'Ama' })
m.text
// Ama: AfriHex AF-GH-13-…
// 5.63194, -0.13998 (±8 m) at 14:05
// https://maps.google.com/?q=5.63194,-0.13998

The message works for anyone: the code for AfriHex apps, plus coordinates and a map link that open in any map app, with the accuracy and time so the reader knows how far to trust it.

The level follows the GPS accuracy, so a code never claims more precision than the phone has. Readings worse than 50 m are marked rough and the message asks the person to describe where they are.

Choosing a level

Level	Cell size	Use for
7	about 2 km across	a neighbourhood (the API's default)
10	about 130 m	a few streets
12	about 20 m	a compound or building
13	about 7 m	a gate

To find a person or a house, use 12 or 13. Level 7 only gets someone to the right neighbourhood.

What still needs the API

Only the code maths is offline. These need the API and our data:

• Converting to and from GhanaPostGPS codes
• Landmark directions ("Opposite Shell filling station"): GET /v2/reverse?descriptors=true
• Gates and building entrances
• Routing, tracking and proof of delivery

A common pattern: create the code offline, send it at once by text message, and add landmark directions when the phone is back online.

The format

The format spec describes codes precisely enough to write your own encoder in any language, and the repository's test codes come from the API itself. Version 1 codes will always decode the same way.