Miscellaneous H3 functions

These functions include descriptions of the H3 grid system.

degsToRads

Converts degrees to radians.

C

double degsToRads(double degrees);

Java

note

Use java.lang.Math.toRadians(double degrees) instead.

JavaScript (Live)

h3.degsToRads(degrees)

Live Editor

function example() { const degrees = 45; return h3.degsToRads(degrees); }

function example() {
  const degrees = 45;
  return h3.degsToRads(degrees);
}

Result

Loading...

Python

note

Use math.radians(degrees) instead.

Shell

$ h3 degsToRads --help
h3: Converts degrees to radians
H3 4.1.0

    degsToRads  Converts degrees to radians
    -d, --degree <DEG>  Required. Angle in degrees
    -h, --help  Show this help message.

$ h3 degsToRads -d 180
3.1415926536

radsToDegs

Converts radians to degrees.

C

double radsToDegs(double radians);

Java

note

Use java.lang.Math.toDegrees(double radians) instead.

JavaScript (Live)

h3.radsToDegs(h)

Live Editor

function example() { const radians = 3.14159; return h3.radsToDegs(radians); }

function example() {
  const radians = 3.14159;
  return h3.radsToDegs(radians);
}

Result

Loading...

Python

note

Use math.degrees(radians) instead.

Shell

$ h3 radsToDegs --help
h3: Converts radians to degrees
H3 4.1.0

    radsToDegs  Converts radians to degrees
    -r, --radian <RAD>  Required. Angle in radians
    -h, --help  Show this help message.

$ h3 radsToDegs -r 1
57.2957795131

getHexagonAreaAvgKm2

Average hexagon area in square kilometers at the given resolution. Excludes pentagons.

C

H3Error getHexagonAreaAvgKm2(int res, double *out);

Java

double getHexagonAreaAvg(int res, AreaUnit unit);

JavaScript (Live)

h3.getHexagonAreaAvg(res, h3.UNITS.km2)

Live Editor

function example() { const res = 5; return h3.getHexagonAreaAvg(res, h3.UNITS.km2); }

function example() {
  const res = 5;
  return h3.getHexagonAreaAvg(res, h3.UNITS.km2);
}

Result

Loading...

Python

h3.average_hexagon_area(res, unit='km^2')

Shell

$ h3 getHexagonAreaAvgKm2 --help
h3: The average area in square kilometers for a hexagon of a given resolution (excludes pentagons)
H3 4.1.0

    getHexagonAreaAvgKm2    The average area in square kilometers for a hexagon of a given resolution (excludes pentagons)
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.

$ h3 getHexagonAreaAvgKm2 -r 1
609788.4417941332

getHexagonAreaAvgM2

Average hexagon area in square meters at the given resolution. Excludes pentagons.

C

H3Error getHexagonAreaAvgM2(int res, double *out);

Java

double getHexagonAreaAvg(int res, AreaUnit unit);

JavaScript (Live)

h3.getHexagonAreaAvg(res, h3.UNITS.m2)

Live Editor

function example() { const res = 5; return h3.getHexagonAreaAvg(res, h3.UNITS.m2); }

function example() {
  const res = 5;
  return h3.getHexagonAreaAvg(res, h3.UNITS.m2);
}

Result

Loading...

Python

h3.average_hexagon_area(res, unit='m^2')

Shell

$ h3 getHexagonAreaAvgM2 --help
h3: The average area in square meters for a hexagon of a given resolution (excludes pentagons)
H3 4.1.0

    getHexagonAreaAvgM2 The average area in square meters for a hexagon of a given resolution (excludes pentagons)
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.

$ h3 getHexagonAreaAvgM2 -r 5
252903858.1819452047

cellAreaRads2

Exact area of specific cell in square radians.

C

H3Error cellAreaRads2(H3Index h, double *out);

Java

double cellArea(long h3, AreaUnit unit);
int cellArea(String h3Address, AreaUnit unit);

JavaScript (Live)

h3.cellArea(h, h3.UNITS.rads2)

Live Editor

function example() { const h = '85283473fffffff'; return h3.cellArea(h, h3.UNITS.rads2); }

function example() {
  const h = '85283473fffffff';
  return h3.cellArea(h, h3.UNITS.rads2);
}

Result

Loading...

Python

h3.cell_area(h, unit='rads^2')

Shell

$ h3 cellAreaRads2 --help
h3: The exact area of a specific cell in square radians
H3 4.1.0

    cellAreaRads2   The exact area of a specific cell in square radians
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 cellAreaRads2 -c 85283473fffffff
0.0000065310

cellAreaKm2

