Google Calendar Events

This is a WordPress plugin, which parses Google Calendar feeds and displays the events as a calendar grid or list on a page, post or widget. Events from multiple feeds can be displayed on one grid or list. You can specify how many events to retrieve, whether to retrieve past events and how long to cache the feed for, amongst other things. Grids can have AJAX functionality, which allows you to change the month, if required.

The calendar grid markup is generated using a modified version of the PHP Calendar script (2.3) by Keith Devens. As of version 0.2, tooltips are created using the jQuery tooltip plugin, qTip.

Don’t hesitate to let me know if you have any questions, problems, feedback etc. Leave a comment at the bottom of the page or contact me.

Jump to:


Visit the demo page to see what the plugin can do.


The current version is 0.7.2

You can download Google Calendar Events from the WordPress plugin directory page.


Either use the automatic installer from within your WordPress admin, or follow the below steps:

  • Download from the plugin repository
  • Extract the file
  • Copy the google-calendar-events directory to your WordPress plugins directory (probably wp-content/plugins)
  • Login to your WordPress admin, navigate to the Plugins section and activate Google Calendar Events
  • You should now see a new Google Calendar Events settings page under the Settings tab

Adding a Feed

Go to the Google Calendar Events settings page and click the Add Feed button. Here’s an explanation of the various fields:

  • Feed ID
    This is automatically assigned, it’s just a unique identifier.
  • Feed Title
    This can be whatever you like. Try to use something descriptive so that it will be easy to remember which feed is which (e.g. ‘Upcoming Club Events’ rather than ‘Feed 1′).
  • Feed URL
    This is the URLto the Google Calendar feed. It should be something like this: end of the URL may have /basic or /fullon the end, both should work ok.If you are using your own feed, you can find the URL by logging into Google Calendar then clicking on the calendar settings. In the Calendar Address section you should see an orange XML button, click on it to see your feed URL. Copy and paste the URL into the Feed URL field.
  • Retrieve events from
    The time at which to start retrieving events. Select one of the options from the drop-down box, and then specify an additional offset for the start time / date you require. The offset should be given in seconds (3600 seconds = 1 hour, 86400 seconds = 1 day), and can be negative.If you are using the ‘Specific date / time’ option, enter the UNIX timestamp for the date / time into the textbox. You can generate UNIX timestamps here.Take a look at this post for a few examples of how to use this option.
  • Retrieve events until
    The time at which to stop retrieving events.The instructions for the ‘Retrieve events from’ option (above) also apply here.
  • Maximum number of events to retrieve
    The maximum number of events to retrieve from the calendar feed. Due to caching and timezone issues, it is a good idea to set this to a higher number than you actually want to display. 5 to 10 higher should be fine in most cases. You can specify the exact number to display in the widget options or shortcode parameters.
  • Date format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General). Stick to just day / week / year formatting here, leave hours / minutes / seconds for the time format (below).
  • Time format
    A PHP date format string. Leave this empty to just use the default for your blog (in Settings > General).
  • Timezone adjustment
    If you are having problems with dates and times being shown incorrectly for your timezone, select your required timezone from the drop-down box.
  • Cache duration
    This is the length of time to keep the feed cached, in seconds (43200 seconds = 12 hours). You might want to reduce this value if your calendar updates very often but avoid setting it really low or page load times and calls to Google’s servers will be increased. If you want to update the feed cache ‘right now’ to check any events you have added to your Google Calendar, set this to 0, then refresh any page with the calendar on it. You should then set this back to a higher number.
  • Show multiple day events on each day?
    If checked, events that span multiple days will be shown on each day that they span. If unchecked, multi-day events will only be shown on their first day.

Display options

To control the information that is displayed for each event in the grid tooltip or list, you can use either the simple display options, or the event display builder. The event display builder is much more flexible than the simple display options.

The simple display options are described below. There is a separate, in-depth guide to the event display builder.

Simple Display Options

  • Display start time / date?
    Select how to display the start time and date for events from the drop-down box. You can also enter some text to be displayed before the start time / date in the textbox
  • Display end time / date?
    Same applies here.
  • Separator text / characters
    If you have chosen to display the time and date for either of the above two settings, you can specify the text / characters to separate the time and date here (include spaces).
  • Display location?
    If checked, the location of events will be displayed (if a location was set when the event was created). You can also enter some text to be displayed before the location in the textbox.
  • Display description?
    Same as the location, but you can also specify a maximum word count for the description text. This can prevent the tooltips / lists becoming very long if your events have lengthy descriptions.
  • Display link to event?
    If checked, a link will be displayed for each event, which links to the Google Calendar page for that event. You can also specify whether these links will open in a new window, and the link text to be displayed.

