Hierarchical hexagonal geospatial indexing system
Project description
h3-py
Python bindings for the H3 Core Library.
For API reference, please see the H3 Documentation.
New in v3.6.1: We upload pre-built Python Wheels to PyPI for Linux/Mac/Windows, which should avoid many previous installation issues.
Install from PyPI
pip install h3
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.6.2-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 427bcf85c40c1483f571bb924286cb7b8473042b822bee95b27d6ac116a35685 |
|
MD5 | 0b40966f2430dcfb9f1242d10e74b7ba |
|
BLAKE2b-256 | 08483575317f69a9394eccb09137738577adc174899de9678ceb4c110f99d78e |
Hashes for h3-3.6.2-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 91643388021054278844f584b724061b635892919bcb5218dbc95be5392cca96 |
|
MD5 | 0325de51e9581bc216648aee84d6186c |
|
BLAKE2b-256 | 176d772e6c5888971d5548f036f0ac6cb3aca579cc6b34f1057efa6890dae8a8 |
Hashes for h3-3.6.2-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 443c040f3698892719f55a982307448c5c7be0f98346b3438de23181c7e2a2d6 |
|
MD5 | e52638156f733e456738f0d4a3f5ef57 |
|
BLAKE2b-256 | 2e659e0de44b1a2f212664e224e64f7a2e4d49460006b51131ed36b91e1b1f97 |
Hashes for h3-3.6.2-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 452d899f9bbd662e3abc6fc54980e6b4b02b2b97b38c6f3a5298bcd1a962df19 |
|
MD5 | 23a9e704c9f7b16de159e58e58adb88d |
|
BLAKE2b-256 | e3816bfc636f49290ea0d18a9176876baa555c9b9a6fadc3574b93d2c5d7f58b |
Hashes for h3-3.6.2-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 180bfce2a12c0fc7d93e4ffbb7feee2af62704214f6306a7f0639222193fdd28 |
|
MD5 | 6a836fbde6396860d4def24f42897718 |
|
BLAKE2b-256 | bddaa3548934b718786946f78210f7562403a3edeb87c01258d7ca16aadcdf74 |
Hashes for h3-3.6.2-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b41764fbf338af163e2d4a98a169f1ac3e179bf952c70e9c52b8f23ae533b90 |
|
MD5 | f1192328c15b246a79e42b65ef334d29 |
|
BLAKE2b-256 | 0dcadec67b9175847c3e49e095fab0ad81d53d00f6d20d760b098900c0056f1c |
Hashes for h3-3.6.2-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 02c657d068cc8d88340a4baa389e3096515e6fc5a99183cacbffb1e02d997a1c |
|
MD5 | a179a3662af65cfce841f088987e19d1 |
|
BLAKE2b-256 | 37ad4557a185de6d1fb1e3499371085fc48a1c1d8dc2ee3efef6c54b3d4d065d |
Hashes for h3-3.6.2-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7be6c37f397fdb148773df7d4531c6ce46d6e3a766d1c746182990e298dd14e1 |
|
MD5 | 20ce0a933713b211c852598acd2a5bf3 |
|
BLAKE2b-256 | c97576f353aff2595bed44716b36d1593465fdaade0d35c171d3ed409518a50c |
Hashes for h3-3.6.2-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | df0fae94cb1bf0ed616afc314be76a2c02ac1feaa89540881909dce82ab16baf |
|
MD5 | b9bdd932ad4f7df343f44799ffd8b2de |
|
BLAKE2b-256 | bb521269850484a0c7b2048b437a45e2044c11e5cab41817b4dc3df32517912e |
Hashes for h3-3.6.2-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4bf2959fd1f3d57e497dad7cd2171a40019ab41c4e3ed7697a3edeef1bcb5ba |
|
MD5 | 720d7445f3b3e2426f6ba41a05738458 |
|
BLAKE2b-256 | 8d83d57f396bbc302a6e3f11e5a8262a6bcd69bde1d1a612de4bb1a59b17dda2 |
Hashes for h3-3.6.2-cp35-cp35m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8dfad6fcc84822227e4568471289f13fb28d387afcee97c8b5ce51d1a1d44ddc |
|
MD5 | 1773bb995fef08f1082deeb8ac93e938 |
|
BLAKE2b-256 | 619d98b5ae3671a72faeb459fa9b1c3cf0cd4a91c10ce4b6b9b70173561090b5 |
Hashes for h3-3.6.2-cp35-cp35m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9252796011258f364ba97d5039c2b570b8c58a20fc4ea6ca33f6bfdc32aa57a1 |
|
MD5 | c61b70fb1485b83e75b504a4a524e9b5 |
|
BLAKE2b-256 | 7bc3b46972a4652cbd1fa81d58e0e3a289d2a517d6c6274004fd62b0b178165b |
Hashes for h3-3.6.2-cp27-cp27mu-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 475379b8235d8d6a81e5bb671ad435b6c4e61cae3761f87b5fca091a27f13def |
|
MD5 | 09ad5103503a19ae7afd7cafcb09c8cb |
|
BLAKE2b-256 | f12153455514f787719d38c1ee7e1db8d1385c54e357a6f446d9fe6eded4bf59 |
Hashes for h3-3.6.2-cp27-cp27m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c740ac84b62d25309cd7308f8af233b18dc4665cdf9413214d4a2725d69e1073 |
|
MD5 | 8d0749d6a90d4ec3a135d0229d1c0d99 |
|
BLAKE2b-256 | b5c42547ea5a110cdf44a42e4a086f1a01faf789e87f668d324f73fcd6b6d2fd |
Hashes for h3-3.6.2-cp27-cp27m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e62dd411940a519e84b22d4152d87fd2fb6c090d2366897632eac399fe3f0d0 |
|
MD5 | c6cb72e0ee1fdef4de413fc6ebd8e0d8 |
|
BLAKE2b-256 | 6aaef79a5c4878abaacb34f57368780e8caec91f2615356bb010fc54d9087353 |