Exact area of specific cell in square kilometers.

C

H3Error cellAreaKm2(H3Index h, double *out);

Java

double cellArea(long h3, AreaUnit unit);
int cellArea(String h3Address, AreaUnit unit);

JavaScript (Live)

h3.cellArea(h, h3.UNITS.km2)

Live Editor

function example() { const h = '85283473fffffff'; return h3.cellArea(h, h3.UNITS.km2); }

function example() {
  const h = '85283473fffffff';
  return h3.cellArea(h, h3.UNITS.km2);
}

Result

Loading...

Python

h3.cell_area(h, unit='km^2')

Shell

$ h3 cellAreaKm2 --help
h3: The exact area of a specific cell in square kilometers
H3 4.1.0

    cellAreaKm2 The exact area of a specific cell in square kilometers
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 cellAreaKm2 -c 85283473fffffff
265.0925581283

cellAreaM2

Exact area of specific cell in square meters.

C

H3Error cellAreaM2(H3Index h, double *out);

Java

double cellArea(long h3, AreaUnit unit);
int cellArea(String h3Address, AreaUnit unit);

JavaScript (Live)

h3.cellArea(h, h3.UNITS.m2)

Live Editor

function example() { const h = '85283473fffffff'; return h3.cellArea(h, h3.UNITS.m2); }

function example() {
  const h = '85283473fffffff';
  return h3.cellArea(h, h3.UNITS.m2);
}

Result

Loading...

Python

h3.cell_area(h, unit='m^2')

Shell

$ h3 cellAreaM2 --help
h3: The exact area of a specific cell in square meters
H3 4.1.0

    cellAreaM2  The exact area of a specific cell in square meters
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 cellAreaM2 -c 85283473fffffff
265092558.1282823086

getHexagonEdgeLengthAvgKm

Average hexagon edge length in kilometers at the given resolution. Excludes pentagons.

C

H3Error getHexagonEdgeLengthAvgKm(int res, double *out);

Java

double getHexagonEdgeLengthAvg(int res, LengthUnit unit);

JavaScript (Live)

h3.getHexagonEdgeLengthAvg(res, h3.UNITS.km)

Live Editor

function example() { const res = 5; return h3.getHexagonEdgeLengthAvg(res, h3.UNITS.km); }

function example() {
  const res = 5;
  return h3.getHexagonEdgeLengthAvg(res, h3.UNITS.km);
}

Result

Loading...

Python

h3.average_hexagon_edge_length(res, unit='km')

Shell

$ h3 getHexagonEdgeLengthAvgKm --help
h3: The average hexagon edge length in kilometers of a given resolution (excludes pentagons)
H3 4.1.0

    getHexagonEdgeLengthAvgKm   The average hexagon edge length in kilometers of a given resolution (excludes pentagons)
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.

$ h3 getHexagonEdgeLengthAvgKm -r 5
9.8540909900

getHexagonEdgeLengthAvgM

Average hexagon edge length in meters at the given resolution. Excludes pentagons.

C

H3Error getHexagonEdgeLengthAvgM(int res, double *out);

Java

double getHexagonEdgeLengthAvg(int res, LengthUnit unit);

JavaScript (Live)

h3.getHexagonEdgeLengthAvg(res, h3.UNITS.m)

Live Editor

function example() { const res = 5; return h3.getHexagonEdgeLengthAvg(res, h3.UNITS.m); }

function example() {
  const res = 5;
  return h3.getHexagonEdgeLengthAvg(res, h3.UNITS.m);
}

Result

Loading...

Python

h3.average_hexagon_edge_length(res, unit='m')

Shell

$ h3 getHexagonEdgeLengthAvgM --help
h3: The average hexagon edge length in meters of a given resolution (excludes pentagons)
H3 4.1.0

    getHexagonEdgeLengthAvgM    The average hexagon edge length in meters of a given resolution (excludes pentagons)
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.

$ h3 getHexagonEdgeLengthAvgM -r 5
9854.0909900000

edgeLengthKm

Exact edge length of specific unidirectional edge in kilometers.

C

H3Error edgeLengthKm(H3Index edge, double *length);

Java

double edgeLength(long h3, LengthUnit unit);
double edgeLength(String h3Address, LengthUnit unit);

JavaScript (Live)

h3.edgeLength(h3, h3.UNITS.km)

Live Editor

function example() { const h = '115283473fffffff'; return h3.edgeLength(h, h3.UNITS.km); }

function example() {
  const h = '115283473fffffff';
  return h3.edgeLength(h, h3.UNITS.km);
}

Result

Loading...

Python

h3.edge_length(h, unit='km')

Shell