When you’re done, click the Add Feed button. You will be redirected back to the main plugin settings page and you should see your feed listed in the current feeds section.

Please note that Google Calendar feeds that you add should have public sharing enabled and have the ‘Share only my free/busy information (Hide details)’ checkbox unchecked (These settings are under ‘Share this Calendar’ in the Settings of your Google Calendar admin).

Event Display Builder Guide

The event display builder requires quite a lot of documentation, so has a page to itself! Please take a look at the event display builder guide.

Editing / Deleting Feeds

On the main plugin settings page, you should see Edit and Delete links for each feed you have added.

The Edit Feed screen is very similar to the Add Feed screen so should be fairly self explanatory by now.

On the Delete Feed screen, check that the feed displayed is the one you wish to delete, then click the Delete Feed button. Make sure that you remove or adjust any widgets or shortcodes etc. that used the feed you have just deleted or you may get errors.

Adding a Widget

You need to have added a feed before you can add a widget, see above for how to do that if you’re not sure. Also, your theme must be widget enabled. If it isn’t, try using one of the other methods explained below.

Once you have added a feed, go to the Widgets page of your WordPress admin (under Appearance) and do the following:

  • Drag the Google Calendar Events widget from the Available Widgets box into one of the widget areas on the right of the screen.
  • Click on the arrow on the right of the widget, you should see some options.
  • Enter the feeds IDs of the feeds you want to display in this widget as a comma separated list (e.g. 1, 2, 4). If you want to display all the feeds you have added, leave this blank.
  • Choose how to display the events from the drop-down-box.
  • Enter the number of events that you want to display in this widget (you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). Enter 0 to display all events that were retrieved.
  • Choose whether you want events to be displayed in ascending or descending order. This only applies to lists.
  • If you want to display a title on the top of the tooltip / each list item, tick the checkbox and enter your desired title text in the text field (can be empty).
  • Click the Save button.

Adding to a Post or Page

To add a calendar grid or list to a post of page, you can use the following shortcode:


It takes up to four different parameters:

  • id – The IDs of the feeds you want to display as a comma separated list (all feeds will be displayed if this is omitted).
  • type – Should be one of the following (defaults to gridif parameter is omitted):
    • list – Events displayed in a list
    • list-grouped – Events displayed in a list, grouped by date
    • grid – Events displayed in a calendar grid for the current month
    • ajax – Events displayed in a calendar grid, with the ability to change months via AJAX
  • title – Title text to be displayed on the top of the tooltip / list items (no title is shown if parameter is omitted).
  • max – The maximum number of events to display (again, you can’t display more than the number you specified in the ‘Maximum number of events to display’ option in the feed settings). All events retrieved will be displayed if set to 0, or if this parameter is omitted.
  • order – The order of events. This only applies to lists. Should be asc or desc (defaults to asc if this parameter is omitted).

So, for example, to display 10 events from feeds 1 and 3 in a AJAX enabled calendar grid with the tooltip title ‘Events on’, use the following:

[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]

You can also use the do_shortcode() function to add a grid or list anywhere in a theme / template, like this:

<?php echo do_shortcode( '[google-calendar-events id="1, 3" type="ajax" title="Events on" max="10"]' ); ?>

General Options

These are the options on the main plugin screen.

  • Custom stylesheet URL
    If you want to make changes to the default CSS styles, create a new stylesheet on your server (not in the google-calendar-events directory) and enter its URL into this textbox. The default stylesheet will be overwritten each time the plugin updates, so beware of editing it directly, you will lose your changes.
  • Add JavaScript to footer?
    If the AJAX functionality, or the tooltips don’t appear to work for your site, try ticking this checbox.
  • Loading text
    Enter the text to display when the calendar is loading during an AJAX request.
  • Error message
    Enter an error message to display to non-admin users if events cannot be displayed for any reason. Logged-in admin users will see different error messages indicating the cause of the error.
  • Optimise event retrieval?
    If enabled, the plugin will use an experimental parameter of the Google Data API, called fields. This feature can improve performance significantly as it allows the plugin to request only the information it requires. This means that there is less feed data to transfer and process. It is highly recommended that you leave this option enabled, however, as this is an experimental feature, Google could potentially remove or change it at any time.
  • Use old styles?
    In version 0.7, some changes were made to the default CSS stylesheet. Enabling this option will add another stylesheet that includes much of the stuff that was removed / changed. You should consider updating your custom stylesheet so that you don’t need this enabled. This option will be removed in a future version.

