When you send a request to the Mapzen Mobility APIs, part of the response you receive may appear to be nothing more than a jumble of characters. However, this is actually something known as an encoded polyline that stores a series of latitude, longitude coordinates as a single string, and greatly reduces the size of the shape.
This polyline…
unoagAndnhFsVxCkAsQUeEkAaRyBq\\_Ewm@mE_r@UwDeAuOMiCkAqQcB{UcF{u@OgCsA_Tly@}J~b@cFzPyBvC_@~C]jA]t@OC?xBNz@N~DrFje@ro@xBvClUb[tx@lhAjVb\lh@ls@`fAbyAj[fc@|EpGW\}DbGyLtOm@l@u@\cANkA?aDL_DNgD\iVhCqRhCeEuo@OkA?]G]OyBoCwc@e@qG
…encodes these points:
[[-122.407448,37.789947],[-122.407525,37.790325],[-122.407227,37.790363],[-122.407128,37.790374],[-122.406823,37.790412],[-122.40635,37.790473],[-122.405602,37.790569],[-122.404786,37.790672],[-122.404694,37.790683],[-122.404427,37.790718],[-122.404358,37.790725],[-122.404061,37.790763],[-122.403695,37.790813],[-122.402817,37.790927],[-122.402749,37.790935],[-122.402413,37.790977],[-122.402222,37.790042],[-122.402108,37.789466],[-122.402047,37.78918],[-122.402031,37.789104],[-122.402016,37.789024],[-122.402001,37.788986],[-122.401993,37.788959],[-122.401993,37.788894],[-122.402001,37.788833],[-122.402009,37.788803],[-122.402131,37.788707],[-122.402909,37.788093],[-122.402985,37.788032],[-122.403435,37.787673],[-122.40461,37.78675],[-122.405076,37.786376],[-122.405915,37.785713],[-122.407357,37.784576],[-122.407937,37.784122],[-122.408074,37.784011],[-122.408089,37.784023],[-122.408219,37.784118],[-122.408486,37.784339],[-122.408509,37.784362],[-122.408524,37.784389],[-122.408532,37.784423],[-122.408532,37.784461],[-122.408539,37.784542],[-122.408547,37.784622],[-122.408562,37.784706],[-122.408631,37.785079],[-122.4087,37.785392],[-122.407921,37.785491],[-122.407883,37.785499],[-122.407868,37.785499],[-122.407853,37.785503],[-122.407792,37.785511],[-122.407204,37.785583],[-122.407067,37.785602]]```
What you see when the precision is off
One of our most common technical support requests is from users attempting to encode or decode a route response with fewer than six digits of precision. Doing this can result in nonsensical coordinates, negative elevations values, or points showing up in the ocean—far away from potential route paths.
For example, a user working with Map Matching recently noticed, “I always get error 171: No suitable edges near location, and some weird positions like [378.07744, -1224.19701], [378.07744, -1224.19756]…” It turned out the user had decoded with a polyline utility from Google, and the problems were fixed by switching to Mapzen’s code.
Why six digits of decimal degree precision?
A key distinction of how Mapzen APIs integrate encoded polylines is that they use six digits of decimal degree precision. This is an enhancement of the algorithms from Google and the APIs from other mapping providers that use five digits of precision. That additional digit gives you extra detail and can return more accurate results along a path — at the equator, six digits gives you 10cm of precision, while five digits yields about a meter. This can make a significant difference in the placement of a route on a road. Also, GeoJSON recently standardized on 6 digits of precision.
The requirement for using six digits applies to any API that accepts inputs of or returns encoded polylines, including Mapzen Turn-by-Turn, Isochrone, Optimized Route, Map Matching, and Elevation. These use calculations from Valhalla, the open-source routing project.
Why does a difference in precision cause issues? The last step in decoding a polyline involves converting an integer into a decimal coordinate, with the presumption that it will be a certain number of digits long. Using five digits of decimal precision instead of six in this last step will lead to the decimal point being placed in the wrong location.
If you have trouble remembering the number of digits with Mapzen APIs, these rhymes can help:
Fewer than six, you need a fix.
With only five, results take a dive.
Use five plus one, you are done.
Decode with our tools for test, results are best.
Tools for decoding with six digits
When you are working with Mapzen’s APIs, only use our tools to decode polylines. In the Mobility documentation, you can find sample code to decode shapes in JavaScript, C++, and Python. We also built this handy tool where you can paste an encoded polyline string, decode it, and see the locations on a map (and save to GeoJSON).
