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.