Notes for Google Apps Calendar Users

If you are using a feed from a Google Apps Calendar and are having issues getting things up and running, please take a look at the notes for Google Apps Calendar Users.

AJAX grids

A few things to remember about AJAX grids. This applies to both widgets and full page grids.

  • To have the ability to change month on a grid, you must use the AJAX versions of the grids. See the above sections for how to do this.
  • To change the month, click on the arrows that appear on either side of the grid title.
  • The arrows will only appear if there are more events to show in that direction. For example, if the grid is showing July and there are no events in August or beyond then the next month arrow will not show.
  • Each time you click on one of the arrows, the information is requested from the server, so will take a small amount of time to appear (generally a couple of seconds).

Frequently Asked Questions

For answers to commonly asked questions, please visit the FAQ page.

If the FAQ don’t help, please ask in the comments below, or send me an email.

Things to Note

  • The calendar grid uses the WordPress ‘Week starts on’ setting to determine on which day the grid will start. You can change this in Settings > General.
  • Only a very basic CSS stylesheet is included. The intention is that you will adjust the stylesheet to fit your theme.
  • Styles and JavaScript are added by wp_head() or wp_footer() (if the relevant option is enabled) so ensure that you theme uses these functions or you will need to add the CSS and JavaScript files manually.
  • The plugin is still very much under development so there may be rough edges. I would appreciate any feedback, including bug reports and requests for additional features. Leave a comment below or contact me. Thanks!

To Do

Things I hope to implement / improve at some point:

  • Allow event information to be displayed within calendar grid cells (not just in the tooltip)
  • Different groupings for the grouped list (week, month, year etc)
  • Better handling of feeds that contain only free / busy information
  • Only load JavaScript when needed on the page
  • Allow a month other than “this” month to be displayed initially for calendar grids (first month that has events?)
  • Convert feeds to a custom post type

Any other suggestions?


Several people have asked about making a donation to the continued development and support of the plugin, so I’ve finally got around to sorting it out! Any donations will go towards website hosting costs and stuff like that.

Donations are much appreciated, but please do not feel in any way obligated to donate! I develop and support the plugin because I enjoy doing so, not for any financial gain.

