h3 3.4.3

Python bindings for H3, a hierarchical hexagonal geospatial indexing system developed by Uber Technologies

H3-Python
=========

|Build Status| |Build Status Appveyor| |H3 Version| |License|

This library provides Python bindings for the `H3 Core
Library <https://github.com/uber/h3>`__. For API reference, please see
the `H3 Documentation <https://uber.github.io/h3/>`__.

Installing
==========

You need to have ``cc``, ``make``, and ``cmake`` in your ``$PATH`` when installing this
package:

.. code:: sh

which cc
/usr/bin/cc
which make
/usr/bin/make
which cmake
/usr/bin/cmake

.. code:: sh

pip install h3

Development
===========

.. code:: sh

git clone https://github.com/uber/h3-py.git && cd h3-py
virtualenv env
source env/bin/activate
pip install -r requirements-dev.txt
fab bootstrap

Usage
=====

The following visualizations are achieved with
`folium <https://github.com/python-visualization/folium>`__.

.. code:: python

from h3 import h3

Convert lat/lng to hexagon address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

h3_address = h3.geo_to_h3(37.3615593, -122.0553238, 5) # lat, lng, hex resolution
hex_center_coordinates = h3.h3_to_geo(h3_address) # array of [lat, lng]
hex_boundary = h3.h3_to_geo_boundary(h3_address) # array of arrays of [lat, lng]

.. image:: docs/source/Hexagon.png
:scale: 50%


Get KRings of hexagon
~~~~~~~~~~~~~~~~~~~~~

.. code:: python

h3.k_ring_distances(h3_address, 4) # array of 4 rings with size [1, 6, 12, 18]
h3.k_ring(h3_address, 4) # a collection of hexagons within kring sizes from 0 to 3

.. image:: docs/source/KRings.png
:scale: 50%


Polyfill a Geo Json with hexagons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

geoJson = {'type': 'Polygon',
'coordinates': [[[37.813318999983238, -122.4089866999972145],
[ 37.7866302000007224, -122.3805436999997056 ],
[37.7198061999978478, -122.3544736999993603],
[ 37.7076131999975672, -122.5123436999983966 ],
[37.7835871999971715, -122.5247187000021967],
[37.8151571999998453, -122.4798767000009008]]] }
hexagons = list(h3.polyfill(geoJson, 8)) # resolution 8

.. image:: docs/source/Polyfill.png
:scale: 50%


For more API reference, please see the `H3
Documentation <https://uber.github.io/h3/>`__.

.. |Build Status| image:: https://travis-ci.org/uber/h3-py.svg?branch=master
:target: https://travis-ci.org/uber/h3-py
.. |Build Status Appveyor| image:: https://ci.appveyor.com/api/projects/status/eaa11gfwmr0gtr5y/branch/master?svg=true
:target: https://ci.appveyor.com/project/Uber/h3-py/branch/master
.. |H3 Version| image:: https://img.shields.io/badge/h3-v3.4.2-blue.svg
:target: https://github.com/uber/h3/releases/tag/v3.4.2
.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: LICENSE