[GAS Beginner Series #78] Get This Week’s Schedule in Bulk: List Sapporo Office Meeting Room Bookings with Calendar.getEvents()

In the previous lesson (Part 77), we learned how to use Calendar.createEvent() and createAllDayEvent() to automatically create regular events like “Monthly Report Meeting” and all-day events like “Office Anniversary” in Google Calendar. It was exciting to see events being populated into the calendar via code, wasn’t it?

Now that you know how to add events to a calendar, the next logical step is learning how to programmatically read, list, and organize existing events using Google Apps Script!

  • “When is Sapporo Office Meeting Room 1 available this week?”
  • “I want to export all meetings scheduled for this month into Google Sheets to share with the team!”
  • “I want to check for conflicting schedules and open time slots in bulk!”

That’s where Calendar.getEvents() comes into play!

With this method, you can retrieve all calendar events within a specified timeframe (e.g., this week, this entire month) all at once using your script.

In this tutorial, our practical project will be “listing reservation statuses for Sapporo Office Meeting Room 1.” We’ll walk through the basic syntax of getEvents(), how to iterate through fetched events with a loop, practical techniques for exporting calendar events to Google Sheets, and the common pitfalls beginners face. Let’s make it crystal clear!

1. What Is Calendar.getEvents()?

Calendar.getEvents() is a method called on a calendar object to retrieve all events occurring between a specified start time and end time in bulk.

Breaking Down the Syntax

In programming, we connect the target object and the action with a dot (.):

var events = calendar.getEvents(startTime, endTime);
  • calendar: The “calendar (planner)” object retrieved via CalendarApp.getCalendarById() or CalendarApp.getDefaultCalendar() that we covered in Part 76.
  • .getEvents(startTime, endTime): The instruction telling the calendar, “Collect and return all events from the start date/time (startTime) to the end date/time (endTime)!”

Think of It as a “Planner” and a “Box of Index Cards”

Let’s use an intuitive analogy to keep things simple:

  • Calendar = An entire planner notebook.
  • getEvents(startTime, endTime) = Opening the planner to “this week’s page” and collecting all sticky notes (events) posted there into a box.
  • Returned result (events) = An array (list) containing those event notes in sequential order.

Remember the “bento box (array)” metaphor from Part 7? When you run getEvents(), all the retrieved events (CalendarEvent objects) are neatly stored inside a single array.

Result (Array: events) Contents (Event Object) Key Getter Methods
events[0] (1st event) 10:00–11:00 “Sapporo Team Morning Standup” .getTitle(), .getStartTime()
events[1] (2nd event) 14:00–15:30 “New Product Planning Meeting” .getTitle(), .getStartTime()
events[2] (3rd event) 16:00–17:00 “Soup Curry Tour Planning” .getTitle(), .getStartTime()

In short, the golden rule of Calendar.getEvents() is: specify a timeframe (start and end), fetch events in bulk, and receive them as an array!

2. STEP 1: Preparation – Set Up the “Sapporo Office Meeting Room 1” Calendar and Test Events

Let’s prepare the environment before writing our GAS code.

Steps

  1. Open Google Calendar: Open Google Calendar in your web browser.
  2. Register sample events: Manually (or using the script from Part 77), add 3–4 test events over the next few days, such as:
    • Example 1: Sapporo Office Meeting Room 1: Weekly Progress Meeting
    • Example 2: Sapporo Team: Soup Curry Tasting Meeting
    • Example 3: Executive Monthly Report Meeting
  3. Create a new Google Spreadsheet: In Google Drive, create a new spreadsheet and name it “Sapporo Office Meeting Room Management”.
  4. Open the GAS script editor: In the spreadsheet menu, click Extensions > Apps Script.

Once the editor opens, you’re all set!

3. STEP 2: [Hands-on] How to Get This Week’s Room Schedule and Output to Logs

Now that everything is ready, let’s write a script that retrieves all events from today through the next 7 days and outputs them to the execution log.

1. Enter the Code

Clear any placeholder code in the editor, and copy and paste the following script:

function getSapporoRoomSchedule() {
  // ① Get your default calendar (or a specified calendar) - Review from Part 76
  var calendar = CalendarApp.getDefaultCalendar();
  
  // ② Set the search start time (today) and end time (7 days later)
  var now = new Date();
  var startTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
  var endTime = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 7, 23, 59, 59);
  
  // ③ Retrieve all events within the specified time range
  var events = calendar.getEvents(startTime, endTime);
  
  // ④ Log the total number of fetched events
  Logger.log("■ Total events retrieved: " + events.length);
  Logger.log("----------------------------------------------");
  
  // ⑤ Loop through each event to display title, start time, and end time
  for (var i = 0; i < events.length; i++) {
    var event = events[i]; // Extract the i-th event from the array
    
    var title = event.getTitle(); // Get the event title
    var start = Utilities.formatDate(event.getStartTime(), "JST", "yyyy/MM/dd HH:mm"); // Start time (Review from Part 29!)
    var end = Utilities.formatDate(event.getEndTime(), "JST", "HH:mm"); // End time
    
    // Output to log
    Logger.log("【Event " + (i + 1) + "】" + title);
    Logger.log("  Time: " + start + " - " + end);
  }
}