$ h3 edgeLengthKm --help
h3: The exact edge length of a specific directed edge in kilometers
H3 4.1.0

    edgeLengthKm    The exact edge length of a specific directed edge in kilometers
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 edgeLengthKm -c 115283473fffffff
10.2947360862

edgeLengthM

Exact edge length of specific unidirectional edge in meters.

C

H3Error edgeLengthM(H3Index edge, double *length);

Java

double edgeLength(long h3, LengthUnit unit);
double edgeLength(String h3Address, LengthUnit unit);

JavaScript (Live)

h3.edgeLength(h3, h3.UNITS.m)

Live Editor

function example() { const h = '115283473fffffff'; return h3.edgeLength(h, h3.UNITS.m); }

function example() {
  const h = '115283473fffffff';
  return h3.edgeLength(h, h3.UNITS.m);
}

Result

Loading...

Python

h3.edge_length(h, unit='m')

Shell

$ h3 edgeLengthM --help
h3: The exact edge length of a specific directed edge in meters
H3 4.1.0

    edgeLengthM The exact edge length of a specific directed edge in meters
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 edgeLengthM -c 115283473fffffff
10294.7360861995

edgeLengthRads

Exact edge length of specific unidirectional edge in radians.

C

H3Error edgeLengthRads(H3Index edge, double *length);

Java

double edgeLength(long h3, LengthUnit unit);
double edgeLength(String h3Address, LengthUnit unit);

JavaScript (Live)

h3.edgeLength(h3, h3.UNITS.rads)

Live Editor

function example() { const h = '115283473fffffff'; return h3.edgeLength(h, h3.UNITS.rads); }

function example() {
  const h = '115283473fffffff';
  return h3.edgeLength(h, h3.UNITS.rads);
}

Result

Loading...

Python

h3.edge_length(h, unit='rads')

Shell

$ h3 edgeLengthRads --help
h3: The exact edge length of a specific directed edge in radians
H3 4.1.0

    edgeLengthRads  The exact edge length of a specific directed edge in radians
    -c, --cell <index>  Required. H3 Cell
    -h, --help  Show this help message.

$ h3 edgeLengthRads -c 115283473fffffff
0.0016158726

getNumCells

Number of unique H3 indexes at the given resolution.

C

H3Error getNumCells(int res, int64_t *out);

Java

long getNumCells(int res);

JavaScript (Live)

h3.getNumCells(res)

Live Editor

function example() { const res = 5; return h3.getNumCells(res); }

function example() {
  const res = 5;
  return h3.getNumCells(res);
}

Result

Loading...

Python

h3.get_num_cells(res)

Shell

$ h3 getNumCells --help
h3: The number of unique H3 cells for a specified resolution
H3 4.1.0

    getNumCells The number of unique H3 cells for a specified resolution
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.

$ h3 getNumCells -r 5
2016842

getRes0Cells

Provide all the resolution 0 H3 cells. These are the coarsest cells that can be represented in the H3 system and are the parents/ancestors of all other cells in the H3 grid system. The returned cells correspond to the 122 base cells.

C

H3Error getRes0Cells(H3Index *out);

out must be an array of at least size res0CellCount().

Java

Collection<Long> getRes0Cells();
Collection<String> getRes0CellAddresses();

JavaScript (Live)

h3.getRes0Cells()

Live Editor

function example() { return h3.getRes0Cells(); }

function example() {
  return h3.getRes0Cells();
}

Result

Loading...

Python

h3.get_res0_cells()

Shell

