Indexing functions

These functions convert between geographic coordinates and Terra cell identifiers, and retrieve the geometry of a given cell.

latLngToCell

Indexes the location at the specified resolution, returning the Terra Index String of the cell containing that point. For more information see the algorithm description.

C

TerraError latLngToCell(double lat, double lng, int res, TerraIndex *out);

Returns 0 (E_SUCCESS) on success.

Python

terra.latlon_to_cell(lat, lng, res, datum='KSA-GRF17')
# Returns: str (Terra Index String)

# Riyadh — Masmak Fortress
cell = terra.latlon_to_cell(24.6877, 46.7219, 8)
# "t10830cd1943ffff8"

# Jeddah — Al-Balad historic district
cell = terra.latlon_to_cell(21.4858, 39.1862, 8)

# NEOM — Tabuk region
cell = terra.latlon_to_cell(27.9654, 35.2034, 8)

The datum parameter accepts 'KSA-GRF17' (default, EPSG:9333) or 'WGS84' (auto-converted).

JavaScript

terra.latLngToCell(lat, lng, res)
// Returns: string (Terra Index String)

const cell = terra.latLngToCell(24.6877, 46.7219, 8);
// "t10830cd1943ffff8"

SQL

terra_latlon_to_cell(lat, lng, resolution)
-- Returns: text

SELECT terra_latlon_to_cell(24.6877, 46.7219, 8);
-- "t10830cd1943ffff8"

-- With KSA-GRF17 geometry column (EPSG:9333)
SELECT terra_latlon_to_cell(
    ST_Y(geom), ST_X(geom), 8
) AS terra_cell
FROM survey_points
WHERE ST_SRID(geom) = 9333;

Go

cell, err := terra.LatLngToCell(24.6877, 46.7219, 8)
// cell: "t10830cd1943ffff8"

DuckDB

terra_latlon_to_cell(lat, lng, resolution)

SELECT terra_latlon_to_cell(24.6877, 46.7219, 8);
-- "t10830cd1943ffff8"

Shell

$ terra latLngToCell --lat 24.6877 --lng 46.7219 -r 8
"t10830cd1943ffff8"

cellToCenter

Finds the geographic centre of a Terra cell in the LAEA projection, reprojected to WGS84 (or KSA-GRF17).

The centre returned is the centroid of the hexagonal cell. It will differ slightly from the original coordinates used to index the cell, because the cell covers a region rather than a point.

C

TerraError cellToCenter(TerraIndex cell, LatLng *center);

Returns 0 (E_SUCCESS) on success.

Python

terra.cell_to_center(cell)
# Returns: (lat, lng) tuple

center = terra.cell_to_center("t10830cd1943ffff8")
# (24.6880, 46.7221)

JavaScript

terra.cellToCenter(cell)
// Returns: [lat, lng]

const center = terra.cellToCenter("t10830cd1943ffff8");
// [24.6880, 46.7221]

SQL

terra_cell_to_lat(cell)   -- Returns: float8
terra_cell_to_lng(cell)   -- Returns: float8

SELECT
    terra_cell_to_lat('t10830cd1943ffff8') AS lat,
    terra_cell_to_lng('t10830cd1943ffff8') AS lng;

Go

center, err := terra.CellToCenter("t10830cd1943ffff8")
// center.Lat, center.Lng

DuckDB

terra_cell_to_lat(cell)
terra_cell_to_lng(cell)

Shell

$ terra cellToCenter -c t10830cd1943ffff8
[24.6880, 46.7221]

cellToBoundary

Returns the six vertices of the hexagonal cell boundary as (lat, lng) pairs.

C

TerraError cellToBoundary(TerraIndex cell, CellBoundary *boundary);

Returns 0 (E_SUCCESS) on success. CellBoundary contains exactly 6 LatLng vertices.

Python

terra.cell_to_boundary(cell)
# Returns: list of (lat, lng) tuples — 6 vertices

boundary = terra.cell_to_boundary("t10830cd1943ffff8")
# [(24.6935, 46.7177), (24.6963, 46.7253), (24.6908, 46.7328),
#  (24.6825, 46.7326), (24.6797, 46.7250), (24.6852, 46.7176)]

For GeoJSON compatibility (lng/lat order), pass geo_json=True.

JavaScript

terra.cellToBoundary(cell)
// Returns: [[lat, lng], ...] — 6 vertices

const boundary = terra.cellToBoundary("t10830cd1943ffff8");

SQL

-- Returns PostGIS geometry (POLYGON, EPSG:4326)
terra_cell_to_boundary_wkb(cell)

SELECT ST_AsGeoJSON(
    terra_cell_to_boundary_wkb('t10830cd1943ffff8')
);

Go

boundary, err := terra.CellToBoundary("t10830cd1943ffff8")
// boundary: []terra.LatLng — 6 vertices

DuckDB

terra_cell_to_boundary_wkb(cell)

Shell

$ terra cellToBoundary -c t10830cd1943ffff8
[[24.6935,46.7177],[24.6963,46.7253],[24.6908,46.7328],[24.6825,46.7326],[24.6797,46.7250],[24.6852,46.7176]]

cellToSaudiCode

Converts a Terra cell to its human-readable Terra Grid Code (TGC) — the T[RES]-[POSITION] string intended for citizens, maps, and dispatch systems. See the Saudi Grid Code guide for full documentation.

Terra-specific

The Saudi Grid Code is the citizen-facing half of the Terra addressing model. Use it wherever a code will be spoken, written on a form, or read off a screen; use the TIS everywhere else.

Python

terra.cell_to_saudi_code(cell)
# Returns: str (Terra Grid Code)

code = terra.cell_to_saudi_code("t10830cd1943ffff8")
# "T08-0C6D351E"

# Reverse: TGC -> TIS
cell = terra.string_to_cell("T08-0C6D351E")
# "t10830cd1943ffff8"

JavaScript

terra.cellToSaudiCode(cell)  // TIS -> TGC
terra.stringToCell(tgc)      // TGC -> TIS

const code = terra.cellToSaudiCode("t10830cd1943ffff8");
// "T08-0C6D351E"

const cell = terra.stringToCell("T08-0C6D351E");
// "t10830cd1943ffff8"

SQL

terra_cell_to_saudi_code(cell)   -- TIS -> TGC
terra_saudi_code_to_cell(code)   -- TGC -> TIS

SELECT terra_cell_to_saudi_code('t10830cd1943ffff8');
-- "T08-0C6D351E"

---

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