Handling “Adjacent Goil” addresses: building deliveries in Ghana with TypeScript

Dominic — Wed, 11 Nov 2026 08:37:16 +0000

In Ghana, "Adjacent Goil Filling Station, Madina Zongo Junction" is a perfectly normal address. Riders call customers three times to find the gate, cash on delivery goes unreconciled, and nobody can prove the parcel reached the right place.

I've been building AfriHex to fix that whole chain, and today the official TypeScript SDK is on npm. Here's a tour of what you can build with it.

npm install @afrihex/sdk

It's typed end to end, has zero dependencies, and runs in Node.js 18+ and modern browsers.

1. Get a key, then a test key

curl -X POST "https://api.afrihex.com/v2/self/signup" \
  -H "Content-Type: application/json" \
  -d '{"name": "Your App", "email": "you@example.com"}'

Then create a test key so your experiments don't touch real customers:

import { AfriHex } from '@afrihex/sdk'

const afrihex = new AfriHex({ apiKey: process.env.AFRIHEX_API_KEY! })

const { key } = await afrihex.account.createTestKey() // afx_test_…, shown once
const test = new AfriHex({ apiKey: key })

Test calls don't use your quota, keep their data separate from live data, and never send real SMS.

2. Parse addresses the way people actually write them

parse understands "adjacent", "opposite", "behind", "beside", "near", "next to" and "after":

const { parsed } = await afrihex.addresses.parse(
  'Adjacent Goil Filling Station, Madina Zongo Junction'
)

parsed?.anchors?.[0]   // { relation: 'adjacent', name: 'goil filling station' }
parsed?.geocode_query  // 'madina zongo junction'

// Find the landmark itself, anchored to the place
const goil = await afrihex.landmarks.geocode({
  q: 'goil',
  anchor: 'Madina Zongo Junction',
  kind: 'fuel_station',
})
goil.matches[0] // Goil, 276 m from the junction

Reverse geocoding works the other way, describing a point by a landmark a rider will recognise:

const here = await afrihex.addresses.reverse(5.6319, -0.14, { descriptors: true })
here.descriptor?.text // "Opposite Nick Petroleum filling station, Gbatsuna"

3. Route a rider

const route = await afrihex.routing.route({
  from: { point: { lat: 5.6457, lng: -0.075 } },
  to: { gps_code: 'GA-183-8164' },
  mode: 'motor_scooter',
})

For a fleet, routing.plan assigns jobs across riders, including several trips per rider.

4. Track the delivery and reconcile the cash

const trip = await afrihex.trips.create({
  destination: { gps_code: 'GA-183-8164' },
  rider_ref: 'kofi',
  amount_to_collect: 120,
  recipient_phone: '0241234567',
})

trip.tracking_url // send this to the customer

await afrihex.trips.ping(trip.id, { lat: 5.64, lng: -0.10 })
await afrihex.trips.recordAttempt(trip.id, { reason: 'customer_unreachable', next_action: 'retry' })
await afrihex.trips.recordCollection(trip.id, { amount: 120, method: 'cash' })
await afrihex.trips.update(trip.id, { status: 'completed' })

const balances = await afrihex.cash.balances() // collected, handed in, still owed per rider

You can also quote prices with delivery.quote and issue proof of delivery at the gate with pod.issue and pod.confirm.

5. Stable location codes, even offline

Every location gets an AfriHex code, built on Uber's open H3 grid:

const hex = await afrihex.hex.encode(5.6221843, -0.1729361, 7)
hex.code       // "AF-GH-7-0GXTJJBDZZZZZ"  (store this)
hex.short_code // "AF-GH-7-0GXTJJBD"       (show this)

Rider on a road with no signal? The companion package @afrihex/offline creates and reads codes on the device with no internet.

Errors are typed

import { AfriHexError } from '@afrihex/sdk'

try {
  await afrihex.trips.get('unknown-id')
} catch (err) {
  if (err instanceof AfriHexError) console.error(err.code, err.status) // TRIP_NOT_FOUND, 404
}

A note on keys

Keep your API key on your server. For mobile apps, mint a per-user token instead of shipping your developer key in the app. The Mobile Integration guide shows the pattern.

Try it

SDK guide: developer.afrihex.com/sdk
Quickstart: developer.afrihex.com/quickstart

Trips, cash, fleet planning and pricing need a paid plan; addresses, routing and hex codes work on the free tier.

If you're building anything with deliveries or addresses in Ghana, I'd love to hear what you're working on. Drop a comment, or tell me which SDK you'd want next.

Dequeue

Dominic — Wed, 15 Dec 2021 01:02:13 +0000

Dequeue

The collections.deque () class is a generalization of stacks and queues and is a deque. The deque () deque supports thread-safe, memory-efficient addition and retrieval of sequence elements from either side with roughly equal O (1) performance in either direction.

sh library

Dominic — Wed, 15 Dec 2021 00:56:56 +0000

Python is a great scripting language. Sometimes using the standard libraries os and subprocess becomes a real headache.

The sh library is a great alternative.

With it, you can call any program as a regular function - this is extremely useful for automating workflow and tasks, and everything is done in Python itself.

Scopes and namespace

Dominic — Mon, 04 Oct 2021 21:28:57 +0000

Namespace is a container that has all the names (of
variables/functions/classes) that you deﬁne. You can deﬁne same
names in diﬀerent namespaces. A name or a variable exists in a
speciﬁc area of the code which deﬁnes its scope. The information
regarding binding between the variables/objects is stored in the
namespace. There are three types of namespaces or scopes.

Built-in These are in-built functions that are available across all
ﬁles or modules.

Global The global namespace has all the variables, functions, and
classes that are available in a single ﬁle.

Local The local namespace are variables deﬁned within a function.

The scopes are nested, which means that the local namespace is
nested within a global namespace which is nested within built-in
namespace. Each scope has its namespace.

DEV Community: Dominic

Handling “Adjacent Goil” addresses: building deliveries in Ghana with TypeScript

1. Get a key, then a test key

2. Parse addresses the way people actually write them

3. Route a rider

4. Track the delivery and reconcile the cash

5. Stable location codes, even offline

Errors are typed

A note on keys

Try it

Dequeue

sh library

Scopes and namespace