Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

Hierarchical hexagonal geospatial indexing system

Project description

H3 Logo

h3-py

PyPI version PyPI downloads conda version version

Tests codecov

Python bindings for the H3 Core Library.

For API reference, see the H3 Documentation.

Installation

From PyPI:

pip install h3

From conda:

conda config --add channels conda-forge
conda install h3-py

New since v3.6.1: We upload pre-built Python Wheels to PyPI for Linux/Mac/Windows, which should avoid many previous installation issues.

Usage

>>> import h3
>>> lat, lng = 0, 0
>>> resolution = 0
>>> h3.geo_to_h3(lat, lng, resolution)
'8075fffffffffff'

Example gallery

Browse a collection of example notebooks, and if you have examples or visualizations of your own, please feel free to contribute!

We also have a simple walkthrough of the API. For more information, please see the H3 Documentation.

APIs

We provide multiple APIs in h3-py. All APIs have the same set of functions, but differ in their input/output formats.

h3.api.basic_str

H3 indexes are represented as Python strs, using list and set for collections.

This is the default API provided when you import h3. That is, import h3.api.basic_str as h3 and import h3 are basically equivalent.

>>> import h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
'8075fffffffffff'

>>> h3.hex_ring(h, 1)
{'8055fffffffffff',
 '8059fffffffffff',
 '807dfffffffffff',
 '8083fffffffffff',
 '8099fffffffffff'}

h3.api.basic_int

H3 indexes are represented as Python ints, using list and set for collections.

>>> import h3.api.basic_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> h3.hex_ring(h, 1)
{577973680303243263,
 578044049047420927,
 578677367745019903,
 578782920861286399,
 579169948954263551}

h3.api.numpy_int

H3 indexes are represented as uint64s, using numpy.ndarray for collections.

The intention is for this API to be faster and more memory-efficient by not requiring int to str conversion and by using no-copy numpy arrays instead of Python lists and sets.

>>> import h3.api.numpy_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> h3.hex_ring(h, 1)
array([578782920861286399, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

Note that h3 has no runtime dependencies on other libraries, so a standard pip install will install no additional libraries. However, h3.api.numpy_int requires numpy. To have numpy installed (if it isn't already) along with h3, run pip install h3[numpy].

h3.api.memview_int

H3 indexes are represented as uint64s, using Python memoryview objects for collections.

This API has the same benefits as numpy_int, except it uses (the less well-known but dependency-free) memoryview.

>>> import h3.api.memview_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> mv = h3.hex_ring(h, 1)
>>> mv
<MemoryView of 'array' at 0x11188c710>

>>> mv[0]
578782920861286399

>>> list(mv)
[578782920861286399,
 578044049047420927,
 577973680303243263,
 578677367745019903,
 579169948954263551]

When using this API with numpy, note that numpy.array creates a copy of the data, while numpy.asarray does not create a copy and the result points to the same memory location as the memoryview object.

Continuing from the example above,

>>> mv = h3.hex_ring(h, 1)
>>> a = np.array(mv)
>>> mv[0] = 0
>>> a
array([578782920861286399, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

>>> mv = h3.hex_ring(h, 1)
>>> a = np.asarray(mv)
>>> mv[0] = 0
>>> a
array([                 0, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

Versioning

h3-py wraps the H3 Core Library, which is written in C. Both projects employ semantic versioning, with versions taking the form X.Y.Z.

h3-py will match the C library in major and minor numbers (X.Y), but may be different on the patch (Z) number.

Use h3.versions() to see the version numbers for both h3-py and the C library. For example,

>>> import h3
>>> h3.versions()
{'c': '3.6.3', 'python': '3.6.1'}

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for h3, version 3.7.0
Filename, size File type Python version Upload date Hashes
Filename, size h3-3.7.0-cp27-cp27m-macosx_10_9_x86_64.whl (699.5 kB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size h3-3.7.0-cp27-cp27m-manylinux2010_x86_64.whl (781.8 kB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size h3-3.7.0-cp27-cp27mu-manylinux2010_x86_64.whl (781.8 kB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size h3-3.7.0-cp35-cp35m-macosx_10_9_x86_64.whl (680.6 kB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size h3-3.7.0-cp35-cp35m-manylinux2010_x86_64.whl (786.9 kB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size h3-3.7.0-cp35-cp35m-win_amd64.whl (563.5 kB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size h3-3.7.0-cp36-cp36m-macosx_10_9_x86_64.whl (687.9 kB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size h3-3.7.0-cp36-cp36m-manylinux2010_x86_64.whl (792.4 kB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size h3-3.7.0-cp36-cp36m-win_amd64.whl (568.4 kB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size h3-3.7.0-cp37-cp37m-macosx_10_9_x86_64.whl (688.6 kB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size h3-3.7.0-cp37-cp37m-manylinux2010_x86_64.whl (790.8 kB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size h3-3.7.0-cp37-cp37m-win_amd64.whl (568.4 kB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size h3-3.7.0-cp38-cp38-macosx_10_9_x86_64.whl (685.4 kB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size h3-3.7.0-cp38-cp38-manylinux2010_x86_64.whl (802.4 kB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size h3-3.7.0-cp38-cp38-win_amd64.whl (575.0 kB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size h3-3.7.0-cp39-cp39-manylinux2010_x86_64.whl (802.5 kB) File type Wheel Python version cp39 Upload date Hashes View
Filename, size h3-3.7.0-cp39-cp39-win_amd64.whl (575.1 kB) File type Wheel Python version cp39 Upload date Hashes View
Filename, size h3-3.7.0.tar.gz (17.3 MB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page