The Terra Grid Code
Every Terra cell has one identity and two written forms. The Terra Index String (TIS) is for machines. The Terra Grid Code (TGC) is for people — short enough to print on a form, read over a radio, and type back into a search field without error.
This page specifies the TGC completely. If you are storing locations in a database or passing them between services, you want the TIS instead.
When to use which
| TIS | TGC | |
|---|---|---|
| Audience | code, databases, APIs | people |
| Example (Res 8) | t10830cd1943ffff8 | T08-0C6D351E |
| Length | 17 characters, always | 7–15 characters, by resolution |
| Error detection | none | check digit |
| Sortable | yes | no |
The rule is simple: if a human will ever see it, use a TGC. Otherwise use a TIS. Converting between them is arithmetic on the same underlying 64-bit index, so nothing is lost either way.
Anatomy
T08-0C6D351E
│└┬┘ └───┬──┘└┬┘
│ │ │ └── check character
│ │ └─────── position, encoding base cell and child digits
│ └────────────── resolution, always two digits
└──────────────── format marker
The resolution prefix is load-bearing, not decorative. The position body alone is not sufficient to identify a cell — the same body can occur at more than one resolution. Never store, transmit, or display a TGC with the prefix stripped.
Alphabet
The position and check characters use 32 symbols:
0 1 2 3 4 5 6 7 8 9 A B C D E F G H J K M N P Q R S T V W X Y Z
I, L, O, and U are excluded. The first three are excluded because they are readily
confused with 1, 1, and 0 when handwritten, printed at small sizes, or read aloud. U is
excluded to avoid accidental formation of offensive strings.
Codes are uppercase. Lowercase input should be accepted and normalised by any implementation, since
l and 1 confusion is a common source of transcription error.
Check character
The final character is a Luhn mod 32 check computed over the position body. It is not part of the position — it carries no locational meaning and is discarded after validation.
Measured over the Res 8 code space:
| Error class | Detection rate |
|---|---|
| Single-character substitution | 100% |
| Adjacent transposition | 99.7% |
Both figures were measured by exhaustive substitution and transposition over sampled codes, not estimated. Any implementation must validate the check character before using a code, and must reject rather than attempt correction — a code that fails validation should be re-entered, not guessed at.
T08-0C6D351E valid
T08-0C7D351E rejected — one character changed
T08-C06D351E rejected — two characters swapped
Length by resolution
| Resolution | Payload bits | Body | Total | Example |
|---|---|---|---|---|
| 0 | 7 | 2 | 7 | T00-0RF |
| 2 | 13 | 3 | 8 | T02-1GSV |
| 4 | 19 | 4 | 9 | T04-31K8R |
| 6 | 25 | 5 | 10 | T06-636HJF |
| 8 | 31 | 7 | 12 | T08-0C6D351E |
| 10 | 37 | 8 | 13 | T10-0RCT6A2SZ |
| 12 | 43 | 9 | 14 | T12-1GSMCM5K8E |
| 14 | 49 | 10 | 15 | T14-31K8S8B6HJ2 |
The payload is 7 bits of base cell plus 3 bits per child digit, encoded most-significant-first with leading zeros retained. The check character adds one.
Res 8, the national base standard, is 12 characters — comparable to other public location codes and short enough to print, dictate, and re-enter reliably.
Worked example
One cell, followed up the hierarchy. Base cell 24, child digits 3-1-5-0-6-2-4-1:
| Resolution | Nominal area | TIS | TGC |
|---|---|---|---|
| 4 | 24.01 km² | t10430cd1fffffff8 | T04-31K8R |
| 5 | 3.43 km² | t10530cd1bffffff8 | T05-0RCT6A |
| 6 | 49 ha | t10630cd197fffff8 | T06-636HJF |
| 7 | 7 ha | t10730cd194fffff8 | T07-1GSMCM7 |
| 8 | 1 ha | t10830cd1943ffff8 | T08-0C6D351E |
The seven children of that Res 8 cell:
T09-31K8S8BS T09-0RCT6A5H T09-636HJGN7 T09-1GSMCM7T
T09-0C6D351K T09-31K8S8CG T09-0RCT6A6D
Note that a code gives no visual hint of the codes near it. Two adjacent cells on the ground have unrelated-looking codes. This is expected — proximity is not a property the human-readable form is designed to carry. Use the traversal API for anything involving neighbours or distance.
What a Terra Grid Code does not contain
No region, city, district, or governorate reference. This is deliberate and it is not an omission to be corrected.
Hexagonal cells are laid out on a continuous grid and take no account of administrative boundaries. A single cell can straddle two governorates, sit across a municipal limit, or fall outside any populated area entirely. Embedding an administrative reference in the code would make that reference wrong for every straddling cell, and would break every code in the affected area whenever a boundary is redrawn.
A Terra Grid Code identifies a position on the ground and nothing else. Administrative attribution is a property of a dataset joined to the cell, not a property of the cell.
No street, building, or postal reference. A cell exists for every point in the Kingdom, including desert, coastline, construction sites, and open sea. Coverage does not depend on a street existing, being named, or being current in any registry.
Using codes in the field
Reading aloud. Read the resolution as two digits, then the body character by character. The excluded letters mean there is no ambiguous pair to disambiguate, so a phonetic alphabet is unnecessary for most exchanges.
Printing. Keep the hyphen. It separates the resolution from the position and prevents the code from being read as one undifferentiated string.
Forms and input fields. Accept lowercase and normalise. Accept a missing hyphen and reinsert it. Reject anything failing the check character rather than attempting correction, and say which part failed so the person knows what to re-read.
Choose the resolution deliberately. A code carries exactly the precision of its resolution, and publishing a Res 12 code implies you can defend sub-metre accuracy. For most operational purposes — an address, a parcel, a connection point, a service call — Res 8 is the right level and the one to standardise on.
API
cellToSaudiCode converts a Terra cell to its TGC; saudiCodeToCell converts back, validating the
check character. See Indexing.
Any independent implementation must reproduce this specification exactly — the alphabet, the most-significant-first packing with leading zeros retained, and the Luhn mod 32 check. A code that round-trips through one implementation and fails in another is a defect in one of them.
Next
- Terra index structure — the 64-bit layout and the TIS
- How Terra works — the grid the codes address
- Tables of cell stats — area and precision by resolution
The Terra System is designed and developed by Tec Solution KSA.