Google Maps PHP Library

Google introduced their Mapping Service with an Javascript API that lets you draw your own maps using their system. Coding maps dealing with big chunks of data in pure Javascript is a bit of a pain so a number of libraries came out making this easier.

• This was first mentioned on a blog posting on my personal site, please leave any comments you may have there. You can also subscribe to the blog's RSS feed to get news about new releases etc.

The most interesting of these libraries that I found is Google Maps EZ a simple bit of Javascript that takes HTML code, parses it and then do the hard work of talking to Google for you. This is great but not ideal yet for large chunks of data. I wrote a PHP library that will parse a config file and a XML data file to output the HTML for Google Maps EZ

The basic idea is to have data in a XML file that contains coordinates, text, images and hyperlinks rendered onto a Google Map. 1 point on a map would require only the following XML:

<points>
        <point>
                <lat>-33.9333</lat>
                <long>18.4667</long>
                <type>lived</type>
                <title>Cape Town</title>
                <comment>Lived here 1997 to 2002</comment>
                <country>South Africa</country>
                <href>http://flickr.com/photos/ripienaar/tags/capetown/</href>
                <linkimg>/visited/images/19591136_35a14f6d58_s.jpg</linkimg>
                <linemember>1</linemember>
        </point>
</points>

Using simple data like this you can put any number of pins on a map, in many colors with links to 3rd party data, a screenshot of such a map in action can be seen above. A full working sample of a map driven by this system can be seen on my Map of Places I visited

Since version 1.6 you can also draw lines on your maps by marking a point as belonging to a numbered line, line caractiristics like color, thickness and opacity can be set in the configuration file.

As this is a PHP script you'll need a working installation of PHP 4, it may work in PHP 5 but I have not tested it at all. You will also need the following:

• Google Maps API Key, these keys are tied to a URL, so if you want more than one instanse of the map you'll need a few of these keys.

• You should have PEAR::Config installed.

• GMaps PHP

PEAR::Config is a seperate package from Pear, even if you have Pear installed you should still install PEAR::Config in addition to just Pear.

Included in the tar ball is a XML parser written by Eric Pollmann that was released under the Public Domain. This wrapper is known to work in PHP 4 only, there are some suggestions on making it work in PHP 5 at http://uk.php.net/manual/en/function.array-merge.php

Simply extract the tar ball containing the source into any directory under your web root:

% cd public_html
% tar -xvzf gmapsphp-current.tgz
gmapsphp-1.2/
gmapsphp-1.2/XMLParser.php
gmapsphp-1.2/gmap.inc.php
gmapsphp-1.2/sample/
gmapsphp-1.2/sample/visited.xml
gmapsphp-1.2/sample/map.cfg
gmapsphp-1.2/sample/index.php
gmapsphp-1.2/README

% mv gmapsphp-1.2 mymap

The distribution comes with a working sample extracted into the sample dirctory.

You can copy the map.cfg from the sample to your mymap directory and edit it, the distributed sample can be seen below.

[map]
data = visited.xml
type = map
width = 800
height = 490
showcountry = 1
showtype = 0
divwidth = 250

[extends]
default = "http://maps.google.com/maps?ll=14.604847,57.656250&spn=127.829913,245.812500"
sengland = "http://maps.google.co.uk/maps?ll=51.733833,-1.713867&spn=3.471419,7.639893"

[controls]
mapctrl = 1
typectrl = 1
scalectrl = 1
size = large

[types]
visit = orange mini
transit = blue
lived = green

[line1]
color = #000000
width = 2
opacity = 0.6

[misc]
gmapez=http://bluweb.com/chouser/gmapez/gmapez-2.js
apikey="yourkey"

[map] section

[extends] section

An extend defines the coordinates of the map center and also the zoom level to show when you first load the map.

Since version 1.2 you can define multiple extends in the configuration file, this allows you to create multiple views of your map.

As an example using my visited places map you can either see the default view that shows most of the world or just South England. Same data, html, config etc, just different initial views of the map.