$ h3 getRes0Cells --help
h3: Returns all of the resolution 0 cells
H3 4.1.0

    getRes0Cells    Returns all of the resolution 0 cells
    -h, --help  Show this help message.
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 getRes0Cells
[ "8001fffffffffff", "8003fffffffffff", "8005fffffffffff", "8007fffffffffff", "8009fffffffffff", "800bfffffffffff", "800dfffffffffff", "800ffffffffffff", "8011fffffffffff", "8013fffffffffff", "8015fffffffffff", "8017fffffffffff", "8019fffffffffff", "801bfffffffffff", "801dfffffffffff", "801ffffffffffff", "8021fffffffffff", "8023fffffffffff", "8025fffffffffff", "8027fffffffffff", "8029fffffffffff", "802bfffffffffff", "802dfffffffffff", "802ffffffffffff", "8031fffffffffff", "8033fffffffffff", "8035fffffffffff", "8037fffffffffff", "8039fffffffffff", "803bfffffffffff", "803dfffffffffff", "803ffffffffffff", "8041fffffffffff", "8043fffffffffff", "8045fffffffffff", "8047fffffffffff", "8049fffffffffff", "804bfffffffffff", "804dfffffffffff", "804ffffffffffff", "8051fffffffffff", "8053fffffffffff", "8055fffffffffff", "8057fffffffffff", "8059fffffffffff", "805bfffffffffff", "805dfffffffffff", "805ffffffffffff", "8061fffffffffff", "8063fffffffffff", "8065fffffffffff", "8067fffffffffff", "8069fffffffffff", "806bfffffffffff", "806dfffffffffff", "806ffffffffffff", "8071fffffffffff", "8073fffffffffff", "8075fffffffffff", "8077fffffffffff", "8079fffffffffff", "807bfffffffffff", "807dfffffffffff", "807ffffffffffff", "8081fffffffffff", "8083fffffffffff", "8085fffffffffff", "8087fffffffffff", "8089fffffffffff", "808bfffffffffff", "808dfffffffffff", "808ffffffffffff", "8091fffffffffff", "8093fffffffffff", "8095fffffffffff", "8097fffffffffff", "8099fffffffffff", "809bfffffffffff", "809dfffffffffff", "809ffffffffffff", "80a1fffffffffff", "80a3fffffffffff", "80a5fffffffffff", "80a7fffffffffff", "80a9fffffffffff", "80abfffffffffff", "80adfffffffffff", "80affffffffffff", "80b1fffffffffff", "80b3fffffffffff", "80b5fffffffffff", "80b7fffffffffff", "80b9fffffffffff", "80bbfffffffffff", "80bdfffffffffff", "80bffffffffffff", "80c1fffffffffff", "80c3fffffffffff", "80c5fffffffffff", "80c7fffffffffff", "80c9fffffffffff", "80cbfffffffffff", "80cdfffffffffff", "80cffffffffffff", "80d1fffffffffff", "80d3fffffffffff", "80d5fffffffffff", "80d7fffffffffff", "80d9fffffffffff", "80dbfffffffffff", "80ddfffffffffff", "80dffffffffffff", "80e1fffffffffff", "80e3fffffffffff", "80e5fffffffffff", "80e7fffffffffff", "80e9fffffffffff", "80ebfffffffffff", "80edfffffffffff", "80effffffffffff", "80f1fffffffffff", "80f3fffffffffff" ]

res0CellCount

Number of resolution 0 H3 indexes, which is defined as 122.

C

int res0CellCount(void);

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

note

This function exists for memory management and is not exposed.

getPentagons

All the pentagon H3 cells at the specified resolution. There are 12 pentagons at each resolution.

C

H3Error getPentagons(int res, H3Index *out);

out must be an array of at least size pentagonIndexCount().

Returns 0 (E_SUCCESS) on success.

Java

Collection<Long> h3.getPentagons(int res);
Collection<String> h3.getPentagonsAddresses(int res);

JavaScript (Live)

h3.getPentagons(res)

Live Editor

function example() { const res = 5; return h3.getPentagons(res); }

function example() {
  const res = 5;
  return h3.getPentagons(res);
}

Result

Loading...

Python

h3.get_pentagons(res)

Shell

$ h3 getPentagons --help
h3: Returns all of the pentagons at the specified resolution
H3 4.1.0

    getPentagons    Returns all of the pentagons at the specified resolution
    -r, --resolution <res>  Required. Resolution, 0-15 inclusive.
    -h, --help  Show this help message.
    -f, --format <FMT>  'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json)

$ h3 getPentagons -r 5
[ "85080003fffffff", "851c0003fffffff", "85300003fffffff", "854c0003fffffff", "85620003fffffff", "85740003fffffff", "857e0003fffffff", "85900003fffffff", "85a60003fffffff", "85c20003fffffff", "85d60003fffffff", "85ea0003fffffff" ]

pentagonCount

Number of pentagon H3 cells per resolution. This is always 12, but provided as a convenience.

C

int pentagonCount(void);

Java

note

This function exists for memory management and is not exposed.

JavaScript (Live)

note

This function exists for memory management and is not exposed.

Python

note

This function exists for memory management and is not exposed.

Shell

$ h3 pentagonCount --help
h3: Returns 12
H3 4.1.0

    pentagonCount   Returns 12
    -h, --help  Show this help message.

$ h3 pentagonCount
12

greatCircleDistanceKm

Gives the "great circle" or "haversine" distance between pairs of LatLng points (lat/lng pairs) in kilometers.

C

double greatCircleDistanceKm(const LatLng *a, const LatLng *b);

Java

double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);

JavaScript (Live)

h3.greatCircleDistance(point1, point2, h3.UNITS.km)

Live Editor

