Installation and usage¶

The latest encpoly release is available on PyPI, and you can install it using Pip:

pip install encpoly

Tip

When installing Python dependencies, it’s a good idea to use a virtual environment.

If you prefer, you can also install encpoly using a higher-level dependency-management tool like Poetry:

poetry add encpoly

Or Pipenv:

pipenv install encpoly

System requirements¶

The encpoly package requires Python 3.4+. It runs well under PyPy. It has no dependencies of its own. It’s multi-platform and works on Linux, MacOS, and Windows.

Usage¶

After you’ve installed the package you can import the encode() and decode() functions from the encpoly package:

>>> from encpoly import encode, decode

To encode a series of coordinates, pass them to the encode() function:

>>> coords = ((38.5, -120.2), (40.7, -120.95), (43.252, -126.453))
>>> encode(coords)
'_p~iF~ps|U_ulLnnqC_mqNvxq`@'

To decode a polyline, pass it to the decode() function:

>>> for (lat, lon) in decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@"):
...     print(lat, lon)
...
38.5 -120.2
40.7 -120.95
43.252 -126.453

Tip

The decode() function returns a generator. If you want to get a list or tuple of coordinates rather than a generator, wrap the function in list or tuple:

>>> tuple(decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@"))
([38.5, -120.2], [40.7, -120.95], [43.252, -126.453])

You’ll probably not need anything other than those two functions, but the full contents of the package are documented in the API reference.

Advanced usage¶

By default the Encoded Polyline Algorithm is lossy. When coordinates are encoded they are truncated to five decimal places. For example, the latitude and longitude coordinates 64.12345678, -21.987654321 would be encoded as 64.12345, -21.98765:

>>> list(decode(encode(((64.12345678, -21.987654321),))))
[[64.12346, -21.98765]]

You can, however, choose the precision at which coordinates are encoded using the precision argument:

>>> coords = ((64.12345678, -21.987654321),)
>>> encode(coords)
'sbkfKxmeeC'
>>> encode(coords, precision=8)
'{soqe}Jnv~x`bC'
>>> list(decode("{soqe}Jnv~x`bC", precision=8))
[[64.12345678, -21.98765432]]

Note

You must use the same value for precision when encoding and decoding. You can only set the precision for polylines as a whole, not individual coordinates within a polyline.

Package development¶

Encpoly is an open-source project and all contributions are welcome. Encpoly is developed on GitHub and the latest source code is always available from there. To get a copy of the code you can clone the public repository:

$ git clone https://github.com/JaGallup/encpoly.git

To install the package in “editable mode” you will need Poetry, a tool for dependency management and packaging in Python. Once you have both Poetry and a copy of the source you can install encpoly and its development dependencies into a virtual environment:

$ cd encpoly
$ poetry install

Test suite¶

Encpoly uses Pytest and Tox for testing. To run the tests locally, use:

tox -e py37

The example above runs tests against Python 3.7. You can also use other versions like py36 and pypy3.

The test suite is run automatically when the master branch is pushed to GitHub. The tests are run using Travis CI (Linux) and Appveyor (Windows) for Python 3.4+ and PyPy 3.5. Code coverage is tracked using Codecov.