2. Line-by-Line Code Breakdown

Let’s break down the key points for beginners:

  • var now = new Date();
    Creates a JavaScript Date object representing the current date and time.
  • new Date(year, month, date, hours, minutes, seconds)
    Creates a Date object for a specific moment. Here, we build our search window from today at 00:00:00 (startTime) to 7 days from now at 23:59:59 (endTime).
  • var events = calendar.getEvents(startTime, endTime);
    The star of today’s lesson! Retrieves all events across those 7 days and stores them in the events array.
  • events.length
    Returns the number of events stored in the array.
  • for (var i = 0; i < events.length; i++) { ... }
    A standard loop to iterate through every event in the array.
    • events[i] extracts the i-th event card.
    • event.getTitle() gets the event title/summary.
    • event.getStartTime() and event.getEndTime() retrieve the start and end dates/times.
  • Utilities.formatDate(...)
    The date-formatting method learned in Part 29! It formats raw Date objects into user-friendly strings like “2026/09/27 10:00”.

3. Save and Run the Script

  1. Click the Save icon (floppy disk) at the top of the editor.
  2. Make sure the selected function is getSapporoRoomSchedule, then click Run.
  3. (Note: On the first run, Google will prompt you with an authorization screen requesting permission to access Google Calendar. Follow the prompts to grant access, just as we did in Part 2!)

4. Check the Execution Log

If you see output like this in the execution log at the bottom, congratulations! You succeeded!

Info    ■ Total events retrieved: 3
Info    ----------------------------------------------
Info    【Event 1】Sapporo Office Meeting Room 1: Weekly Progress Meeting
Info    Time: 2026/09/28 10:00 - 11:30
Info    【Event 2】Sapporo Team: Soup Curry Tasting Meeting
Info    Time: 2026/09/29 12:00 - 13:00
Info    【Event 3】Executive Monthly Report Meeting
Info    Time: 2026/10/01 15:00 - 16:30

All events registered on the calendar were cleanly fetched in bulk via code!

4. STEP 3: Level Up Your Workflow! 3 Practical Applications of getEvents()

Instead of just logging the schedule, here are three practical techniques you can apply to real-world business workflows.

Use Case 1: Exporting Events to Google Sheets (appendRow Integration)

One of the most frequent business needs is exporting Google Calendar events to Google Sheets for backups, logging, or reporting.

By combining this with Sheet.appendRow() (covered in Part 7), you can build an automated logging tool with minimal effort!

function exportScheduleToSpreadsheet() {
  var calendar = CalendarApp.getDefaultCalendar();
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  
  // Timeframe: Today at 00:00:00 to 7 days later at 23:59:59
  var now = new Date();
  var startTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
  var endTime = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 7, 23, 59, 59);
  
  // Fetch events
  var events = calendar.getEvents(startTime, endTime);
  
  // Append each event to the spreadsheet row by row (using appendRow from Part 7!)
  for (var i = 0; i < events.length; i++) {
    var event = events[i];
    
    var title = event.getTitle();
    var start = Utilities.formatDate(event.getStartTime(), "JST", "yyyy/MM/dd HH:mm");
    var end = Utilities.formatDate(event.getEndTime(), "JST", "yyyy/MM/dd HH:mm");
    var description = event.getDescription(); // Get event description/notes
    
    // Create a 1-row array and append to the end of the sheet!
    sheet.appendRow([title, start, end, description]);
  }
  
  Logger.log("Successfully exported calendar events to spreadsheet!");
}