function example() { const point1 = [-10, 0]; const point2 = [10, 0]; return h3.greatCircleDistance(point1, point2, h3.UNITS.km) }

function example() {
  const point1 = [-10, 0];
  const point2 = [10, 0];
  return h3.greatCircleDistance(point1, point2, h3.UNITS.km)
}

Result

Loading...

Python

h3.great_circle_distance(point1, point2, unit='km')

Shell

$ h3 greatCircleDistanceKm --help
h3: Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in kilometers
H3 4.1.0

    greatCircleDistanceKm   Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in kilometers
    -i, --file <FILENAME>   The file to load the coordinates from. Use -- to read from stdin.
    -c, --coordinates <ARRAY>   The array of coordinates to convert. Up to 1500 characters.
    -h, --help  Show this help message.

$ h3 greatCircleDistanceKm -c "[[-10, 0], [10, 0]]"
2223.9010395046

greatCircleDistanceM

Gives the "great circle" or "haversine" distance between pairs of LatLng points (lat/lng pairs) in meters.

C

double greatCircleDistanceM(const LatLng *a, const LatLng *b);

Java

double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);

JavaScript (Live)

h3.greatCircleDistance(point1, point2, h3.UNITS.m);

Live Editor

function example() { const point1 = [-10, 0]; const point2 = [10, 0]; return h3.greatCircleDistance(point1, point2, h3.UNITS.m); }

function example() {
  const point1 = [-10, 0];
  const point2 = [10, 0];
  return h3.greatCircleDistance(point1, point2, h3.UNITS.m);
}

Result

Loading...

Python

h3.great_circle_distance(point1, point2, unit='m')

Shell

$ h3 greatCircleDistanceM --help
h3: Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in meters
H3 4.1.0

    greatCircleDistanceM    Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in meters
    -i, --file <FILENAME>   The file to load the coordinates from. Use -- to read from stdin.
    -c, --coordinates <ARRAY>   The array of coordinates to convert. Up to 1500 characters.
    -h, --help  Show this help message.

$ h3 greatCircleDistanceM -c "[[-10, 0], [10, 0]]"
2223901.0395045886

greatCircleDistanceRads

Gives the "great circle" or "haversine" distance between pairs of LatLng points (lat/lng pairs) in radians.

C

double greatCircleDistanceRads(const LatLng *a, const LatLng *b);

Java

double greatCircleDistance(LatLng point1, LatLng point2, LengthUnit unit);

JavaScript (Live)

h3.greatCircleDistance(point1, point2, h3.UNITS.rads)

Live Editor

function example() { const point1 = [-10, 0]; const point2 = [10, 0]; return h3.greatCircleDistance(point1, point2, h3.UNITS.rads) }

function example() {
  const point1 = [-10, 0];
  const point2 = [10, 0];
  return h3.greatCircleDistance(point1, point2, h3.UNITS.rads)
}

Result

Loading...

Python

h3.great_circle_distance(point1, point2, unit='rads')

Shell

$ h3 greatCircleDistanceRads --help
h3: Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in radians
H3 4.1.0

    greatCircleDistanceRads Calculates the 'great circle' or 'haversine' distance between two lat, lng points, in radians
    -i, --file <FILENAME>   The file to load the coordinates from. Use -- to read from stdin.
    -c, --coordinates <ARRAY>   The array of coordinates to convert. Up to 1500 characters.
    -h, --help  Show this help message.

$ h3 greatCircleDistanceRads -c "[[-10, 0], [10, 0]]"
0.3490658504

describeH3Error

Provides a human-readable description of an H3Error error code.

C

char *describeH3Error(H3Error err);

This function cannot fail, as it just returns a string stating that the H3Error value is itself invalid and does not allocate memory to do so. Do not call free on the result of this function.

JavaScript (Live)

note

Just read the .message property from the caught error, instead.

Live Editor

function example() { let errorMessage = "" try { h3.cellToChildrenSize("asdf", 9); } catch (e) { errorMessage = e.message; } return errorMessage; }

function example() {
  let errorMessage = ""
  try {
    h3.cellToChildrenSize("asdf", 9);
  } catch (e) {
    errorMessage = e.message;
  }
  return errorMessage;
}

Result

Loading...

Shell

$ h3 describeH3Error --help
h3: Returns a description of the provided H3 error code number, or indicates the number is itself invalid.
H3 4.1.0

    describeH3ErrorReturns a description of the provided H3 error code number, or indicates the number is itself invalid.
    -e, --error <CODE>  Required. H3 Error code to describe
    -h, --help  Show this help message.

$ h3 describeH3Error -e 5
Cell argument was not valid