Hierarchical hexagonal geospatial indexing system
Project description
h3-py
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 str
s, 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 int
s, 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 uint64
s, 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 list
s and set
s.
>>> 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 uint64
s, 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'}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for h3-3.7.2-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2d3b6540a8b36032d57ab56d3db48d5c0ff936b60da28d8dfbf4c74be5f295f0 |
|
MD5 | 0cdaeacc42e3e9e10b12f3cc8d6c6b8c |
|
BLAKE2b-256 | a74779de7eb5b47dfb7363b803a72ad020f02636db7500ae2a77a41c0762eed4 |
Hashes for h3-3.7.2-cp39-cp39-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a1e86a00e5ff5da3c9e278679364a8640fd36d0e0b88a22a29c8c49c05fe4145 |
|
MD5 | 104ab82c6f2e80f17cd0dff12ff66cfd |
|
BLAKE2b-256 | a86076e487e8e268d6d792d89e93544e7408613baa88b05ce422d1989b292034 |
Hashes for h3-3.7.2-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8167e1389598a185d33c66cf5149d3a457780dbc7fb22f11ead1153cf1ac2fcb |
|
MD5 | cf8361e0c42fb2b6021c630d205291b4 |
|
BLAKE2b-256 | bd4fdc7d95a089fade3d735701a25ad5e3aaa00b42f05f9ebf46c4f45e941556 |
Hashes for h3-3.7.2-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e38c92ec8572ac071fb8d92ce811665d80e6ee019ee6c33b6ea708fd978d19e |
|
MD5 | 05fd307fe048ea84343afebb780ad763 |
|
BLAKE2b-256 | 017399d7160fd8936baa358afe33f62cd6f35b768b407d9ac105f2e2a7a769e2 |
Hashes for h3-3.7.2-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bb205325abeed4deb64e1a82bc10e21f2d0e86c1c1ebf6aa12e1859a096f2063 |
|
MD5 | 011ca2298cc45b5e1afefd88abc2aab6 |
|
BLAKE2b-256 | 5c42e476c2ee2e20f798a3762bdf5f2876e2311e655d998d1a01e215bde6efdf |
Hashes for h3-3.7.2-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d7c5db66b69ce5cce3b4b8c49264a85c06b8c0bf6970bd779437aec705dcfdf4 |
|
MD5 | 71e9b4d71fe7bf20fbde67d13ce34ef7 |
|
BLAKE2b-256 | 7828a13bb31183ae69641d7765523d7e8a210d25b81bae476cd3da6a16906b0d |
Hashes for h3-3.7.2-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 808478e912dc81fa15cf8cd5e08ebe623386e81e3767c983ea83ebd4e859d743 |
|
MD5 | 02175f6e1dd89ae8e4071a1110b53e20 |
|
BLAKE2b-256 | 8264e1bb0fd9af7044f36fef832451ac96fc5ffb0b2860702acfbc52036b054c |
Hashes for h3-3.7.2-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0f04a747dd3cccad055b5d44d9733454abfbc85e351a1cc186beced4697a650f |
|
MD5 | 69c27c65da83b99f03fe77ff08499035 |
|
BLAKE2b-256 | 4b0bccfc2691bc9585a479583052477eeff942ea7b3886b71a8568e69b627190 |
Hashes for h3-3.7.2-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1d88cccf881fee97daf94623dc65269e8500f597daf542ff1bc2583e9edf04d1 |
|
MD5 | 0c6203c1bee753ee6ec1c96e599cc481 |
|
BLAKE2b-256 | 50ae6bfeb9460b407de3068b6e65de2add5b687c93f86d86efc6fc7d7e249330 |
Hashes for h3-3.7.2-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cbf3ba462cf3f541cd8c1b4ed4dfff834307beb8a8bbb220a30931b2106e5c60 |
|
MD5 | 81148bc44f61acef933a698c9933919e |
|
BLAKE2b-256 | ee68a410670634bcbe8b120c57922a28c5fd1dc2876c8173e2c0d8a6e88b57a1 |
Hashes for h3-3.7.2-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e455a033bd536405989f8263595e0c18912167140b0a444ba797978e65b8f6b |
|
MD5 | 800637ba13198e51efd55486a8ebd8ad |
|
BLAKE2b-256 | b081b90c0ae344fb3513b79839ea7708b97a877cdf2c0e2d0cfda3fc8c4a2fc7 |
Hashes for h3-3.7.2-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3556ef201c8758839f84457abe76559cb5657f9ddf485a895f52032931657475 |
|
MD5 | e8f5934bc45fd82076db68121b544748 |
|
BLAKE2b-256 | 15ec9f3dee17a031094c4aa1ff7220e9837c7b6632a529e391fbdec7cc88f1fe |
Hashes for h3-3.7.2-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e9adde9f35187dcd3c031384d2968968f019c8eceea58e223a03723604abf7e0 |
|
MD5 | 7e995c29162f42c4408c0dbb5b70acd2 |
|
BLAKE2b-256 | 660d555c585fd978ce0c759df1e1a936673a7e02094cf2c719da968ea79acc40 |
Hashes for h3-3.7.2-cp35-cp35m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31e539bff3b94b80b6eb77f5aa514f90a9d1e15972db4778e8af861e6f47edd1 |
|
MD5 | abe5afe6155bffd93bf5dfe41f266fed |
|
BLAKE2b-256 | 74b648ee7d21f837b52178e93f02e9bc10e0ee000d8f34382b1dc281c2baf39a |
Hashes for h3-3.7.2-cp35-cp35m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 10496db335b748e32b219d388e0bf6503d47eb481281667789a4c84f9f368ea5 |
|
MD5 | 424a9ada7240d37c8ec42d69f6dcf9cf |
|
BLAKE2b-256 | 37b380cefb180474e28becbf04003f9a5be357f8b51477bab763dddb77ef5e30 |
Hashes for h3-3.7.2-cp27-cp27mu-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c1d8c1d8b2f56c5d0ce73f62c6deba407c41ce87958f0909da35b7c29f40bc77 |
|
MD5 | 552d0caba90088827e32ddad9b313631 |
|
BLAKE2b-256 | 47348f9eb982c5aa21bddd6164e3413d89bcd66a8d9fc7e758b86633ce65e287 |
Hashes for h3-3.7.2-cp27-cp27m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93748d1ae0d2d73352165b92ea2f52c0bb1aecf1d2a7808f6092fe709ddd1449 |
|
MD5 | 9db3ff626f48f605ad5ee13ec08d9ab0 |
|
BLAKE2b-256 | 606fe26e8df5db331dabb530158c476a7bd6ffda4a29c9447bc2034f9d201067 |
Hashes for h3-3.7.2-cp27-cp27m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1b1e455525a222d487010835630e7951f84b9034c6d7b9cf5501fbd6a9559453 |
|
MD5 | eeba7cab8a3ff3363492be63e406ea8c |
|
BLAKE2b-256 | 7bbe40b282e3522d56f244a934435f3dc5858f7020b9ce8ddb97fee4fc33ce76 |