Set this function on a time-driven trigger, and you can achieve total automation—like exporting meeting room bookings every Monday morning automatically!

Use Case 2: Filtering Events by Specific Keywords (Conditional Branching with if)

If you only want to filter meetings that include a specific term, like “Soup Curry”, use JavaScript’s indexOf() or includes() inside your loop:

for (var i = 0; i < events.length; i++) {
  var event = events[i];
  var title = event.getTitle();
  
  // Process only if the title contains "Soup Curry"
  if (title.indexOf("Soup Curry") !== -1) {
    Logger.log("★ Selected: " + title);
  }
}

Use Case 3: Searching Directly with the options Parameter

getEvents() also provides an advanced signature where you pass an options object as the third argument to search calendar events directly.

// Fetch only events matching the search keyword "Soup Curry" directly from the calendar
var events = calendar.getEvents(startTime, endTime, {search: 'Soup Curry'});

Using {search: 'keyword'} lets Google Calendar filter the events before returning them, which keeps your script clean and concise.

5. 5 Common Pitfalls Beginners Face and How to Fix Them

Here are five frequent errors developers encounter when using Calendar.getEvents(). Review these now so you don’t waste hours debugging!

Pitfall 1: Calling events.getTitle() Directly and Getting a TypeError

This is an extremely common beginner mistake!

// ✕ Incorrect: events is an Array, so event methods cannot be called on it directly!
var events = calendar.getEvents(startTime, endTime);
var title = events.getTitle(); 
// Error: TypeError: events.getTitle is not a function

[Explanation & Solution]

getEvents() returns a “box (array)” containing events. You cannot ask the box itself, “What is your title?”

Always retrieve individual event objects first—such as events[0] or events[i] inside a for loop—before calling .getTitle()!

Pitfall 2: Reversing Start and End Dates, Resulting in 0 Events

// ✕ Incorrect: The start date is set in the future relative to the end date
var startTime = new Date("2026/10/01");
var endTime = new Date("2026/09/01");

var events = calendar.getEvents(startTime, endTime); // Returns 0 events!

For getEvents(startTime, endTime), argument 1 must be the start (earlier time) and argument 2 must be the end (later time). If reversed, GAS will not throw an error; it simply returns an empty array (0 items), making it tricky to diagnose.

Pitfall 3: Forgetting That Date Object Months Are Zero-Indexed (0 = Jan, 11 = Dec)

In JavaScript’s new Date(year, month, day), months start from 0.

  • new Date(2026, 8, 1) ➡ September 1 (8 corresponds to September)
  • new Date(2026, 9, 1) ➡ October 1 (9 corresponds to October)

If you tried to get October events by setting month to 10 and ended up with November events instead, this zero-indexed month rule is the culprit!

Pitfall 4: Non-existent Calendar ID Throws Cannot read properties of null

When using CalendarApp.getCalendarById("ID") (from Part 76), mistyping the ID or lacking access permissions causes it to return null.

Calling .getEvents() on null triggers this error:

TypeError: Cannot read properties of null (reading 'getEvents')

Double-check your calendar ID, or test your code using CalendarApp.getDefaultCalendar() (your primary calendar) first.

Pitfall 5: All-Day Events Have an End Time of “00:00 the Next Day”

When retrieving an all-day event like “Office Anniversary”, Google Calendar records its end time as 00:00:00 of the following day, not 23:59:59 of the current day.

When building date comparisons or display logic, combine your checks with the event.isAllDayEvent() method for best results!

6. Summary and What’s Next

In this tutorial, we covered in depth how to use Calendar.getEvents() to retrieve calendar events in bulk for any specified time window.

Key Takeaways

  1. Calendar.getEvents(startTime, endTime) retrieves events within a timeframe as an array.
  2. Because the result is an array, iterate through it using a for loop to process individual events.
  3. Use getTitle(), getStartTime(), and getEndTime() to extract event details.
  4. Combine with Sheet.appendRow() to easily export calendar schedules directly to Google Sheets.

Once you master reading calendar schedules programmatically, you can build all sorts of automated workflows, from room availability checkers to automated weekly activity reports!

Now that we can read events, what if you want to automatically invite meeting attendees to them?

In the next lesson (Part 79), we’ll cover how to automatically invite Sapporo team members to events like the “Monthly Report Meeting” using CalendarEvent.addGuest()! See you next time!