Core Concepts
A handful of terms come up everywhere in the H3 API. This page explains them in plain language so the rest of the docs read smoothly. You don't have to memorize it — come back when a word needs unpacking.
Cells and indexes
A cell is one hexagon in the grid. Every cell has a unique index — a single 64-bit integer
that identifies it exactly. When you call latLngToCell,
the integer you get back is that index.
The same index has a canonical hexadecimal string form (for example 8928308280fffff). The
integer and the string are two views of the same value:
Resolutions
H3 isn't one grid — it's 16 nested grids, numbered 0 (coarsest) to 15 (finest). The
resolution you pass to latLngToCell decides how big the cell is.
- Low resolutions (0–4) cover continents, countries, and large regions.
- Mid resolutions (7–10) cover neighborhoods, city blocks, and buildings — the sweet spot for most apps.
- High resolutions (12–15) cover rooms and sub-meter precision.
Each step finer divides a cell into roughly 7 children, so cell counts grow fast. Picking the right resolution is the most important design decision you'll make — coarser means fewer cells and less storage; finer means more precision and more cells.
Resolution reference table
Average hexagon area and edge length at each resolution (cells vary slightly by location — about ±15% from the equator to the poles):
| Resolution | Avg Hex Area | Avg Edge Length |
|---|---|---|
| 0 | 4,357,449.416 km² | 1,281.256 km |
| 1 | 609,788.441 km² | 483.057 km |
| 2 | 86,801.780 km² | 182.512 km |
| 3 | 12,393.434 km² | 68.979 km |
| 4 | 1,770.347 km² | 26.071 km |
| 5 | 252.903 km² | 9.854 km |
| 6 | 36.129 km² | 3.724 km |
| 7 | 5.161 km² | 1.406 km |
| 8 | 0.737 km² | 531.414 m |
| 9 | 0.105 km² | 200.786 m |
| 10 | 0.015 km² | 75.863 m |
| 11 | 0.002 km² | 28.663 m |
| 12 | 307.092 m² | 10.830 m |
| 13 | 43.870 m² | 4.092 m |
| 14 | 6.267 m² | 1.546 m |
| 15 | 0.895 m² | 0.584 m |
Choosing a resolution
Pick the resolution where one cell is about the size of the thing you're modeling. Tracking vehicles
to a city block? Resolution 9–10. Drawing service areas across a city? Resolution 6–7. Aggregating
demand for a national heatmap? Resolution 4–5. You can always roll a fine cell up to a coarser parent
with cellToParent later.
Base cells
At resolution 0 the world is tiled by exactly 122 base cells. Every finer cell descends from one
of them, and a cell's getBaseCellNumber (0–121) tells
you which one. Base cells are useful for coarse partitioning — for example, sharding a global dataset
across 122 buckets.
You can list every resolution-0 cell with
getRes0Cells.
Pentagons
Hexagons cannot perfectly tile a sphere — geometry forces a small number of pentagons. H3 has exactly 12 pentagon cells at every resolution, positioned over the oceans to minimize their practical impact.
Pentagons have 5 neighbors instead of 6, which makes them a genuine edge case:
- A
gridDisktouching a pentagon returns fewer cells than the usual formula predicts. - Some operations near a pentagon can raise a pentagon-distortion error.
Test for one with isPentagon, and list them with
getPentagons.
Never hard-code disk sizes
Because of pentagons, do not assume gridDisk($cell, $k) returns exactly 3 * k * (k + 1) + 1
cells. Always iterate the returned array rather than relying on a fixed count.
String vs integer representation
Both forms identify the same cell. Use the one that fits the context:
| Form | Looks like | Best for |
|---|---|---|
| Integer | 617700169958293503 | Database columns, grouping, joins, in-memory work |
| Hex string | 8928308280fffff | JSON / APIs, logs, anything that might lose 64-bit precision |
Convert freely with h3ToString and
stringToH3.
Why the string matters across boundaries
A 64-bit integer is too large for some systems to represent exactly — JavaScript numbers, for instance, lose precision above 2⁵³. When a cell index leaves PHP for a browser or an external API, send the string form to keep it intact.
Res Class III
Resolutions alternate between two orientations of the hexagonal grid. The odd resolutions (1, 3, 5, …) are called Class III; even resolutions are Class II. The two classes are rotated relative to each other, which is why cell boundaries look slightly different between adjacent resolutions.
You rarely need to think about this, but two cases matter:
- A Class III cell's boundary may have extra vertices where it meets Class II neighbors.
- Some algorithms (and the local IJ coordinate system) behave differently across the two classes.
Check a cell with isResClassIII.
Next steps
With the vocabulary in hand, dig into the API:
- Indexing & Inspection — coordinates to cells and back, plus inspecting any cell.
- Traversal & Hierarchy — neighbors, rings, paths, parents, and children.
- Measurements & Utilities — areas, distances, and grid metadata.