Skip to main content

Indexing

Functions for converting between geospatial coordinates and A5 indices.

Coordinates are specified as per the GeoJSON spec, namely: [longitude, latitude].

info

For detailed information about how A5 encodes cells as 64-bit integers, see Index Encoding.

lonLatToCell​

Indexes the coordinate at a given resolution to an A5 cell index.

a5_lonlat_to_cell(longitude DOUBLE, latitude DOUBLE, resolution INTEGER) -> UBIGINT

Parameters​

  • coordinate (number[]) coordinate as [longitude, latitude]
  • resolution (number) The resolution level to index at

Return value​

  • (bigint) The A5 cell identifier

cellToLonLat​

Returns the geospatial coordinate at the center of an A5 cell.

a5_cell_to_lonlat(cell UBIGINT) -> DOUBLE[2]


-- As a GEOMETRY point
a5_cell_to_point(cell UBIGINT) -> GEOMETRY

Parameters​

  • cell (bigint) A5 cell identifier

Return value​

  • (number[]) The center coordinate as [longitude, latitude]

cellToBoundary​

Returns the vertices that define the boundary of an A5 cell.

a5_cell_to_boundary(cell UBIGINT) -> DOUBLE[2][]
a5_cell_to_boundary(cell UBIGINT, closed_ring BOOLEAN) -> DOUBLE[2][]
a5_cell_to_boundary(cell UBIGINT, closed_ring BOOLEAN, segments INTEGER) -> DOUBLE[2][]


-- As a GEOMETRY polygon
a5_cell_to_geometry(cell UBIGINT) -> GEOMETRY
a5_cell_to_geometry(cell UBIGINT, segments INTEGER) -> GEOMETRY

Parameters​

  • cell (bigint) A5 cell identifier
  • options (object) Optional configuration object
    • closedRing (boolean) Whether to close the ring by repeating the first point at the end. Defaults to true.
    • segments (number | 'auto') Number of segments to use for each edge. When set to 'auto', uses a resolution-appropriate value. Defaults to 'auto'.

Return value​

  • (number[][]) Array of coordinates defining the cell boundary, each as [longitude, latitude]

polygonToCells​

Returns all cells within a polygon, defined either by a single ring of [longitude, latitude] vertices or by GeoJSON-style rings [outer, ...holes]. Cells inside a hole are excluded.

Rings may be open or closed (GeoJSON-style, with the first vertex repeated at the end) — closure is automatic either way. Either winding order is accepted; the orientation is detected from the ring geometry. Hole rings with fewer than 3 distinct vertices are ignored.

The containment option controls which cells count as belonging to the polygon:

  • 'center' (default) — a cell is included only if its center lies inside the polygon. Adjacent polygons that share an edge produce disjoint coverings, so this is the right choice for partitioning.
  • 'overlapping' — additionally includes every cell that overlaps the polygon boundary. The result is a superset of 'center' that fully covers the polygon with no gaps, at the cost of some overlap with adjacent polygons. Use this when a query must not miss any cell touching the polygon (for example, filtering database rows by cell before applying an exact geometry test).

The result is a covering of the polygon, approximating it with 'center' and containing it with 'overlapping': compacted cells, then a compaction marker recording the resolution. Use uncompact to expand it to the input resolution. The compacted form is intended for storage, transfer and set operations: cell boundaries of different resolutions do not nest geometrically, so the mixed-resolution cells of a covering will show overlaps and gaps when rendered. Uncompact to a single resolution before drawing cells on a map.

Multi-polygons are not supported directly — call polygonToCells per polygon and combine the results with union. Coverings can also be intersected, subtracted and tested for containment without uncompacting, see Coverings.

a5_geometry_to_cells(geom GEOMETRY, resolution INTEGER) -> UBIGINT[]
a5_geometry_to_cells(geom GEOMETRY, resolution INTEGER, overlapping BOOLEAN) -> UBIGINT[]

