Automating Google Calendar with Python: Your Personal Digital Assistant

Are you tired of manually adding events to your Google Calendar, or perhaps you wish your calendar could do more than just sit there? What if you could teach your computer to manage your schedule for you, adding events, checking appointments, or even sending reminders, all with a simple script? Good news – you can!

In this blog post, we’re going to dive into the exciting world of automation by showing you how to programmatically interact with Google Calendar using Python. Don’t worry if you’re new to coding or automation; we’ll break down every step into easy-to-understand pieces. By the end, you’ll have the power to create a simple script that can read your upcoming events and even add new ones!

What is Google Calendar Automation?

At its core, automation means making a computer do tasks for you automatically, without needing your constant attention. When we talk about Google Calendar automation, we’re talking about writing code that can:

• Read events: Get a list of your upcoming appointments.
• Add events: Schedule new meetings or reminders.
• Update events: Change details of existing entries.
• Delete events: Remove old or canceled appointments.

Imagine never forgetting to add a recurring meeting or being able to quickly populate your calendar from a spreadsheet. That’s the power of automation!

Why Python for This Task?

Python is an incredibly popular and versatile programming language, especially loved for scripting and automation tasks. Here’s why it’s a great choice for this project:

• Simple Syntax: Python is known for its readability, making it easier for beginners to pick up.
• Rich Ecosystem: It has a vast collection of libraries (pre-written code) that extend its capabilities. For Google Calendar, there’s an official Google API client library that simplifies interaction.
• Cross-Platform: Python runs on Windows, macOS, and Linux, so your scripts will work almost anywhere.

What You’ll Need (Prerequisites)

Before we start, make sure you have a few things ready:

• A Google Account: This is essential as we’ll be accessing your Google Calendar.
• Python Installed: You’ll need Python 3 installed on your computer. If you don’t have it, visit python.org to download and install the latest version.
• Basic Command Line Knowledge: We’ll use your computer’s terminal or command prompt a little bit to install libraries and run scripts.
• A Text Editor: Any text editor (like VS Code, Sublime Text, Notepad++, or even basic Notepad) will work to write your Python code.

Step-by-Step Guide to Automating Google Calendar

Let’s get our hands dirty and set up everything needed to talk to Google Calendar!

Step 1: Enable the Google Calendar API

First, we need to tell Google that we want to use its Calendar service programmatically.

1. Go to the Google Cloud Console: console.cloud.google.com.
2. If it’s your first time, you might need to agree to the terms of service.
3. At the top of the page, click on the “Select a project” dropdown. If you don’t have a project, click “New Project”, give it a name (e.g., “My Calendar Automation”), and create it. Then select your new project.
4. Once your project is selected, in the search bar at the top, type “Google Calendar API” and select it from the results.

5. On the Google Calendar API page, click the “Enable” button.

   • Supplementary Explanation: What is an API?
     An API (Application Programming Interface) is like a menu at a restaurant. It tells you what you can order (what services you can ask for) and how to order it (how to format your request). In our case, the Google Calendar API allows our Python script to “order” actions like “add an event” or “list events” from Google Calendar.

Step 2: Create Credentials for Your Application

Now, we need to create a way for our Python script to prove it has permission to access your calendar. This is done using “credentials.”

1. After enabling the API, you should see an option to “Go to Credentials” or you can navigate there directly from the left-hand menu: APIs & Services > Credentials.
2. Click on “+ Create Credentials” and choose “OAuth client ID”.
3. If this is your first time, you might be asked to configure the OAuth consent screen.
   • Choose “External” for User Type and click “Create”.
   • Fill in the “App name” (e.g., “Calendar Automator”), “User support email”, and your “Developer contact information”. You can skip the “Scopes” section for now. Click “Save and Continue” until you reach the “Summary” page. Then, go back to “Credentials”.
4. Back in the “Create OAuth client ID” section:
   • For “Application type”, select “Desktop app”.
   • Give it a name (e.g., “CalendarDesktopClient”).
   • Click “Create”.
5. A pop-up will appear showing your client ID and client secret. Most importantly, click “Download JSON”.

6. Rename the downloaded file to credentials.json and place it in the same directory (folder) where you’ll save your Python script.

   • Supplementary Explanation: What is OAuth and Credentials?
     OAuth (Open Authorization) is a secure way to allow an application (like our Python script) to access your data (your Google Calendar) without giving it your username and password directly. Instead, it uses a temporary “token.”
     Credentials are the “keys” that your application uses to start the OAuth process with Google. The credentials.json file contains these keys, telling Google who your application is.

Step 3: Install the Google Client Library for Python

Now, let’s get the necessary Python libraries installed. These libraries contain all the pre-written code we need to interact with Google’s APIs.

Open your terminal or command prompt and run the following command:

pip install google-api-python-client google-auth-oauthlib google-auth-httplib2

• Supplementary Explanation: What is pip and Python Libraries?
  pip is Python’s package installer. It’s how you download and install additional Python code (called “packages” or “libraries”) created by other people.
  Python Libraries are collections of pre-written functions and modules that you can use in your own code. They save you a lot of time by providing ready-made solutions for common tasks, like talking to Google APIs.

Step 4: Write Your Python Code

Now for the fun part! Open your text editor and create a new file named calendar_automation.py (or anything you like, ending with .py) in the same folder as your credentials.json file.

Paste the following code into your file:

import datetime
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

SCOPES = ['https://www.googleapis.com/auth/calendar']

