Tiye Compass · API v1 · 5 m cells · 8-character Crockford-32

Turn a GPS point into a digital address.

Compass is Tiye’s digital address engine. It maps a coordinate to a deterministic 5 m × 5 m cell inside a country namespace. The human code is eight characters, printed as two groups of four, for example 076F R09N. Country is sent with the request and is not part of the printed address.

Get my address

Allow location, then Compass resolves your GPS into an 8-character cell code. GPS accuracy is metadata; the cell size is always 5 m. If the first reading fails, Compass retries without high accuracy. Country is chosen from the GPS point when possible.

Country

———— ————

Location not requested yet.

Blantyre sample

Frozen V1 vector for Malawi. Use this if you are not in a supported African bounding box.

MWI · -15.8874886, 35.0645192

076F R09N

Press resolve to call POST /api/v1/address/resolve

Resolve coordinates

POST /api/v1/address/resolve

Country Latitude Longitude

Lookup address

POST /api/v1/address/lookup — returns the 5 m cell centre.

Country Address

Validate address

POST /api/v1/address/validate — rejects I, L, O, U and bad checksums.

Country Address

Round trip

Resolve a coordinate, then look the code back up. The looked-up point is the cell centre and must encode to the same code.

API documentation

Mathematical engine from Tiye. No map provider. Country + 8-character code uniquely identifies a 5 m cell. Algorithm version 1 is frozen.

Base URL

https://compass-api.tiye.services/api/v1

Endpoints

Method	Path	Purpose
GET	`/api/v1/countries`	Supported ISO country namespaces
POST	`/api/v1/address/resolve`	Coordinate → address
POST	`/api/v1/address/lookup`	Address → cell centre
POST	`/api/v1/address/validate`	Check alphabet, checksum, and range

Resolve

POST /api/v1/address/resolve
Content-Type: application/json

{
  "country": "MWI",
  "latitude": -15.8874886,
  "longitude": 35.0645192,
  "accuracy_meters": 8.4
}

{
  "address": "076FR09N",
  "country": "MWI",
  "latitude": -15.8874886,
  "longitude": 35.0645192,
  "cell_center": { "latitude": "...", "longitude": "..." },
  "bounds": { "north": "...", "south": "...", "east": "...", "west": "..." },
  "resolution_meters": 5,
  "algorithm_version": 1,
  "accuracy_meters": 8.4
}

Lookup

POST /api/v1/address/lookup

{ "country": "MWI", "address": "076FR09N" }

Returned latitude / longitude are the cell centre, not the original GPS pin.

Validate

POST /api/v1/address/validate

{ "country": "MWI", "address": "076FR09N" }

{ "valid": true, "country": "MWI", "address": "076FR09N", "algorithm_version": 1, "reason": null }

Rules

Human code	Exactly 8 Crockford-32 characters `0123456789ABCDEFGHJKMNPQRSTVWXYZ`, printed as `076F R09N`. No `I L O U`. Lowercase and a middle space are accepted. The API value is the compact 8 characters.
Country	ISO 3166-1 alpha-3, sent separately. `MWI` + `076F R09N` is not the same place as `ZMB` + `076F R09N`.
Resolution	5 m × 5 m cell. Not GPS accuracy.
Checksum	2 bits inside the 8 characters. A typo is often `valid: false`.
Namespace	V1 uses the frozen country bounding rectangle. A point outside it returns 422.
Errors	404 unknown country. 422 invalid coordinate, invalid code, or out of range.