API reference

Encode and decode coordinates using Google’s Encoded Polyline Algorithm.

The Encoded Polyline Algorithm is a lossy compression algorithm that allows you to store a series of geographical coordinates as a single string. It was developed by Google.

The encoding process converts a longitude or latitude coordinate from a decimal value to a binary value, and then converts that into a series of ASCII characters. To further compress the data, values stored for longitude and latitude are offset from the previous longitude or latitude values. The algorithm is lossy because it uses a default maximum precision of five decimal places for longitude and latitude.

Encoding and decoding

encpoly.encode(locations, precision=None)

Encode the given coordinates as an encoded polyline.

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

To produce an encoded polyline, follow these steps for each individual longitude and latitude value.

  1. Take a signed longitude or latitude decimal value and multiply it by 1e5 (or other decimal precision if specified)
  2. Round the result using Python 2’s default rounding behaviour
  3. Convert the decimal value to binary (a negative value must be calculated using its two’s complement)
  4. Shift the binary value left by one bit
  5. If the original decimal value is negative, invert the encoding
  6. Break the binary value out into 5-bit chunks from right to left
  7. Place the 5-bit chunks into reverse order
  8. OR each value with 0x20 if another bit chunk follows
  9. Convert each value to decimal
  10. Add 63 to each value (this is to avoid, e.g., unprintable ASCII characters)
  11. Convert each value to its ASCII equivalent

Note

After the first latitude/longitude pair, the steps should be followed using offsets from the previous point.

If coordinates are provided with a greater decimal precision than is used during step 1, the resulting output will be lossy.

Parameters:
  • locations (iterable) – ordered latitude and longitude pairs (in y, x order) as a tuple, list, or other iterable
  • precision (int) – maximum decimal precision to use for longitude and latitude coordinates (defaults to 5)
Returns:

an encoded polyline
Return type:

str
encpoly.decode(polyline, precision=None)

Yield the given encoded polyline as an ordered series of points.

This essentially reverses the algorithm’s steps as outlined in the encode() documentation.

>>> for coord in decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@"):
...     print(coord)
...
[38.5, -120.2]
[40.7, -120.95]
[43.252, -126.453]
Parameters:
  • polyline (str) – encoded polyline to decode
  • precision (int) – maximum decimal precision used when the polyline was originally encoded (defaults to 5)
Yields:

iterable of lists of lat/lon coordinate pairs

Supporting functions and attributes

The following functions are attributes are used to support encoding and decoding and are not expected to be used directly. They’re documented here for completeness.

encpoly.codec.DEFAULT_PRECISION = 100000.0

When encoding values of longitude and latitude, use a default precision of five decimal places. This gives, very roughly, accuracy of one metre.

encpoly.codec.polyline_round(number)

Return the given number rounded to nearest integer.

>>> polyline_round(0.5)
1
>>> polyline_round(-0.5)
-1

Note

The rounding behaviour is “always round up 0.5”. This is not generally considered the standard way of rounding numbers now (Python 3 does it differently, for example). But it is what Python 2 does by default and it is, not coincidentally, what the Encoded Polyline Algorithm requires.

Parameters:number (float) – value to round to nearest integer
Returns:int
encpoly.codec.encode_coord(coord, precision)

Encode a given longitude or latitude value as an encoded polyline.

The encodes an individual value from a lat/lon pair into an ASCII value that can be used in an encoded polyline.

Tip

You probably want to use encpoly.encode() instead, as that function will encode a complete line (that is, a set of lat/lon pairs).

>>> encode_coord(-179.9832104, 1e5)
'`~oia@'
Parameters:
  • coord (float) – a single latitude or longitude coordinate
  • precision (float) – maximum decimal precision used to store the coordinate value
Returns:

the coordinate value as an encoded polyline
Return type:

str
encpoly.codec.decode_coords(polyline)

Yield alternating latitude and longitude values from a polyline.

Each coordinate is an offset from the last of its type, and has yet to be converted from its stored integer value to a floating point coordinate (see steps 1 and 2 of the encoding algorithm).

Tip

You probably want to use encpoly.decode() instead, as that function returns lat/lon pairs with offset and precision handled correctly.

>>> tuple(decode_coords("_p~iF~ps|U_ulLnnqC_mqNvxq`@"))
(3850000, -12020000, 220000, -75000, 255200, -550300)
Parameters:polyline (str) – encoded polyline to decode
Yields:iterable of alternating lat/lon coordinates