def authenticate_google_calendar():
    """Shows basic usage of the Google Calendar API.
    Prints the start and name of the next 10 events on the user's calendar.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    return build('calendar', 'v3', credentials=creds)

def list_upcoming_events(service, max_results=10):
    """Lists the next N events on the user's primary calendar."""
    try:
        now = datetime.datetime.utcnow().isoformat() + 'Z'  # 'Z' indicates UTC time
        print(f'Getting the next {max_results} upcoming events')
        events_result = service.events().list(calendarId='primary', timeMin=now,
                                              maxResults=max_results, singleEvents=True,
                                              orderBy='startTime').execute()
        events = events_result.get('items', [])

        if not events:
            print('No upcoming events found.')
            return

        for event in events:
            start = event['start'].get('dateTime', event['start'].get('date'))
            print(start, event['summary'])

    except HttpError as error:
        print(f'An error occurred: {error}')

def add_event(service, summary, description, start_time, end_time, timezone='America/Los_Angeles'):
    """Adds a new event to the user's primary calendar."""
    event = {
        'summary': summary,
        'description': description,
        'start': {
            'dateTime': start_time, # e.g., '2023-10-27T09:00:00-07:00'
            'timeZone': timezone,
        },
        'end': {
            'dateTime': end_time,   # e.g., '2023-10-27T10:00:00-07:00'
            'timeZone': timezone,
        },
    }

    try:
        event = service.events().insert(calendarId='primary', body=event).execute()
        print(f"Event created: {event.get('htmlLink')}")
    except HttpError as error:
        print(f'An error occurred: {error}')

if __name__ == '__main__':
    calendar_service = authenticate_google_calendar()

    print("\n--- Listing Upcoming Events ---")
    list_upcoming_events(calendar_service, max_results=5)

    print("\n--- Adding a New Event ---")
    # Example: Add an event for tomorrow, adjust times and dates as needed
    tomorrow = datetime.date.today() + datetime.timedelta(days=1)
    start_event_time = f"{tomorrow.isoformat()}T10:00:00-07:00" # Tomorrow at 10 AM PST
    end_event_time = f"{tomorrow.isoformat()}T11:00:00-07:00"   # Tomorrow at 11 AM PST

    add_event(calendar_service,
              summary='Automated Python Meeting',
              description='Discussing calendar automation project.',
              start_time=start_event_time,
              end_time=end_event_time,
              timezone='America/Los_Angeles') # Use your local timezone or UTC

Understanding the Code

Let’s break down what’s happening in this script:

• SCOPES: This variable tells Google what kind of access your script needs.
  • 'https://www.googleapis.com/auth/calendar.readonly' allows your script to only read events.
  • 'https://www.googleapis.com/auth/calendar' allows your script to read, add, update, and delete events. We’re using this broader scope for our examples. If you change this, remember to delete token.json so you can re-authenticate.
• authenticate_google_calendar() function: This is the heart of the authentication process.
  • It checks if you already have a token.json file (created after your first successful authentication). If yes, it uses those saved credentials.
  • If not, or if the credentials are expired, it uses your credentials.json to start an OAuth flow. This will open a browser window asking you to log into your Google account and grant permission to your application.
  • Once authorized, it saves the authentication token to token.json for future runs, so you don’t have to re-authenticate every time.
  • Finally, it builds a service object, which is what we use to actually make requests to the Google Calendar API.
• list_upcoming_events() function:
  • This function uses the service object to call the events().list() method of the Calendar API.
  • calendarId='primary' refers to your default Google Calendar.
  • timeMin=now ensures we only get events from now onwards.
  • maxResults=max_results limits the number of events displayed.
  • singleEvents=True expands recurring events into individual instances.
  • orderBy='startTime' sorts the events by their start time.
  • It then iterates through the retrieved events and prints their start time and summary.
• add_event() function:
  • This function demonstrates how to create a new event.
  • It constructs a dictionary (event) with all the necessary details like summary, description, start and end times, and timeZone.
  • It then calls service.events().insert() to add the event to your primary calendar.
  • The dateTime values need to be in RFC3339 format (e.g., 2023-10-27T10:00:00-07:00), which includes the full date, time, and timezone offset. datetime.datetime.isoformat() helps create this.
• if __name__ == '__main__':: This block runs when you execute the script. It calls our authentication function, then uses the calendar_service to list and add events.

Running Your Script

1. Save your calendar_automation.py file in the same directory as your credentials.json file.
2. Open your terminal or command prompt.
3. Navigate to the directory where you saved your files using the cd command (e.g., cd path/to/your/calendar_project).

4. Run the script using Python:

   bash
python calendar_automation.py

What Happens on the First Run?

• When you run the script for the very first time, your default web browser will open.
• It will ask you to sign into your Google account and grant permission for “Calendar Automator” (or whatever name you gave your OAuth consent screen) to access your Google Calendar.
• After you grant permission, the browser will likely display a message saying the authentication flow has completed. You can then close that browser tab.
• Back in your terminal, the script will continue, create a token.json file, and then proceed to list your upcoming events and add the example event.

For all subsequent runs, as long as token.json is valid, the browser window will not open, and the script will run directly!

Exploring Further

Congratulations! You’ve successfully automated Google Calendar with Python. This is just the beginning of what you can do:

• Delete Events: Explore the events().delete() method in the API documentation.
• Update Events: Look into events().update().
• Search for Events: Use more advanced query parameters with events().list().
• Create Recurring Events: The API supports complex recurrence rules.
• Integrate with Other Data: Imagine reading events from a spreadsheet, a database, or even an email and automatically adding them.

This skill opens up a world of possibilities for managing your time and tasks more efficiently. Keep experimenting, and happy automating!