To get the extend url's you need to use Google Maps, open it in a browser and drag and zoom till you get the map to be how you want it to look on your own map, left double click in the center of the map. This will set the link in the top right called 'Link to this page' to the URL you need for the extend. Simply copy that URL and paste it into the configuration file as either default or a named value, you can add as many extends as you like in this manner.

• You may notice that your map does not look exactly as you thought it would while positioning it on the Google Maps page, this is probably due to the width and height of your map not being the same as the one displayed by Google Maps, you will need to use some trial and error to get it right.

[controls] section

On each Google Map you will notice there are various buttons you can interact with, these lets you choose map, satelite or highbrid view as well as let you control zoom level. The controls section in the configuration lets you control which of these to display and how large they should be displayed.

[types] section

As you will see later on the XML data file supports a type for each point, in the XML file you would simply have a word like visited or lived this would map to this section and instruct Google Maps which color pins to put for your points. For a list of supported colors refer to the GMaps EZ documentation. If you appent the word mini to any color like in the sample above the pin will be a much smaller pin that does not show any text on the pin itself, this is useful for maps with many markers.

There is one special type - none - using it in a point will prevent any comments or markers to be made at this point, it's only really useful when drawing lines. You should therefore consider the type none to be a reserved word and not try and define types matching that, they won't work.

[misc] section

At present the author of GMaps EZ would like you to just use the javascript and images served up from his server, this is not ideal and I've offered to help package the system up into a package that can be hosted by yourselves, until this is done though you can leave the gmapez URL on its default setting, once a versioned package is available you would change this to your own installation URL.

Add your own Google API Key in the apikey property.

[lineX] section

Lines can be drawn between points by using the <linemember> property of a point, simply assining all the points for a given line to the same line number will make a line appear between the points, in order that they are listed in the data file.

If you need to set special start and end points for your lines, simply create point types for those and set the start and end point to be of that type.

The data for the map gets read from a simple XML file, it can be anywhere on the file system where your webserver can read it, just make sure the config file points to the right location. A sample data file has been provided in the tar ball.

A sample single point map is shown below:

   <points>
        <point>
                <lat>-33.8667</lat>
                <long>151.2000</long>
                <type>visit</type>
                <title>Sydney</title>
                <country>Australia</country>
                <href>http://flickr.com/photos/ripienaar/tags/sydney/</href>
                <linkimg>/visited/images/19397064_a15dadd4cc_s.jpg</linkimg>
                <comment>Visited in 2000 and 2001</comment>
                <linemember>1</linemember>
        </point>
  <points>

This is pretty self explanatory at this point, I won't go into full detail of each bit of data, the only fancy thing here is linkimg and href these two are reliant on each other, it will show a image that you can click on to go to the URL. If you do not want a clickable image, you can use linktext instead of linkimg, this will give you a textual hyperlink.

The type links back to types created in the configuration file, there is a special type called none that will not make any clickable point, this is to enable line drawing between points without putting markers.

You can put many markers on the map, I've created a map with 2000 points and while it works on big computers it definitely runs into problems on smaller computers, you'll need to do some tests if you want to make really huge maps.

A reasonably good source for coordinates can be found at http://www.fallingrain.com/world/. You could also use the same method you used to get the extend URL's to find coordinates using Google Maps, just pull the coordinates out of the URLs you obtain.

The final part in making it all work is setting up a bit of HTML to call your map. In the samples directory is a provided PHP script that will do this for you, the important code is:

        require_once("gmap.inc.php");

        if (isSet($_GET['view'])) {
                print(getGMapEZ("map.cfg", $_GET['view']));
        } else {
                print(getGMapEZ("map.cfg"));
        }

This will allow you to call the PHP file with a view parameter that matches the names or you configured in your extends section in the configuration. Sample URL's from my own installation:

• Your HTML document that hosts the map must use <html xmlns:v="urn:schemas-microsoft-com:vml"> to prevent errors in Internet Explorer.

You could use mod_rewrite in Apache to make these URL's look nicer. A simple rule like the one below can redirect all requests to /yourmap/view/extendname to view the specific extend.

RewriteRule view/(.+) index.php?view=$1

Using this mod_rewrite rule you can view my South England map with the following url http://www.devco.net/visited/view/sengland