May-7-2010 NOTE: this project has a new home at Google Code

DOWNLOAD:

GoogleMapAPI-2.5.tar.gz

ANONYMOUS CVS: (leave password empty)
    cvs -d :pserver:anonymous@cvs.phpinsider.com:/export/CVS login
    cvs -d :pserver:anonymous@cvs.phpinsider.com:/export/CVS checkout GoogleMapAPI

NEWS/CHANGES:

NEWS

DEMO:

demo

NAME:

    GoogleMapAPI - A library used for creating google maps.

AUTHOR:
    Monte Ohrt <monte [AT] ohrt [DOT] com>

LATEST VERSION:
    2.5 - Sep 20th, 2007

SYNOPSIS:

    <?php
    require('GoogleMapAPI.class.php');

    $map = new GoogleMapAPI('map');
    // setup database for geocode caching
    $map->setDSN('mysql://USER:PASS@localhost/GEOCODES');
    // enter YOUR Google Map Key
    $map->setAPIKey('YOURGOOGLEMAPKEY');
    
    // create some map markers
    $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
    $map->addMarkerByAddress('826 P St Lincoln NE 68502','Old Chicago','<b>Old Chicago</b>');
    $map->addMarkerByAddress('3457 Holdrege St Lincoln NE 68502',"Valentino's","<b>Valentino's</b>");
    ?>

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
    <head>
    <?php $map->printHeaderJS(); ?>
    <?php $map->printMapJS(); ?>
    <!-- necessary for google maps polyline drawing in IE -->
    <style type="text/css">
      v\:* {
        behavior:url(#default#VML);
      }
    </style>
    </head>
    <body onload="onLoad()">
    <table border=1>
    <tr><td>
    <?php $map->printMap(); ?>
    </td><td>
    <?php $map->printSidebar(); ?>
    </td></tr>
    </table>
    </body>
    </html>



OUTPUT:

    View the output of the above example here:

    http://www.phpinsider.com/php/code/GoogleMapAPI/demo/

    
DESCRIPTION:

    GoogleMapAPI - A library used for creating google maps using the
    Google Map public API. Features include multiple map markers, customizable
    icons, map directions built into info window, and sidebar generation.
    
    More information on the Google Map API can be found here:
    
    http://www.google.com/apis/maps/
    

DISCUSSION:
-----------

    Discussions are currently held in the Smarty add-on forum (although Smarty
    is not necessary to use GoogleMapAPI.)

    http://www.phpinsider.com/smarty-forum/viewforum.php?f=19
    

BASE CLASS METHODS:
-------------------

    GoogleMapAPI($map_id = 'map', $app_id = 'MyMapApp')
    ---------------------------------------------------
    
        Class Constructor.
        The map id is needed only if you have multiple maps on the same page.
        The App ID is used for the Yahoo GeoCode API, if you use Yahoo for lookups.
        Use a unique App ID per application.
        
        Example:
        
        // use defaults
        $map = new GoogleMapAPI();

        // set custom map id and app id
        $map = new GoogleMapAPI('mymap','myapp');


    setDSN($dsn)
    ------------
    
        Used to set the database DSN. The database is used to cache
        geocode lookups (highly recommended!) The PEAR::DB module
        is required for database access. You will need to create
        the following database schema (mysql example given):
        
        CREATE TABLE GEOCODES (
          address varchar(255) NOT NULL default '',
          lon float default NULL,
          lat float default NULL,
          PRIMARY KEY  (address)
        );
        
        Example:
        
        $map->setDSN('mysql://DBUSER:DBPASS@DBHOST/DBNAME');
        $map->setDSN('mysql://geo:foobar@localhost/GEOCODES');

    
    setAPIKey($key)
    ---------------
    
        Sets the Google Map API Key. This is mandatory, you will need
        an API Key for your hostname! You can register free here:
        
        http://www.google.com/apis/maps/signup.html

        Example:
        
        // enter YOUR registered API Key
        $map->setAPIKey('ABQIAAAAxp5FF-A0RhHOnnTBwrlRbx');


    setWidth($width)
    ----------------
    
        Sets the width of the map window. This can be either px or %.
        Default is 500px.
    
        Example:
        
        $map->setWidth('500px');
        $map->setWidth('100%');

    
    setHeight($height)
    ------------------
    
        Sets the height of the map window. This can be either px or %.
        Default is '500px'.
    
        Example:
        
        $map->setHeight('500px');
        $map->setHeight('100%');
        
        
    enableMapControls()
    -------------------
    
        This will enable the map controls to zoom/move around the map.
        Enabled by default.


    disableMapControls()
    --------------------
    
        This will disable the map controls to zoom/move around the map.
        Enabled by default.


    setZoomLevel()
    --------------
    
        This sets the default map zoom level.
        
        Example:
        
        $map->setZoomLevel(4);


    setControlSize($size)
    ---------------------
    
        This sets the map control size. Relevant only if map controls are
        enabled. large = map zoom/move with slider. small = zoom/move without
        slider. Large is default.
        
        Example:
        
        $map->setControlSize = 'small';


    enableTypeControls()
    --------------------
    
        This will enable the map type controls (map/satellite/hybrid).
        Enabled by default.


    disableTypeControls()
    ---------------------
    
        This will disable the map type controls (map/satellite/hybrid).
        Enabled by default.


    setMapType($type)
    -----------------
    
        This sets the default map type. Relevant only if map type controls are
        enabled. map = default map. satellite = satellite view. hybrid = hybrid
        view.
        
        Example:
        
        $map->setMapType('map'); // default
        $map->setMapType('satellite');
        $map->setMapType('hybrid');
        
        
    enableSidebar()
    ---------------
    
        This enables the map sidebar. Use printSideBar() or getSideBar() to
        output the sidebar text. Enabled by default.


    disableSidebar()
    ----------------
    
        This disables the map sidebar. Enabled by default.

    
    enableDirections()
    ------------------
    
        This enables map directions in the bottom of the pop-up info window.
        Enabled by default.        


    disableDirections()
    -------------------
    
        This disables map directions in the bottom of the pop-up info window.
        Enabled by default.

    enableZoomEncompass()
    ---------------------
    
        This enables zoom encompass so default map zoom is as small as possible
        and include all map markers.
        Enabled by Default.

    disableZoomEncompass()
    ----------------------
    
        This disables zoom encompass.
        Enabled by Default.        


    setBoundsFudge($val)
    --------------------
    
        Set the map boundary fudge factor. This will adjust how much map
        boundary encompasses the map markers. (0.01 is default.)
        
        Example:
        
        $map->setBoundsFudge(0.01);
        
        
    setBrowserAlert($message)
    -------------------------
    
        This sets the alert message that pops up when a browser is not
        compatible with the Google Map API. Default is:
        "Sorry, the Google Maps API is not compatible with this browser."
        
        
    setJSAlert($message)
    --------------------
    
        This sets the alert message that displays when javascript is disabled.
        Default: "<b>Javascript must be enabled in order to use Google Maps.</b>"
    
        
    enableOnLoad()
    --------------
    
        This enables the onLoad() javascript function, which is used by default.
        This allows the map javascript to be put into the <head></head> tag,
        then loaded upon page entry with either <body onload="onLoad()"> right
        in the body tag, or use printOnLoad() to place this elsewhere. With onLoad
        disabled, the map javascript must be embedded inside the <body></body>
        tags. Using onLoad() is the best method to use for browser
        compatability.


    enableInfoWindow()
    ------------------
    
        enables info windows on map markers.
        Enabled by default.
    

    disableInfoWindow()
    -------------------

        disables info windows on map markers.
        Enabled by default.


    enableScaleControl()
    --------------------
    
    enables the map scale.
    Enabled by default.
    

    disableScaleControl()
    ---------------------
    
    disables the map scale.
    Enabled by default.


    enableOverviewControl()
    -----------------------
    
    enables the map overview.
    Disabled by default.


    disableOverviewControl()
    ------------------------
    
    disable the map overview.
    Disabled by default.

        
    disableOnLoad()
    ---------------
    
        This disables the onLoad() javascript function. (see enableOnLoad())
        Enabled by default.
        
        
    setInfoWindowTrigger($type)
    ---------------------------
    
        This sets the info window trigger behavior. click = info window comes up
        when clicking on a marker. mouseover = info window comes up when mousing
        over a marker. Default is click.
        
        Example:
        
        $map->setInfoWindowTrigger('mouseover');
                
                
    addMarkerByAddress($address,$title = '',$html = '')
    ---------------------------------------------------
    
        This adds a marker to the map. The address must be a fully qualified
        address that can be used by the available geocode lookup services.
        
        To add markers with geocodes directly, see addMarkerByCoords().
        
        The title is used for the sidebar navigation link. The html is used
        in the info window that pops up when you click on the map marker. If
        no html is provided, the title will be used.
        
        Note: map centering is done automatically as markers are added.
        
        Note: You can use tabbed windows by passing an array of
            title=>text values as the $html parameter. If driving directions
            are enabled, they show up under the first tab.
                
        Example:
        
        $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
                
                
    addMarkerByCoords($lon,$lat,$title = '',$html = '')
    ---------------------------------------------------
    
        This adds a map marker by geocode (lon/lat) directly. See
        addMarkerByAddress() for more details.

        Example:
        
        $map->addMarkerByAddress(-96.6539,40.8191,'PJ Pizza','<b>PJ Pizza</b>');
        
    
   
    addPolyLineByAddress($address1,$address2,$color,$weight,$opacity)
    -----------------------------------------------------------------
    
        This adds a polyline between the two given addresses. You can optionally
        supply a color (in #ffffff hex notation), weight (thickness in pixels),
        and opacity (in percentage 0-100).
        
        Example:
        
        $map->addPolyLineByAddress(
            '3457 Holdrege St Lincoln NE 68502',
            '826 P St Lincoln NE 68502','#eeeeee',5,50);
                
        
    addPolyLineByCoords($lon1,$lat1,$lon2,$lat2,$color,$weight,$opacity)
    --------------------------------------------------------------------
    
        This adds a polyline between the two given geocoordinate points. You can optionally
        supply a color (in #ffffff hex notation), weight (line thickness in pixels),
        and opacity (in percentage 0-100).

        Example:
        
        $map->addPolyLineByCoords(-96.67,40.8279,-96.7095,40.8149,'#eeeeee',5,50);

                
    adjustCenterCoords($lon,$lat)
    -----------------------------
    
        This adjusts the map center coords by the given lon/lat. This is done
        automatically as you add markers to the map, or you can do it manually
        with this function. Note: this function is used internally by the
        library, it isn't normally necessary unless you have a specific need and
        you know what you are doing.

        
    setCenterCoords($lon,$lat)
    --------------------------
                
        This sets the map center coords to the given lon/lat. Center coords are
        calculated automatically as you add markers to the map, or you reset it
        manually with this function. Note: this function is used internally by
        the library, it isn't normally necessary unless you have a specific need
        and you know what you are doing.


    setLookupService('GOOGLE')
    -------------------------
                
        This sets the geocode lookup service. Default is GOOGLE, which uses the
        GOOGLE Geocode API. If you use the YAHOO Geocode API, be sure to set
        your application ID when instantiating GoogleMapAPI. NOTE: Yahoo API
        works only for US addresses (AFAIK).
    
    
    setMarkerIcon($iconImage,$iconShadowImage,$iconAnchorX,$iconAnchorY,$infoWindowAnchorX,$infoWindowAnchorY)
    ----------------------------------------------------------------------------------------------------------
    
        This sets the icon image for ALL the map markers. Call this once. If you
        want to set a different icon for each marker, use addMarkerIcon()
        instead.
        
        You must supply a separate image for the icon and its shadow.
        iconAnchorX/Y is the X/Y coordinates of the icon for the map point.
        infoWindowAnchorX/Y is the X/Y coordinates of the icon where the info
        window connects.
        
        The iconImage and iconShadowImage can be either fully qualified URLs, or
        a relative path from your web server DOCUMENT_ROOT. These images MUST
        exist and readable so the library can calculate the dimensions.
        
        Example:
        
        $map->setMarkerIcon('/images/house.png','/images/house_shadow.png',0,0,10,10);


    addMarkerIcon($iconImage,$iconShadowImage,$iconAnchorX,$iconAnchorY,$infoWindowAnchorX,$infoWindowAnchorY)
    ----------------------------------------------------------------------------------------------------------
    
        This sets the icon image for the CURRENT map marker. IMPORTANT: you MUST
        call addMarkerIcon() once for every marker. Do not use setMarkerIcon()
        if you use this function.
        
        You must supply a separate image for the icon and its shadow.
        iconAnchorX/Y is the X/Y coordinates of the icon for the map point.
        infoWindowAnchorX/Y is the X/Y coordinates of the icon where the info
        window connects.
        
        The iconImage and iconShadowImage can be either fully qualified URLs, or
        a relative path from your web server DOCUMENT_ROOT. These images MUST
        exist and readable so the library can calculate the dimensions.
        
        Example:
        
        $map->addMarkerIcon('/images/house.png','/images/house_shadow.png',0,0,10,10);


    printHeaderJS()
    ---------------

        This prints the header javascript that goes into the <head></head> tags.
        To return the header javascript in a variable, use getHeaderJS().
        
        Example:
        
        <head>
        <?php $map->printHeaderJS(); ?>
        </head>
    

    getHeaderJS()
    -------------
    
        This returns the header javascript that goes into the <head></head> tags.
        To print the header javascript directly, use printHeaderJS().
        
        Example:
        
        <?php
        $headerjs = getHeaderJS();
        ?>
        <head>
        <?php echo $headerjs; ?>
        </head>
        
        
    printMapJS()
    ------------

        This prints the map javascript. If onLoad() is enabled, put this in the
        <head></head> tags, and supply <body onload="onLoad()"> in the body tag
        (or use printOnLoad()).
        
        Otherwise, put this just before the </body> tag to make it load
        automatically. Note that using onLoad() is recommended over this method.
        
        To return the map javascript in a variable, use getMapJS().
        
        Example:
        
        <head>
        <?php $map->printMapJS(); ?>
        </head>
    
    
    getMapJS()
    ----------

        This returns the map javascript that goes into the <head></head> tags.
        To print the map javascript directly, use printMapJS().
        
        Example:
        
        <?php
        $mapjs = $map->printMapJS();
        ?>
        <head>
        <?php echo $mapjs; ?>
        </head>


    printOnLoad()
    -------------

        This prints the onLoad() javascript call. This is an alternate to
        using <body onload="onLoad()"> in the body tag. You can place
        this anywhere in the html body.
        
        To return the onLoad() javascript in a variable, use getOnLoad().
        
        Example:
        
        <head>
        <?php $map->printMapJS(); ?>
        </head>
        <body>
        <?php echo $map->printMap(); ?>
        <?php $map->printOnLoad(); ?>
        </body>
    
    
    getOnLoad()
    -----------

        This returns the map javascript that goes into the <head></head> tags.
        To print the map javascript directly, use printMapJS().
        
        Example:
        
        <?php
        $onload = $map->getOnLoad();
        $mapjs = $map->getMapJS();
        $map = $map->getMap();
        ?>
        <head>
        <?php echo $mapjs; ?>
        </head>
        <body>
        <?php echo $map; ?>
        <?php echo $onload; ?>
        </body>

        
        
    printMap()
    ----------

        This prints the map html.
        To return the map html in a variable, use getMap().
        
        Example:
        
        <head>
        <?php $map->printMapJS(); ?>
        </head>
        <body onload="onLoad()">
        <?php echo $map->printMap(); ?>
        </body>

        Example 2 (using printOnLoad):
        
        <head>
        <?php $map->printMapJS(); ?>
        </head>
        <body>
        <?php echo $map->printMap(); ?>
        <?php echo $map->printOnLoad(); ?>
        </body>

    
    
    getMap()
    --------

        This returns the map html in a variable.
        To print the map html directly, use printMap().
        
        Example:
        
        <?php
        $map = $map->getMap();
        ?>
        <body onload="onLoad()">
        <?php echo $map; ?>
        </body>


    printSidebar()
    --------------

        This prints the sidebar html.
        To return the sidebar html in a variable, use getSidebar().
        
        Example:
        
        <body onload="onLoad()">
        <table>
         <tr>
          <td>
           <?php $map->printMap(); ?>
          </td>
          <td>
           <?php $map->printSidebar(); ?>
          </td>
         </tr>
        </table>
        </body>
    
    
    getSidebar()
    ------------

        This returns the sidebar html in a variable.
        To print the sidbar html directly, use printSidebar().
        
        Example:
        
        <?php
        $map = $map->getMap();
        $sidebar = $map->getSidebar();
        ?>
        <body onload="onLoad()">
        <table>
         <tr>
          <td>
          <?php echo $map; ?>
          </td>
          <td>
           <?php echo $sidebar; ?>
          </td>
         </tr>
        </table>
        </body>
                
    
    getGeocode($address)
    --------------------
    
        This looks up the geocode of an address. It will use the database cache
        if available. If you want to lookup a geocode without using the database
        cache, use geoGetCoords(). Note: this function is used internally by the
        library, it isn't normally necessary unless you have a specific need and
        you know what you are doing.
        
        Example:
        
        $geocode = $map->getGeocode('237 S 70th suite 220 Lincoln NE 68510');
        
        echo $geocode['lat'];
        echo $geocode['lon'];
        
        
    getCache($address)
    ------------------
    
        This will get the cached geocode info for an address from the database
        cache, or return FALSE if nothing is available. Note: this function is
        used internally by the library, it isn't normally necessary unless you
        have a specific need and you know what you are doing.
        
        Example:
        
        $geocode = $map->getCache('237 S 70th suite 220 Lincoln NE 68510');
        
        echo $geocode['lat'];
        echo $geocode['lon'];
        

    putCache($address,$lon,$lat)
    ----------------------------
    
        This will insert geocode info for the given address into the database
        cache. Note: this function is used internally by the library, it isn't
        normally necessary unless you have a specific need and you know what you
        are doing.
        
        Example:
        
        $map->putCache('237 S 70th suite 220 Lincoln NE 68510',-96.62538,40.812438);
        

    geoGetCoords($address)
    ----------------------
    
        This looks up the geocode of an address directly (not from cache.) Note:
        this function is used internally by the library, it isn't normally
        necessary unless you have a specific need and you know what you are
        doing.
        
        Example:
        
        $geocode = $map->geoGetCoords('237 S 70th suite 220 Lincoln NE 68510');
        
        echo $geocode['lon'];
        echo $geocode['lat'];

    geoGetDistance($lat1,$lon1,$lat2,$lon2,$unit)
    ---------------------------------------------

        This gets the distance between too coordinate points using the great
        circle formula. $unit can be M (miles),K (kilometers),N (nautical
        miles),I (inches), or F (feet). Default is M.   
        
        Example:
        
        $distance = $map->geoGetDistance($lat1,$lon1,$lat2,$lon2,$unit);

        
        
INTEGRATING GOOGLE MAPS WITH SMARTY TEMPLATES
---------------------------------------------

    Integrating with Smarty is as simple as assigning the necessary vars to the
    template and then displaying them. Note: This example does not cover how to
    setup Smarty, please use the Smarty documentation.
    
    Example:
    
    <?php
    require('Smarty.class.php');
    require('GoogleMapAPI.class.php');

    $smarty = new Smarty();
    $map = new GoogleMapAPI();
    
    // setup database for geocode caching
    $map->setDSN('mysql://USER:PASS@localhost/GEOCODES');
    // enter YOUR Google Map Key
    $map->setAPIKey('YOURGOOGLEMAPKEY');
    
    // create some map markers
    $map->addMarkerByAddress('621 N 48th St # 6 Lincoln NE 68502','PJ Pizza','<b>PJ Pizza</b>');
    $map->addMarkerByAddress('826 P St Lincoln NE 68502','Old Chicago','<b>Old Chicago</b>');
    $map->addMarkerByAddress('3457 Holdrege St Lincoln NE 68502',"Valentino's","<b>Valentino's</b>");
    
    // assign Smarty variables;
    
    $smarty->assign('google_map_header',$map->getHeaderJS());
    $smarty->assign('google_map_js',$map->getMapJS());
    $smarty->assign('google_map_sidebar',$map->getSidebar());
    $smarty->assign('google_map',$map->getMap());
    
    // display the template
    $smarty->display('index.tpl');
    ?>
    
    contents of index.tpl:
    ----------------------
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
    <head>
    {$google_map_header}
    {$google_map_js}
    <!-- necessary for google maps polyline drawing in IE -->
    <style type="text/css">
      v\:* {ldelim}
        behavior:url(#default#VML);
     {rdelim} 
    </style>
    </head>
    <body onload="onLoad()">
    <table>
      <tr>
        <td>{$google_map}</td>
        <td>{$google_map_sidebar}</td>
      </tr>
    </table>
    </body>
    </html>


CREDITS:
--------

Excellent Google Maps tutorials by Mike:
http://www.econym.demon.co.uk/googlemaps/index.htm

People who have helped/contributed:

Charlie Dawes
Jake Krohn
Clark Freifeld <clark AT users DOT sourceforge DOT net>
Angelo Conforti
Jerome Combaz
drakos7 (from forums)
nmweb (from forums)

Anyone I missed, drop me a line!

Monte Ohrt <monte [AT] ohrt [DOT] com>

OTHER PROJECTS:

View Monte's other projects

To find a Cheap Web Hosting provider, we recommend this valuable resource.