Parameters​

  • polygon (LonLat[] | LonLat[][]) Either a single ring of [longitude, latitude] vertices, or an array of rings where the first ring is the outer boundary and subsequent rings are holes. The outer ring must contain at least 3 vertices.
  • resolution (number) Target resolution (0–30)
  • options (object) Optional configuration object
    • containment ('center' | 'overlapping') Which cells to include relative to the polygon. 'center' includes a cell only if its center is inside; 'overlapping' also includes cells that touch the polygon, for gap-free coverage. Defaults to 'center'.

Return value​

Example​

-- Bounding box around central Paris
SELECT a5_geometry_to_cells(
  'POLYGON((2.25 48.81, 2.42 48.81, 2.42 48.90, 2.25 48.90, 2.25 48.81))'::GEOMETRY, 10
) AS compact;


-- All cells at resolution 10
SELECT unnest(a5_uncompact(a5_geometry_to_cells(
  'POLYGON((2.25 48.81, 2.42 48.81, 2.42 48.90, 2.25 48.90, 2.25 48.81))'::GEOMETRY, 10
))) AS cell;


-- The same polygon with a hole — cells inside the hole are excluded
SELECT a5_geometry_to_cells(
  'POLYGON((2.25 48.81, 2.42 48.81, 2.42 48.90, 2.25 48.90, 2.25 48.81),
           (2.30 48.84, 2.37 48.84, 2.37 48.87, 2.30 48.87, 2.30 48.84))'::GEOMETRY, 10
) AS with_hole;


-- Full coverage — every cell overlapping the polygon, with no gaps along the edge
SELECT a5_geometry_to_cells(
  'POLYGON((2.25 48.81, 2.42 48.81, 2.42 48.90, 2.25 48.90, 2.25 48.81))'::GEOMETRY, 10, true
) AS covering;

lineStringToCells​

Returns all cells whose pentagons intersect a polyline defined by a sequence of waypoints. Consecutive waypoints are connected with great-circle arcs. For a simple two-point line segment, pass [start, end].

The result is uncompacted at the requested resolution and is not sorted — cells appear roughly in the order they were discovered along the path. Cells at waypoint junctions are deduplicated.

a5_geometry_to_cells(geom GEOMETRY, resolution INTEGER) -> UBIGINT[]  -- geom a LINESTRING

Parameters​

  • waypoints (LonLat[]) Polyline vertices, each as [longitude, latitude]
  • resolution (number) Target resolution (0–30)

Return value​

  • (bigint[]) Array of unique cell identifiers whose pentagons intersect the polyline

Example​

-- Simple segment: Paris → London
SELECT a5_geometry_to_cells('LINESTRING(2.3522 48.8566, -0.1276 51.5074)'::GEOMETRY, 8) AS segment;


-- Multi-waypoint route: Paris → Lyon → Nice
SELECT a5_geometry_to_cells(
  'LINESTRING(2.3522 48.8566, 4.8357 45.7640, 7.2620 43.7102)'::GEOMETRY, 8
) AS cells;

Cell representation​

A5 cells are stored as 64 bit integers, for performance and to provide a compact representation for use in databases. In JavaScript these can be represented as BigInt values and arrays of cells stored as BigUint64Arrays.

For best performance it is recommended to use this representation, but it is also possible to convert them into hexadecimal, for example to encode them in JSON (which does not support 64 bit integers). Two helper functions are provided for this conversion.

u64ToHex​

a5_u64_to_hex(cell UBIGINT) -> VARCHAR

Parameters​

  • index (bigint) A5 cell identifier

Return value​

  • (string) Hexadecimal string representation of the cell identifier

hexToU64​

a5_hex_to_u64(hex VARCHAR) -> UBIGINT

Parameters​

  • hex (string) Hexadecimal string representation of an A5 cell identifier

Return value​

  • (bigint) The A5 cell identifier