Synchronized Google Maps Data File Format

It will probably be quite helpful for you to open both the maps and the associated data files below so you will have specific examples in mind as you follow this discussion of the Synchronized Google Maps data file format.

The Northeastern University maps and its data file mapspots.txt

The satellite views of the major league baseball parks and its data file baseball.txt

The structure of each line with location data is as follows:

LocationName|Latitude|Longitude|ZoomLevel

As you can see, the data separator is a vertical bar: |.

The LocationName is the name that will appear in the dropdown menu. It can contain arbitrary characters including blanks but of course cannot include a vertical bar |. Leading and trailing whitespace in the LocationName will not appear in the dropdown menu and extra internal whitespace will be suppressed.

The Latitude and Longitude should be floating point string values that specify the geographic location. In practice, we have found that 5 decimal digits is sufficient accuracy.

The ZoomLevel should be an integer string value between 0 and 20 that specifies the zoom level.

There should be no whitespace in the Latitude, Longitude, or ZoomLevel data.

If the ZoomLevel is omitted for a particular location then when that location is selected the zoom will remain at its current value. This is the design choice in the file baseball.txt. If the user wants to zoom in or out when viewing one particular ballpark, they will get the same zoom level when they switch to a different ballpark.

In contrast, the file mapspots.txt for the Northeastern University maps always provides a ZoomLevel. Since the point of the data is to help locate a particular building or place of interest, the zoom level should always be set to focus on the entity selected.

It is possible to omit Latitude and Longitude. However, this is not especially useful unless you wish to have items in the dropdown list that have no behavior and merely serve as separators.

When the data file is read, an empty line is ignored. This convention makes it easy to separate actual data lines in the data file. This is extremely helpful when entering or editing latitude-longitude data.

We should now speak of the role of the 2 files mapspots.txt and baseball.txt.

When Synchronized Google Maps is invoked in its simplest form, the URL will look like:

..../maps/index.htm

In that case, the application will look for the specific data file mapspots.txt in the maps directory. If found, this file will be used to populate the dropdown list. If not found, then a default location will be used to initialize the maps and the dropdown menu will be made invisible.

It is possible to supply a different data file by using a query parameter to name the file. This is what we did for the ballparks:

..../maps/index.htm?data=baseball.txt

The file baseball.txt is then used to replace the file mapspots.txt in the creation of the dropdown.

It is also possible to use the data= query parameter to actively suppress the dropdown menu if that is desired. Here is how this is done:

..../maps/index.htm?data=none

The parameter data=none causes the maps application to ignore all data files including mapspots.txt. The dropdown menu will be made invisible.

There is a further bit of trickiness in the file baseball.txt that we should now explain. The first line of this file is:

?z=18&t1=h&t2=m&start=Boston

If the very first character in the data file is a question mark character ?, then the first line is treated as an embedded default query string.

The processing rule is this:

If a query parameter is set in an embedded default query string and is not set in the regular query string on the URL, then this embedded query parameter value will be used.

Thus, a regular query parameter dominates an embedded query parameter. Nevertheless, an embedded query parameter will prevail during initialization if that parameter is not set in the regular query string.

Here is what the above embedded default query string is specifying:

z=18: Set zoom level to 18

t1=h: Set the type of map 1 to hybrid satellite

t2=m: Set the type of map 2 to regular road map

start=Boston: Start with the location in the dropdown list whose location name starts with “Boston”, that is, start with “Boston Red Sox: Fenway Park”.

The zoom level is set to 18 since that turns out be just right for seeing an entire ballpark. The type of map 1 is set to hybrid satellite. Since, by default, one map is displayed initially, what the user will see is a hybrid satellite view. If the user chooses to see two synchronized maps, map 2 will be a regular road map.

The choice of Fenway Park as the first location to display is a reflection of the fact that Northeastern University is very close to Fenway Park.

We discuss query parameters in detail in:

Synchronized Google Maps Query Parameters