Formatting Google Calendar Links With Timezones and PHP Carbon

Add Timezones to Google Calendar Links

Add Timezones to Google Calendar Links

Google has an undocumented means of linking a user to create an event on their calendar. It’s pretty simple once you figure out the parameters:

https://calendar.google.com/calendar/render?action=TEMPLATE&text=Hey, Timezone Me Google

And here is an example of a timezone being set:

https://calendar.google.com/calendar/render?action=TEMPLATE&text=Hey, Timezone Me Google&details=Please set timezones for us.&location=Phoenix+AZ+85004&dates=20170817T160000/20170819T160000&ctz=Africa/Abidjan&sf=true&output=xml#eventpage_6

Like all good undocumented features, hitting a snag means great difficulty in finding a solution. This is the case with timezones.

Set Calendar Link Timezone

A great resource for getting started in the event parameters is this StackOverflow post. Unfortunately, when the user clicks through even after setting the timezone, no timezone is specified.

After some long digging in Google Product forums, someone else found that you could set the timezone with another undocumented parameter, ctz, which specifies the timezone name. In itself, specifying this won’t set the timezone. I found that you have to specify both the ctz and send Google the timezone-formatted date.

This is pretty easy to do with PHP Carbon. The function below is an example of a method you might put on an Event model.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
    public function getGoogleCalendarLink()
    {
        // Get your start & end date
        // The start and end date below are Carbon objects
        $startDate = $this->start_date;
        $endDate   = $this->end_date;
 
        // Set your timezone if it is set
        if ($this->timezone) {
            $startDate = $startDate->setTimezone($this->timezone);
            $endDate = $endDate->setTimezone($this->timezone);
        }
 
        // Create the full calendar link
        $queryString = sprintf(
            'action=%s&text=%s&details=%s&location=%s&dates=%s/%s&ctz=%s',
            // action
            'TEMPLATE',
            // text
            urlencode($this->title),
            // details
            urlencode(strip_tags($this->description)),
            // location
            urlencode($this->address),
            // dates
            urlencode($startDate->format("Ymd\THis")),
            urlencode($endDate->format("Ymd\THis")),
            // ctz
            urlencode($startDate->timezoneName)
        );
 
        return 'https://www.google.com/calendar/event?' . $queryString;
    }
    public function getGoogleCalendarLink()
    {
        // Get your start & end date
        // The start and end date below are Carbon objects
        $startDate = $this->start_date;
        $endDate   = $this->end_date;

        // Set your timezone if it is set
        if ($this->timezone) {
            $startDate = $startDate->setTimezone($this->timezone);
            $endDate = $endDate->setTimezone($this->timezone);
        }

        // Create the full calendar link
        $queryString = sprintf(
            'action=%s&text=%s&details=%s&location=%s&dates=%s/%s&ctz=%s',
            // action
            'TEMPLATE',
            // text
            urlencode($this->title),
            // details
            urlencode(strip_tags($this->description)),
            // location
            urlencode($this->address),
            // dates
            urlencode($startDate->format("Ymd\THis")),
            urlencode($endDate->format("Ymd\THis")),
            // ctz
            urlencode($startDate->timezoneName)
        );

        return 'https://www.google.com/calendar/event?' . $queryString;
    }

Calendar Parameters

The full list of calendar parameters is below. If you have more to add please comment and let me know:

Parameter Description
action I haven’t seen a deviation from the value TEMPLATE.
text The title field for the event.
details The description field for the event.
location The event location.
dates Both dates, formatted with a timezone if present, and separated by a slash.
ctz The timezone name to set. Must also set the timezone in the date for it to work.

Hopefully that saves you the time I spent. Cheers!

Discussion

Leave a Reply