There is no question that the encoded polyline technique offers great performance benefits for drawing polylines on a Google Map. However, there are two main potential pitfalls to be aware of that have been discussed fairly extensively on the API discussion group but are ignored in the API documentation.
Encoded polylines occasionally disappear for no apparent reason.
It's not a huge deal, since it really happens only very rarely.
Furthermore, it happens consistently and, when it happens, it
seems that you can fix it by fiddling with the encoding parameters.
Generally, smaller values of verySmall seem to help.
Here's an example of a disappearing
encoded polyline generated by my encoder. The behavior is not
unique to my encoding process. In fact, we can coerce Google's
own encoders to produce the same behavior, as
explained here.
Another example given in this thread in the API discussion group was generated by a previous version of my encoder. That example works when encoded with the current version. No one seems to have an explanation and I would have to consider it to be a bug in the API.
Quite a few people in the API discussion group have reported a strange cumulative deviation of their encoded path from the correct path. Examples include thread 1, thread 2, and thread 3. All these cases are instances of confusion over double-backslashes in string literals.
The encoded point string can include a back-slash (\) as important information. Of course, the back-slash is also used as the escape character in a string literal - for example, "\n" generates a return. Thus the correct string literal notation for the string with two characters, namely a back-slash (\) follows by the letter n, is "\\n". More generally, every occurrence of "\" in a string literal should be replaced with "\\".
String literals are a common way that strings arise in our programs, but they are not the only way. If you work with encoded polylines at the programming level, then you must understand that the following all lead to the same string, namely a back-slash followed by the letter n.
var s1 = "\\n";var s2 = String.fromCharCode(92) + String.fromCharCode(110);var s3 = document.formName.inputString.value;, where
the inputString field of formName contains the two characters \n.
If you are simply defining a static encoded polyline using a string
literal as the points property of the encoded polyline,
then you would probably enter your string in the way that s1
has been entered. The variable s2 is analogous to the
way an encoded point string might be built dynamically. If you are
reading the value of a string from an input form, then your code
will likely look something like that defining the variable s3.
Note, however, that the characters typed into the inputString field are
different from the characters in the string literal representation;
in particular, there is no double back-slash. The reason is that
string values are read from forms verbatim.
This last point concerning the verbatim reading of strings from HTML forms causes an apparent inconsistency between Google's polyline encoding utility and the API. Take a string which includes back-slashes (with double back-slashes or single) and decode it using the utility. Then use the same string as a string literal in the API. The result will be different. Conversely, if you encode a path which produces a back-slash using Google's utility and use the API to plot this using a string literal, the result will not be correct.
Let's state an example as explicitly as possible, just because the API documentation has ignored this for way too long. Take your favorite place specified as a (lat, lon) pair; mine happens to be (35.6,-82.55). Now step by (-0.00015,-0.00015), so I step to (35.59985, -82.55015). The result is an actual double back-slash, so the string literal encoding of the step should be "\\\\". Google's utility yields "\\". The utility decodes this correctly, since it's read from form input. The result is a step to the South-West. If you use the resulting string as a string literal in the API, however, you get a line which goes North-South.
I suppose I think that this is not a bug in the API. I do however think it is an egregious omission from the documentation.