Skip to main content

Traversal

Functions for finding neighboring cells, collecting cells within a range, and tracing cells along a path. See the Traversal example.

Each A5 cell has exactly 5 edge neighbors, which can be obtained using the gridDisk function. If the vertex neighbors are required, gridDiskVertex can be used. For broader range queries sphericalCap provides all the cells within a great-circle radius. To trace cells along a great-circle path, use lineStringToCells.

In order to save memory, the returned cells from gridDisk, gridDiskVertex and sphericalCap are compacted.

gridDisk​

Returns all cells within k edge-sharing hops of a center cell.

At each step, only edge-sharing neighbors (5 per cell) are followed.

The result is compacted — use uncompact to expand to the target resolution.

function gridDisk(cellId: bigint, k: number): BigUint64Array;

Parameters​

  • cellId (bigint) Center A5 cell identifier
  • k (number) Number of hops (0 returns just the center cell)

Return value​

  • (BigUint64Array) Sorted, compacted array of cell identifiers in the disk

Example​

import { lonLatToCell, gridDisk, uncompact, getResolution } from 'a5-js';

const cell = lonLatToCell([2.3522, 48.8566], 10);
const ring1 = gridDisk(cell, 1), getResolution(cell); // center + 5 edge neighbors (compacted)
const ring2 = uncompact(gridDisk(cell, 2), getResolution(cell)); // center + ring 1 + ring 2 (uncompacted)

gridDiskVertex​

Returns all cells within k hops of a center cell, following both edge-sharing and vertex-sharing neighbors.

The result is compacted — use uncompact to expand to the target resolution.

function gridDiskVertex(cellId: bigint, k: number): BigUint64Array;

Parameters​

  • cellId (bigint) Center A5 cell identifier
  • k (number) Number of hops (0 returns just the center cell)

Return value​

  • (BigUint64Array) Sorted, compacted array of cell identifiers in the disk

sphericalCap​

Computes all cells whose centers fall within a great-circle radius from the center of a given cell.

The result is compacted — use uncompact to expand to the target resolution.

function sphericalCap(cellId: bigint, radius: number): BigUint64Array;

Parameters​

  • cellId (bigint) Center A5 cell identifier
  • radius (number) Radius in meters

Return value​

  • (BigUint64Array) Sorted array of cell identifiers at mixed resolutions (compacted)

Example​

import { lonLatToCell, sphericalCap, uncompact, getResolution } from 'a5-js';

const cell = lonLatToCell([2.3522, 48.8566], 10);
const compact = sphericalCap(cell, 500_000); // 500 km
const flat = uncompact(compact, getResolution(cell));

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.

function lineStringToCells(waypoints: LonLat[], resolution: number): bigint[];

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​

import { lineStringToCells } from 'a5-js';

// Simple segment: Paris → London
const segment = lineStringToCells([[2.3522, 48.8566], [-0.1276, 51.5074]], 8);

// Multi-waypoint route
const route = [
  [2.3522, 48.8566], // Paris
  [4.8357, 45.7640], // Lyon
  [7.2620, 43.7102]  // Nice
];
const cells = lineStringToCells(route, 8);