Introduction
Terra is a geospatial indexing system that partitions Saudi Arabia into hierarchical hexagonal cells. Terra is open source under the Apache 2 license.
The Terra Core Library implements the Terra grid system. It includes functions for converting latitude and longitude coordinates to the containing Terra cell, finding the centre of Terra cells, finding the boundary geometry of Terra cells, finding neighbours of Terra cells, and traversing the resolution hierarchy.
- The Terra Core Library is written in C. Bindings for Python, JavaScript, PostgreSQL, Go, R, and DuckDB are available.
- Terra is natively aligned with SANSRS (KSA-GRF17), the national spatial reference system mandated by Council of Ministers Decision No. 90.
What Terra provides
A single grid for the whole Kingdom. Terra has 15 resolution levels (Res 0–14). Resolution 8 is the national base standard, with each cell covering exactly 1 hectare. Every cell at a given resolution has the same area anywhere in Saudi Arabia — the equal-area projection is chosen so that counting cells is the same as measuring ground.
Two ways to name a location. Every cell has a 64-bit index with two string forms: the Terra Index String for code, databases, and APIs, and the Terra Grid Code for people — short, speakable, and unambiguous. Converting between them is arithmetic, not a lookup.
A common key for disparate data. Cadastral records, logistics telemetry, environmental readings, utility networks, and administrative datasets rarely share a geometry model, and joining them usually means a spatial predicate over mismatched shapes. Indexed to Terra cells, they join on an integer.
Addressing that works everywhere. A Terra cell exists for every point in the Kingdom — desert, coastline, construction site, and open sea included. Coverage does not depend on a street existing, being named, or being current in any registry.
A hierarchy that aggregates cleanly. Any cell rolls up to its parent with a bit mask. Counts, sums, and densities computed at a fine resolution aggregate to a coarse one without re-reading the source geometry, which makes Terra a practical substrate for analysis and for machine learning over spatial features.
Where to start
- New to Terra — read How Terra Works for the design of the grid itself, then Quick Start.
- Integrating Terra into a system — start with Installation and the API Reference.
- Working to a national standard — see SANSRS Integration for datum handling, the geoid model, and migration from legacy reference frames.
Developed by Tec Solution KSA.