The Google Maps Plugin
Plugin Name: googlemaps
Purpose: To display event locations on a map. This plugin can display a map location for a single event (event display) or for a group of events (monthly, weekly, upcoming and static list of events display). Users can also optionally search for events near their location. Features of this plugin include:
- Bulk geocoding of events
- Search events near your location
- Driving directions support
- Color coded icons based on category color
- Custom styles for map display
- Display map for events that occur on a particular day, week or month
- Compatible with category chooser, show map locations by category
- Ability to move map pin manually to fine-tune location
- Google Maps v3 API support
- My Location: utilize browser location feature in HTML 5
- Category icons: Maps can now display either category icons or the standard pin icons
Version 3.1 and above of the Google Maps plugin uses the Google Maps version 3 API. Plugin versions earlier than 3.1 use an API no longer supported by Google will no longer work.
If you have not done so yet, sign up for a Google account and get a Google Maps API key from this URL (note: the URL has changed) : http://code.google.com/apis/console . From the services menu, enable the "Google Maps API v3" option. You will need the Google API key to insert into the Google Maps plugin. This key can be found the "API Access" menu option. More information about obtaining a Google API key can be found here:
Your key can be found in the "API Access" menu option from Google's API console. To use this key on multiple sites, enter each site where the plugin will be installed in the "Edit allowed referers". Once you obtain the key, go to Joomla Plugin Manager on your site and edit the Google Maps plugin (under the zapcalendar folder). Enter your API code here.
Completing the Installation (Zap Calendar Version 3.x Only)
After enabling the plugin and entering the API key, you will need to go to the Zap Calendar control panel in the back-end to complete the installation. From the panel, click the "Complete Install" (you may not see this option when upgrading from a previous version).
The map display is controlled from a Zap Calendar view's plugin settings. Use the plugin settings to enable the plugin. When viewing a single event, no map is displayed if the event does not have a location specified. The pin color of the event is based on the event's category. If an event belongs to more than one category, the first category's color will be used.
The plugin automatically converts locations to latitude/longitude coordinates. When creating a new event, the plugin settings allow for an alternate location to be used for lat/long purposes. For example, the location McDonald's" by itself will not be locatable due do the many possible locations; however, an alternate address can be entered to determine lat/long coordinates while still keeping the location description as "McDonald's". If the geocoded position is not correct, the pin on the map can be dragged to the correct position.
Proximity searching is also enabled in the view's plugin settings. Set the units (kilometers or miles) and up to three distances to search. For example, if units are set to kilometers and the distances 50, 100, and 200 are entered, this will allow users to search for events up to 50 km, 100 km and 200 km within their location, respectively. Distances are based on a straight line calculation and not driving distance.
Geocoding is the term used to convert a street address to a latitude/longitude coordinate. Bulk geocoding can occur when importing many events from an icalendar or CSV import, which may have a street address but will not have a latitude/longitude location. It can also occur when installing the Google Maps plugin into an existing calendar that already contains events.
In order to perform bulk geocoding, the Google Maps API geocoding limit must be raised. By default, one geocoding per second is the maximum. This limit can be raised to increase the number of geocodings per second. A rate of 10 per second is the recommended value for this setting with Zap Calendar. This can be updated under the Quotas section in the Google API console. This rate can be modified for both v2 and v3 API's.
Bulk geocoding is done automatically in the back-ground when a user browses the monthly or weekly calendar. The map will populate automatically when new locations are found and geocoded. It may take a few map refreshes to see all the map locations in a month view.
Google allows up to 2,500 geocodings and 25,000 map views per day per website without charge. Higher maximums will require contacting Google for a license. If you have installed a Google Maps API key, you can monitor your site's quotas at the API console.
Only one map can be displayed per page. The map will not be displayed if several Zap Calendar modules are being used on the same page with the Google Maps plugin enabled. Disable the Google Maps plugins from these modules/views so that only one view on the page has it enabled.
Events with the same location will have overlapping markers, however, only one of the markers will be clickable.
The plugin automatically converts locations to latitude/longitude coordinates and caches them as it finds them. These locations may not appear on the map the first time they are found, but will be displayed in subsequent map displays. When importing events, it may be useful to page through the monthly map to allow the plugin to cache these new locations.
Occasionally, the locations are not automatically geocoded for various reasons. You can display these "missing" locations from the Tools menu in Zap Calendar 4 or the Admin Tools area in Zap Calendar 3 for manual geocoding.