Request Encoding
When requesting a map, parameters such as position (c), center point (ctr) and POIs (poi) contain geolocation coordinates defined by latitude and longitude. These parameters may also be specified using an encoded geolocation, which can shorten or help obfuscate the URL.
To provide encoded geolocations, use the parameters c, ctr or poi with a Base64-encoded string prefixed with 'e.' as the value instead of normal latitude, longitude pair.
For position (c) and center point (ctr) there are also encoded parameter variants e and ectr that do not need the prefix 'e.' in the value string. Note, however, that some jurisdictions, such as China, may not accept unencoded geolocations in the URLs, especially if the URLs are publicly visible.
| Parameter | Unencoded Example | Encoded Example |
|---|---|---|
| Position | c=lat,lon | c=e.Base64String (or e=Base64String) |
| Center point | ctr=lat,lon | ctr=e.Base64String (or ectr=Base64String) |
| Points of interest | poi=lat1,lon1,lat2,lon2,... | poi=e.Base64String1,e.Base64String2,... |
The steps involved in encoding location parameters are as follows:
- The co-ordinates of a geographic location are initially defined as two floating point numbers for latitude and longitude.
- The longitude is converted to an integer (intBits) using IEEE 754-2008 floating-point "single format" bit layout.
- The latitude is converted to an integer (intBits) using IEEE 754-2008 floating-point "single format" bit layout.
- A byte array is created consisting of the intBits encoded latitude followed by the intBits encoded longitude.
- The byte array is then encoded as a Base64 string using the standard algorithm as defined in RFC152 format (MIME).
- Any padding characters (=) are removed from the Base64 encoded string.
- In order to avoid using characters with a special meaning in the URL, two further substitutions are then made to the Base64-encoded string.
- All plus signs (+) are changed to minus signs (-)
- All forward slashes (/) are changed to underscores (_)
- Prefix 'e.' is appended to the beginning of the Base64-encoded string.
