Terra index structure

Every location in Saudi Arabia can be expressed as a Terra cell — a 64-bit unsigned integer encoding the cell's resolution, base cell, and hierarchical position. Terra provides two human-readable string representations of this integer, each optimised for a different audience.

The 64-bit cell index

Internally, every Terra cell is a uint64_t. All arithmetic in terra-core operates on this integer directly — no string parsing, no geometry lookup.

Bits	Field	Description
63–60	Mode	0001 = Terra hexagon cell
59–56	Reserved	0000 in Terra v1
55–52	Resolution	0–14; value 15 reserved
51–45	Base cell	0–127; ~80 base cells cover KSA + GCC buffer
44–3	Child digits	14 × 3 bits (values 0–6); digits below current resolution padded with 7
2–0	Reserved	Zero in Terra v1

Extract the resolution with a single bitwise operation:

int terra_get_resolution(TerraIndex cell) {
    return (int)((cell >> 52) & 0xF);
}

Child digits

Each digit (0–6) identifies which of the 7 children was selected at each level. Digit 0 is the centre child; digits 1–6 are the surrounding children. Digits beyond the current resolution are padded with 7, so parent cells can be derived from children using a mask operation without any coordinate lookup.

Terra Index String — TIS

The TIS is the developer-facing string form: a lowercase t prefix followed by the 64-bit integer encoded as 16 hex characters.

t10830cd1943ffff8

• Always 17 characters, at every resolution.
• Resolution is implicit in the bit field — readable with terra_get_resolution().
• Used by all terra-core bindings, PostGIS storage, API responses, and DuckDB.

Terra Grid Code — TGC

The TGC is the human-facing string form: short, speakable, and geometrically derived with no reference to any administrative boundary.

T08-0C6D351E

Format: T[RES]-[POSITION]

Component	Meaning
T	Terra prefix
08	Resolution — two digits, zero-padded. 08 = Res 8 = 1 ha.
-	Separator
0C6D351	Position code in Base32. Length scales with resolution.
E	Check character (Luhn mod 32). Validated, then discarded.

Position code alphabet — 32 unambiguous characters (excludes I, L, O, U):

0123456789ABCDEFGHJKMNPQRSTVWXYZ

Code length by resolution:

Res	Body chars	Full TGC	Example
0–1	2	7	T00-0RF
2	3	8	T02-1GSV
3–4	4	9	T04-31K8R
5–6	5	10	T06-636HJF
7	6	11	T07-1GSMCM7
8 ★	7	12	T08-0C6D351E
9	7	12	T09-31K8S8BS
10–11	8	13	T11-636HJGPD8
12	9	14	T12-1GSMCM5K8E
13–14	10	15	T14-31K8S8B6HJ2

Lengths include the check character. Full specification in The Terra Grid Code.

At every resolution, 32ⁿ exceeds the total cell count for Saudi Arabia plus the full GCC buffer zone. No two cells share a TGC.

TIS vs TGC

	TIS	TGC
Example	t10830cd1943ffff8	T08-0C6D351E
Length	Always 17 chars	7–15 chars
Resolution visible?	No (bit field)	Yes (T08)
Human-readable?	No	Yes
Error detection?	No	Check character
Admin boundary?	No	No
Primary use	Code, databases, APIs	Maps, dispatch, field, citizens

Converting between TIS and TGC is pure arithmetic — no geographic lookup, no network call.

Base cells

Terra defines approximately 80 base cells (Res 0 hexagons) covering Saudi Arabia and the GCC buffer zone. Each is identified by an integer 0–127 in bits 51–45. Every Terra cell traces back to exactly one base cell plus up to 14 child digits. The base cell layout is fixed for all Terra v1 indices.

---

The Terra System is designed and developed by Tec Solution KSA.