Measurements & Utilities

These functions answer the quantitative questions: how big is a cell, how long is an edge, how far apart are two points, and how many cells exist at a resolution. They come in unit variants — km, m, and radians — so you can stay in whatever unit your domain uses.

use Foysal50x\H3\H3;
 
$h3 = new H3();
$cell = $h3->latLngToCell(37.7749, -122.4194, 9);

Area functions

Average hexagon area

The average area of any cell at a resolution — a fast lookup that doesn't need a specific cell.

public function getHexagonAreaAvgKm2(int $res): float
public function getHexagonAreaAvgM2(int $res): float

echo $h3->getHexagonAreaAvgKm2(9);   // ~0.105 km²
echo $h3->getHexagonAreaAvgM2(9);    // ~105000 m²

Great for capacity planning and resolution selection. See the full resolution table.

Exact cell area

The exact area of a specific cell — cells vary by location (about ±15% from equator to pole).

public function cellAreaKm2(int $cell): float
public function cellAreaM2(int $cell): float
public function cellAreaRads2(int $cell): float

Method	Unit
`cellAreaKm2`	square kilometers
`cellAreaM2`	square meters
`cellAreaRads2`	square radians (unit sphere)

echo $h3->cellAreaKm2($cell);   // exact area of this cell

// Total area covered by a set of cells
$total = 0.0;
foreach ($h3->gridDisk($cell, 3) as $c) {
    $total += $h3->cellAreaKm2($c);
}
printf("Coverage: %.3f km²\n", $total);

Edge length functions

Average edge length

The average length of a cell edge at a resolution.

public function getHexagonEdgeLengthAvgKm(int $res): float
public function getHexagonEdgeLengthAvgM(int $res): float

echo $h3->getHexagonEdgeLengthAvgKm(9);   // ~0.2 km
echo $h3->getHexagonEdgeLengthAvgM(9);    // ~200.786 m

Exact edge length

The exact length of a specific directed edge.

public function edgeLengthKm(int $edge): float
public function edgeLengthM(int $edge): float
public function edgeLengthRads(int $edge): float

$edge = $h3->originToDirectedEdges($cell)[0];
 
echo $h3->edgeLengthM($edge);   // exact length in meters

Great-circle distance

The straight-line distance between two coordinates over the surface of the Earth (the haversine distance). This works on raw coordinates — no cells required.

public function greatCircleDistanceKm(float $lat1, float $lng1, float $lat2, float $lng2): float
public function greatCircleDistanceM(float $lat1, float $lng1, float $lat2, float $lng2): float
public function greatCircleDistanceRads(float $lat1, float $lng1, float $lat2, float $lng2): float

Parameter	Type	Description
`$lat1`, `$lng1`	`float`	First point, in degrees
`$lat2`, `$lng2`	`float`	Second point, in degrees

// San Francisco to Oakland
$km = $h3->greatCircleDistanceKm(37.7749, -122.4194, 37.8044, -122.2712);
$m  = $h3->greatCircleDistanceM(37.7749, -122.4194, 37.8044, -122.2712);
 
printf("%.2f km (%.0f m)\n", $km, $m);

Distance vs. grid distance

greatCircleDistanceKm gives a real-world physical distance in km/m. The gridDistance function gives a grid distance in cell steps. Use the great-circle distance for sorting "nearest" results; use grid distance for hop counts and path complexity.

Utility functions

getNumCells

The total number of cells that exist at a resolution — across the whole Earth.

public function getNumCells(int $res): int

echo $h3->getNumCells(0);   // 122
echo $h3->getNumCells(9);   // a very large number

Use this for storage and capacity estimates.

getRes0Cells

Every resolution-0 base cell — all 122 of them.

public function getRes0Cells(): array

$baseCells = $h3->getRes0Cells();
echo count($baseCells);   // 122

Handy for partitioning a global dataset into 122 coarse buckets.

getPentagons

The 12 pentagon cells at a given resolution.

public function getPentagons(int $res): array

$pentagons = $h3->getPentagons(5);
echo count($pentagons);   // 12

Use this to pre-compute the pentagons you need to special-case. See Pentagons.

degsToRads / radsToDegs

Convert between degrees and radians.

public function degsToRads(float $degrees): float
public function radsToDegs(float $radians): float

$rads = $h3->degsToRads(180.0);   // 3.14159...
$degs = $h3->radsToDegs(3.14159); // ~180.0

Worked example — area-based pricing

Charge for a delivery zone proportional to the area it covers:

zone-pricing.php

use Foysal50x\H3\H3;
 
$h3 = H3::getInstance();
 
$center = $h3->latLngToCell(37.7749, -122.4194, 8);
$zone   = $h3->gridDisk($center, 2);
 
$areaKm2 = 0.0;
foreach ($zone as $c) {
    $areaKm2 += $h3->cellAreaKm2($c);
}
 
$ratePerKm2 = 5.00;
printf("Zone: %d cells, %.2f km², monthly fee $%.2f\n",
    count($zone), $areaKm2, $areaKm2 * $ratePerKm2);

Next steps

Handle failures and stay within memory limits in Error Handling & Safety.
See measurements applied in the Examples.