Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage. See our recent announcement for more information about the new pricing changes for Google Maps API.
Events Manager Pro 2.6.4 introduced Google Static Maps as an option for displaying location maps on your site. Static Maps provide a great option for displaying customised maps of your location with a much higher free usage free usage limit compared to regular (dynamic) maps, and also provide multiple options to still give your users that great experience of viewing dynamic/interactive maps by clicking on them.
EMP also provides a caching mechanism which has several benefits including the ability to display relatively sized images, reduce page load times as well as your API usage quotas.
Setting Up Static Maps
1. Enable ‘Static Maps API’ Library
You will need to enable an additional API library called ‘Maps Static API’ in the same area you set up your Google API account, please refer to our Google Maps API setup instructions or Google’s official documentation.
2. Obtain Additional API Keys
Static Maps require additional API keys, which include a Signature and (optionally) Server key.
Signature keys are required, and will prevent users from using your API key to generate map images on their own site. To obtain a signature, visit the Static Maps API library page you just visited and enabled, and click the ‘URL Signing Secret’ tab. From there, you can enable and generate a new secret, which you will use in the next step.
Server keys are used if you will be making use of our caching feature, or if your maps are using relative sizes (for example if you use a location placeholder like #_LOCATIONMAP{100%,300}). To obtain a server key, you will create another API key as per our Google API setup instructions. Whilst optional, you should also restrict the key to the IP of your web server to prevent unauthorized use.
3. Select Static Maps Map Type
Once you’ve enabled the API and obtained the right keys, you will need to go to your Dashboard > Events > Settings > General (tab) > Google Maps and Location Services > Google Map Type and select ‘Static Maps’ as your map type. When you do this, you’ll see additional options appear, including two text inputs where you’ll introduce the keys you obtained in step 2 above.
4. Set up additional options
At this point, static maps will work and will simply show a static image. If you have defined any map styling these styles will also be applied to static maps.
You can also define click actions and enable caching, which we’ll cover in the following sections.
Click Actions & Hover Text
Static maps are simply images, compared to dynamic maps which allow you to zoom and move around the map to see further surroundings. However, loading dynamic maps can be costly and unnecessary when a large portion of users will likely never interact with the map. Click actions for static maps provide that balance to provide a great user experience whilst providing optimal API quota usage.
When Static Maps are enabled (as per instructions above) in your settings page, you will see a ‘Map click action’ dropdown in the ‘Static Maps Options’ section, allowing you to choose additional actions when the static map image is clicked on. If you choose a click action, when a user hovers over a map image, the ‘Static hover text’ will show over the map and one of the following actions will occur when clicked on:
Link to google.com options
A new tab will open and will load a map on google.com. There is no API usage cost with this option, and produce the same results as covered by embedded maps map type, along with the related downsides regarding lack of customization.
Load dynamic map
A dynamic map will replace the static image, which will look somewhat seamless maintaining the same style and aspect as your static image. This is the most professional-looking option, and by loading static images first you’ve optimized your API usage of dynamic maps preventing them from being consumed unnecessarily for site visitors who don’t intend to use it.
Load embedded map
Similar to the dynamic map option, clicking on the static image will replace it with an embedded map with the same dimensions. Embedded maps have no usage quota but come with the downside of lacking customization.
Static Caching
Static map caching will enable you to serve images directly from your own server, which are cached for the amount of days you choose. Aside from the obvious benefit of reduced API usage, there is also a significant performance advantage: Optimized loading times.
Google Static Maps will load slower, especially when loading dynamically sized images. This is due to the URL signing requirement, which can only be done server-side. With dynamic image sizing, such as loading a map that is 100% the width of your page, the width can only be calculated in Javascript once the page is loaded. At this point, we must request an image from the server running Events Manager with the specific dimensions so it can be signed with your API key and secret. This process requires a certain amount of processing and slows down loading time, which is why caching is beneficial.
Cache Expiry and Adhering to Google’s Terms of Service
In order to adhere to Google’s TOS you must not keep images stored for more than 30 days, therefore it’s recommended you set the ‘Static map cache expiry days’ to a value of less than 30 days. When enabled, images older than x days according to your settings will be deleted on a daily basis from your google maps images folder.
Google has strict rules about caching and defines it in their Terms of Service – Section 10.5 d:
No caching or storage. You will not pre-fetch, cache, index, or store any Content to be used outside the Service, except that you may store limited amounts of Content solely for the purpose of improving the performance of your Maps API Implementation due to network latency (and not for the purpose of preventing Google from accurately tracking usage), and only if such storage:
- is temporary (and in no event more than 30 calendar days);
- is secure;
- does not manipulate or aggregate any part of the Content or Service; and
- does not modify attribution in any way.
Caching for our purposes, however, will adhere to these requirements, as the main reason for this is to improve performance and the map content is not modified in any way.
Troubleshooting Caching
If you have enabled caching, it should work automatically. However, if you find that your images are not loading correctly or are loading slowly, please verify that your site is correctly creating a cache folder to save images and has permission to write to the /wp-content/uploads/events-manager/static-gmaps/ folder (create one if necessary).
You can also verify your file permissions are correct by trying to upload a file via the WordPress Media section, which uses the same folder Events Manager caches files to.