# Geospatial

Geospatial values say where things are, and what is near or inside what:
a bakery's position, the patches it delivers to, the shops within five
kilometres of a customer, the pins inside the map a person is looking at.

The types are standard types, listed under
[Geospatial types](/docs/geospatial-types.md): `Point`,
with a named `latitude` and `longitude`, five other geometries such as
`Polygon`, and `Geometry`, which holds any one of the six. All of them
are in WGS84, the coordinate system GPS uses, and are sent as GeoJSON.
This page covers what you do with them:

| Part | What | Builds on |
|---|---|---|
| [Geometry operations](/docs/geometry-operations.md) | 10 in `geo`: distance, length, bearing, area, intersects, contains, within (with or without `distance:`), centroid, bounding box; and the two for WKT text | The standard library's [operations](/docs/what-every-operation-follows.md) and its whole-number maths |
| [Storing geometries](/docs/geospatial-storage.md) | One PostGIS `geography` column per geometry, checked to its type and WGS84; GiST indexes derived from your queries | [Storage types](/docs/storage-types.md) |
| [Finding records by place](/docs/geospatial-queries.md) | `geo.within`, `geo.contains`, `geo.intersects` as `where:` conditions; `order:` by `geo.distance` inside a radius | [Reads and writes](/docs/reads-and-writes.md) |
| [GeoJSON and other formats](/docs/geospatial-interop.md) | GeoJSON `Feature` and `FeatureCollection`; WKT where other systems use it | The standard library's GeoJSON |

PostGIS is the PostgreSQL extension for geographic data. Where this page
says a PostGIS behaviour was verified, it was checked against PostGIS
3.4.2 on PostgreSQL 16. Some compiler messages cite a decision by number,
as in `question 10`; the Decisions table in the
[design notes](https://github.com/jadpo-dev/jadpo/blob/main/docs/language/notes/20-geospatial.md#decisions) lists them.

| Page | What it covers |
|---|---|
| [What every geospatial operation follows](/docs/what-every-geospatial-operation-follows.md) | Every `geo.` operation works the same way in the respects below, so you can rely on them without checking each operation. |
| [Geometry operations](/docs/geometry-operations.md) | The `geo.` operations measure distances, lengths, directions and areas, and say whether one shape touches or holds another. |
| [Predicates and shapes](/docs/predicates-and-shapes.md) | Whether one shape contains, is within or intersects another, and a shape's centre and bounding box. |
| [Storing geometries](/docs/geospatial-storage.md) | A geometry field of an entity is stored in one PostgreSQL column of PostGIS's `geography` type. |
| [Finding records by place](/docs/geospatial-queries.md) | You find records by where they are with a `geo.` call as a query's `where:` condition. |
| [GeoJSON and other formats](/docs/geospatial-interop.md) | Other systems send and expect geometries in their own formats: map libraries take GeoJSON layers, spreadsheets and other systems' APIs hold WKT text, and trackers send pairs of numbers. |
| [What geospatial leaves out, and what to use instead](/docs/geospatial-left-out.md) | Some geospatial work is left out of the language. |

[What is built](/docs/geospatial-built.md) says which of this works today.

## Details

The exact rules, for when you hit an edge case.

| Page | What it covers |
|---|---|
| [Precision and determinism](/docs/precision-and-determinism.md) | A `geo.` operation gives the same digits on the interpreter, a native build and a wasm32 build, and a query gives the same records the code would keep. |