3,886 Responses

  1. Hi there Ross!

    Thanks a lot for this plugin, it has a lot of great features. Did you ever find a way to show the event title on the grid squares? I have a need for this asap if there is a way to do so. I still wish to have the tooltip enabled and need to be able to to back and forth between months.

    I know you are able to pull this info to display on the list view, so I would imagine there is a way to do so for the grid view.

    Let me know, thanks!


  2. Hi there Ross,

    Thanks for your work on this plug-in. I’m really glad to have multiple Google calendars pulling in across my site. I would like to be able to include a month heading to group together events occurring in the same month.

    Any hope of having this role out soon?


  3. Hello Ross

    Thanks for using the php calendar to create an awesome plug-in. I love the less is more approach.

    One problem, this is on a site that only has events during September/October each year. I think I can make this happen with a simple code change, but what file is specifying the month?



  4. I’m interested to know how widget 1 works. I’m assuming when you click on an arrow an Ajax request is sent to the server. Out of curiosity, what does the server return? Does it return data in xml format that it parsed by the client using JavaScript?


  5. Hi Ross, I’m getting:

    1 or more of your feeds could not be displayed. The following errors occurred:

    Feed 1: Some data was retrieved, but could not be parsed successfully. Please ensure your feed URL is correct.

    The feed being:
    Page I’m testing it on:

    Works via the Google iframe on this page:

    Any clue as to why?

  6. Hey Ross,

    I’m getting a four-hour difference in posted time to actual calendar time. I’ve looked for a “Set time zone” in the plugin/widget but can’t find one.

    Any ideas?


  7. I am getting the following message:
    “1 or more of your feeds could not be displayed. The following errors occurred:

    Feed 2: Access to this feed was denied (403). Please ensure you have public sharing enabled for your calendar.”

    Can you please help me.
    Thank you,

  8. Thanks for the great calendar. Absolutely love the simple layout.

    I have created a new stylesheet and have tried uploading it to several different places on my site to override the default and I still can not get it to work. Any suggestions on where in the directory to store?

    Also, is it possible to change the font type in the month header?

    Thank you in advance.

  9. Thanks it works awesome.
    I’m creating a site in Dutch and I started editing the .POT file with poedit.
    But I can’t seem to find how to change the names of months and days.
    And with it the letters in the upper section of the calendar. M till S.
    I hope you can help me.


  10. Hi there, first off, GREAT plugin! I was wondering if there is anyway to actually show the events on the calendar rather than just changing the font color of the date instead of showing them only in a tooltip. Basically just so that it looks a little more like the Google Calendar interface?

  11. Hi , i added events today between dates that are already present on the grouped list but they are not showing up when the page is refreshed ?

  12. Hi there Ross

    I hope that you are well.
    In regard to link:
    Really enjoy using this plugin, however after waking up this morning I found my Calenders gone and my widgets reporting errors of this nature:

    1 or more of your feeds could not be displayed. The following errors occurred:

    Feed 1: There are no HTTP transports available which can complete the requested request. Please ensure your feed URL is correct.

    Do you perhaps know what I could be doing incorrectly?


  13. Hi,
    First of all, great plugin. Thx alot (mate :) ).
    I would like to hide the widget completely if no events can be displayed, for whatever reason.
    I’m ok with php and css, so if you can give me some pointers I might figure it out myself. It shouldn’t be 2 hard, but it would be nice to know where to start. Help is highly appreceated.
    Thx again, sabu :)

  14. Hi Ross,

    I was a bit haste in sending my previous email to you; figured out what the problem was–I had multiple calendars and I had to just combine them all into one!

    Thanks for the great plugin; now need to figure out how to customize the style setting; will play around with it!



  15. HI Ross,

    When I display the calendar on a page as a grid; when it hovers over an event and shows the box of details–how do I customize how the info in the box looks w/the CSS? My main issue is that the “More details” link is currently the same colour as the bgcolor of the box and you don’t notice there is a link unless you hover over it and it switches to another colour.

    Do I have to use the Event Display Builder to customize it? b/c I see that it’s pulling certain styling away from the builder. I’m using the default css sheet for the most part, and I can’t see where I have to go to change this setting.

    Thanks so much!

  16. I’m trying to show a map for the event location, but it isn’t happening!

    [maps-link newwindow="true"]Click for map…[location][/maps-link]
    [if-location]Location: [location][/if-location]
    [link newwindow="true"]More details…[/link]

    I just get a link that says:

    The “Where” field in Google Calendar says “BECK THEATRE, Hayes” and Google’s link nails it perfectly.

    Have I missed something I have to do?

    Great plugin BTW, I was using Stout Google Calendar, but this is a great improvement over that!


  17. Hi Ross,

    How would I handel a calendar with events where the timezone varies? (e.g. the use case being for someone who travels and gives talks)

    Ideally I’d like the website to display the times in the timezone of where the event is happening, (not adjusted).

    The problem is 1) if I set the TZ on the event to the local time of the event locale, then the website’s time is wrong, 2) if I set TZ to the website’s local time, then anyone subscribed to the calendar will get the wrong time.

    Any ideas?

    Ps. Thx for the great plug-in!

  18. I love the interface of the plugin. It’s very well laid out. This is quite possibly one of the best laid out and constructed WordPress plugin that I’ve ever used. Keep up the good work, man!

  19. Hi Ross,
    thanks for this great plugin. I have one difficulty with it. When I display the calendar in the list-mode the description-part is not shown correctly. the text is only broken in the line breaks I did in google, so the text is only shown in a few single lines. Is there any possibility to have line-breaks in the text, that the complete text is shown on my page?
    Thank you in advance.

  20. Not sure if my question went through of not, but I’ve been trying to get the 2 different feeds to have two different BG colors of the calendar grid.

    I’ve tried:

    .gce-page-grid .gce-calendar .gce-has-events .gce-feed-2 { /* Table cells with events */
    background: #0f2045;


    .gce-feed-2 .gce-multiple { /* Feed 2 Color */
    background: #0f2045;

    And the color for feed 2 does not change from the default BG color. What am I missing? Thanks!

  21. Greetings! Your plugin is GREAT!

    I’ve noticed that multi-day events often will show as running one extra day. For example, if I do a Wednesday thru Friday event, it shows Saturday as the end day.

    Is there a fix for this?

  22. You can add the “event title” in these styles, including:

    ‘gce-today gce-today-has-events “event-title”‘ ??

    ‘gce-day-past’ . $event_title;

    ‘gce-day-future’ . $event_title;

    to apply styles to each date field.


  23. Hi Ross,

    Thank you for all your efforts to create and manage such a great calendar widget… awesome!

    ISSUE: Some of my users/viewers are not able to see the “Tool Tip” (Event Summary Pop Up) when they put their cursor over a day (with an event scheduled) in the calendar view ( I have ensured each of these users/viewers have updated Flash etc. Any thoughts on why this is?

    Any help would be greatly appreciated.



Leave a Reply