[GAS Beginner Series #29] Format Dates and Times Easily: How to Use Utilities.formatDate() and Format Patterns

Have you ever run into this frustrating issue while working with dates and times in Google Apps Script (GAS)?

You try to get the current date and time when your program runs, output it to the execution log, or write it into a Google Spreadsheet or email—only to be greeted by a super-long, messy raw string like Thu Jan 29 2026 14:30:00 GMT+0900 (Japan Standard Time).

What instantly turns this clunky, hard-to-read date data into clean, readable formats we use every day—like “2026/01/29” or “January 29, 2026 (Thu) 14:30”—is the star of this guide: Utilities.formatDate()!

In this complete tutorial, we will thoroughly explain Utilities.formatDate(), the most essential GAS method for customizing date and time formatting. We will cover basic syntax, 2-digit years, Japanese eras, English day/month names, traditional lunar calendar month names, and common timezone pitfalls so you can master date formatting in your automation workflows!

1. What Is Utilities.formatDate() in Google Apps Script?

Utilities.formatDate() is a built-in method in Google Apps Script that formats and converts a raw Date object into a string using a specified pattern and timezone.

Breaking Down the Syntax

It might look a bit intimidating at first, but once you break down the parts, the structure is very intuitive.

Utilities.formatDate(date, timeZone, format)
  • Utilities: Think of this as a handy utility toolbox packed with helpful helper features in GAS (date conversions, encryption, file compression, etc.).
  • .formatDate(): A specific command (method) inside that toolbox that says, “Please reformat this date into the style I want!”

Think of It as a “Translator”

When you retrieve a date using new Date() in GAS, you get a “Date object (raw data)” that is easy for computers to process, but looks like an untranslated foreign language to humans.

Utilities.formatDate() acts like an expert translator that converts raw timestamp data into clean, readable text tailored to whatever custom style you require.

As we saw when learning getValue() in Episode 5, setValue() in Episode 6, and appendRow() in Episode 7, inserting this “translation” step before outputting date values to spreadsheets, emails, or Google Calendar allows you to build clean, professional automated workflows that anyone can understand at a glance!

2. Basic Syntax and the 3 Core Arguments

When calling Utilities.formatDate(), you pass in three essential arguments inside the parentheses in exact order.

var formattedDate = Utilities.formatDate(dateData, timeZone, formatPattern);

Let’s review the role of each argument carefully.

Argument PositionParameter NamePurpose and Value to SpecifyConcrete Example
1st ArgumentdateThe original date data to convert (Date object)new Date() or a date retrieved from a cell
2nd ArgumenttimeZoneThe reference standard time zone to use for calculation"Asia/Tokyo" or Session.getScriptTimeZone()
3rd ArgumentformatThe rule or pattern specifying how it should look"yyyy/MM/dd HH:mm:ss", etc.

3. STEP 1: [Hands-on] Reformatting January 29, 2026 into a Clean Date String

Seeing is believing! Let’s write some code and test it out.

We will create a baseline timestamp for January 29, 2026, at 14:30:00, and convert it into a clean “2026/01/29 14:30:00” string.

1. Enter the Code

From the Google Sheets menu, navigate to Extensions > Apps Script, and paste in the following script. We will output the results to the execution log using Logger.log(), which we covered in Episode 1.

function formatMyDate() {
  // 1. Prepare the baseline date data (Jan 29, 2026 14:30:00)
  // *Note: In JavaScript, months are zero-indexed (0 = Jan, 1 = Feb), so use 0 for January
  var targetDate = new Date(2026, 0, 29, 14, 30, 0);
  
  // 2. Set the timezone (Japan Standard Time)
  var timeZone = "Asia/Tokyo";
  
  // 3. Define the formatting pattern
  var pattern = "yyyy/MM/dd HH:mm:ss";
  
  // 4. Format cleanly with Utilities.formatDate!
  var result = Utilities.formatDate(targetDate, timeZone, pattern);
  
  // 5. Output the results to the log
  Logger.log("Raw data before conversion: " + targetDate);
  Logger.log("Clean data after conversion: " + result);
}

2. Check the Execution Log

Save the script and run formatMyDate! If your Execution log at the bottom displays the following lines, you have succeeded.

Info	Raw data before conversion: Thu Jan 29 2026 14:30:00 GMT+0900 (Japan Standard Time)
Info	Clean data after conversion: 2026/01/29 14:30:00

The cluttered raw Date representation has been neatly transformed into crisp, concise “2026/01/29 14:30:00” text!

4. STEP 2: Complete Guide to Date Format Pattern Symbols

Mastering the pattern symbols (letters) used in the 3rd argument of Utilities.formatDate() gives you unlimited control over your date representations.

Here, we will cover everything from standard patterns to frequently requested variants like 2-digit years, Japanese eras, English weekdays, English month names, and traditional Japanese month names (such as Yayoi or Uzuki)!

1. Year Formatting: 4-Digit vs. 2-Digit Year

To represent years, use yyyy for a 4-digit year, or yy for a 2-digit year showing only the last two digits.

Pattern SymbolDescriptionOutput Example (Jan 29, 2026)
yyyyFull year (4 digits)2026
yyLast 2 digits of the year26

Code Example: Using 2-Digit Year Notation

function formatYearExamples() {
  var targetDate = new Date(2026, 0, 29); // January 29, 2026
  var timeZone = "Asia/Tokyo";

  // 1. Standard 4-digit year
  var y4 = Utilities.formatDate(targetDate, timeZone, "yyyy/MM/dd");
  // ➡ 2026/01/29

  // 2. Compact 2-digit year
  var y2 = Utilities.formatDate(targetDate, timeZone, "yy/MM/dd");
  // ➡ 26/01/29
  
  Logger.log("4-digit year: " + y4);
  Logger.log("2-digit year: " + y2);
}

💡 Practical Tip: Outputting Japanese Eras (Reiwa, Heisei, etc.)

If you need to output Japanese era dates like “Reiwa 8” (令和8年), relying on default pattern tokens like G often outputs Western era markers such as AD26 due to language environments, which is unreliable in production. A custom helper function is the most robust, battle-tested approach. Below is a practical function that handles all eras since the Meiji period and converts year 1 to “Gannen” (元年).

// Pass a Date object and receive a Japanese era string (e.g., Reiwa 8)
function toJapaneseEra(dateObj) {
  var year = dateObj.getFullYear();
  var month = dateObj.getMonth() + 1;
  var day = dateObj.getDate();
  
  // Convert date into a YYYYMMDD number (e.g., 20260129) for easy comparison
  var dateNumber = year * 10000 + month * 100 + day;

  var eraName = "";
  var eraYear = 0;

  // Determine era based on start dates (YYYYMMDD)
  if (dateNumber >= 20190501) {
    eraName = "令和";
    eraYear = year - 2018;
  } else if (dateNumber >= 19890108) {
    eraName = "平成";
    eraYear = year - 1988;
  } else if (dateNumber >= 19261225) {
    eraName = "昭和";
    eraYear = year - 1925;
  } else if (dateNumber >= 19120730) {
    eraName = "大正";
    eraYear = year - 1911;
  } else if (dateNumber >= 18680125) { // Meiji reference start date
    eraName = "明治";
    eraYear = year - 1867;
  } else {
    return "Pre-Meiji"; // Dates before Meiji are excluded
  }

  // Treat the first year as 'Gannen' (元年)
  var eraYearStr = (eraYear === 1) ? "元" : eraYear;
  
  return eraName + eraYearStr + "年";
}

By pairing this helper function for the Japanese era year with Utilities.formatDate() for the month and day, you get a completely bug-free Japanese date string!

// Example in action
function testEra() {
  var targetDate = new Date(2026, 0, 29); // January 29, 2026
  
  // Generate 'Reiwa 8' with the helper, and '01/29' with Utilities.formatDate
  var eraText = toJapaneseEra(targetDate);
  var mdText = Utilities.formatDate(targetDate, "Asia/Tokyo", "MM月dd日");
  
  Logger.log("Japanese Era output: " + eraText + mdText);
  // ➡ Execution log: Japanese Era output: 令和8年01月29日
}

2. Month Formatting: Numbers, Abbreviations, Full Names, and Traditional Month Names

The month symbol must always be an uppercase M (be careful: lowercase m represents minutes!).

Pattern SymbolDescriptionJanuary (Jan)March (Mar)April (Apr)
MM2-digit number (zero-padded)010304
M1- to 2-digit number134
MMMEnglish 3-letter abbreviationJanMarApr
MMMMEnglish full month nameJanuaryMarchApril

Code Example: Formatting English Month Names (March, April / Mar, Apr)

When generating international reports or web dashboards, you often need English month representations like “March” or “Mar”.

function formatEnglishMonths() {
  var dateJan = new Date(2026, 0, 29); // Jan 29
  var dateMar = new Date(2026, 2, 15); // Mar 15
  var dateApr = new Date(2026, 3, 10); // Apr 10
  var tz = "Asia/Tokyo";

  // 3-letter abbreviation (MMM): Jan, Mar, Apr
  Logger.log("Jan (short): " + Utilities.formatDate(dateJan, tz, "MMM dd, yyyy")); // Jan 29, 2026
  Logger.log("Mar (short): " + Utilities.formatDate(dateMar, tz, "MMM dd, yyyy")); // Mar 15, 2026
  Logger.log("Apr (short): " + Utilities.formatDate(dateApr, tz, "MMM dd, yyyy")); // Apr 10, 2026

  // Full spelling (MMMM): January, March, April
  Logger.log("Mar (full): " + Utilities.formatDate(dateMar, tz, "MMMM dd, yyyy")); // March 15, 2026
  Logger.log("Apr (full): " + Utilities.formatDate(dateApr, tz, "MMMM dd, yyyy")); // April 10, 2026
}

Technique: Generating Traditional Japanese Month Names (Yayoi, Uzuki, etc.)

If you are building seasonal event trackers or themed newsletters, you might want to display classical Japanese lunar month names (和風月名) like “Yayoi” (弥生) or “Uzuki” (卯月).

While Utilities.formatDate() does not have a native token for these names, mapping an array of strings in GAS solves this elegantly!

function formatWafuMonth() {
  var targetDate = new Date(2026, 2, 15); // March 15, 2026
  
  // Array of 12 traditional Japanese month names
  var wafuMonths = [
    "睦月", "如月", "弥生", "卯月", "皐月", "水無月",
    "文月", "葉月", "長月", "神無月", "霜月", "師走"
  ];
  
  // Get month index (0 to 11) using targetDate.getMonth()
  var monthIndex = targetDate.getMonth(); 
  var wafuName = wafuMonths[monthIndex]; // For March (index 2), this returns 'Yayoi' (弥生)
  
  // Format the remaining day part using Utilities.formatDate and combine them!
  var dayPart = Utilities.formatDate(targetDate, "Asia/Tokyo", "dd日");
  
  Logger.log("Traditional month output: " + wafuName + " " + dayPart);
  // ➡ Execution log: Traditional month output: 弥生 15日
}

Combining standard methods with simple JavaScript arrays gives you complete flexibility for any custom date naming scheme!

3. Day of the Week Formatting: Sun, Sat, and Full Weekday Names

To format the day of the week, use the E symbol.

Pattern SymbolDescriptionExample (Jan 29, 2026 / Thu)Sunday ExampleSaturday Example
E or EEE3-letter weekday abbreviationThuSunSat
EEEEFull weekday nameThursdaySundaySaturday

Code Example: Extracting Weekday Names

function formatDayOfWeekExamples() {
  var dateThu = new Date(2026, 0, 29); // Thursday, Jan 29, 2026
  var dateSun = new Date(2026, 0, 25); // Sunday, Jan 25, 2026
  var dateSat = new Date(2026, 0, 31); // Saturday, Jan 31, 2026
  var tz = "Asia/Tokyo";

  // EEE returns 3-letter English abbreviations like Sun, Sat, Thu
  Logger.log("Thursday: " + Utilities.formatDate(dateThu, tz, "yyyy-MM-dd (EEE)")); // 2026-01-29 (Thu)
  Logger.log("Sunday: " + Utilities.formatDate(dateSun, tz, "yyyy-MM-dd (EEE)"));   // 2026-01-25 (Sun)
  Logger.log("Saturday: " + Utilities.formatDate(dateSat, tz, "yyyy-MM-dd (EEE)")); // 2026-01-31 (Sat)
}

💡 Need Japanese Weekdays (like “木” or “木曜日”)?

Just like our traditional month names above, create an array like var weekNames = ["日", "月", "火", "水", "木", "金", "土"]; and fetch the item via weekNames[targetDate.getDay()]. It’s the cleanest and most reliable pattern in GAS!

4. Summary Reference: Day, Hour, Minute, and Second Tokens

Here is a quick cheat sheet for day and time tokens. Keep this handy whenever you need to build custom timestamps!

UnitPattern SymbolDescriptionExample (2026/01/29 14:05:09)
Daydd2-digit day (zero-padded)29
d1- to 2-digit day29
HourHH24-hour format (2 digits, 00–23)14
hh12-hour format (2 digits, 01–12)02
Minutemm2-digit minute (lowercase!)05
Secondss2-digit second09

5. 4 Common Traps Beginners Face (and How to Fix Them)

When working with Utilities.formatDate(), almost every beginner runs into one of these classic mistakes. Knowing them in advance will save you hours of debugging!

Trap 1: The 9-Hour Timezone Shift Rollback

You format a date representing “January 29, 2026 at 08:00 AM”, but your output inexplicably displays “January 28, 2026 at 23:00″—shifted back 9 hours to the previous day.

Cause

You passed "GMT" (Coordinated Universal Time) as the 2nd argument. Since Japan Standard Time (JST) is 9 hours ahead of GMT (GMT+9), formatting against GMT shifts your time 9 hours into the past.

Solution

When working with Japan Standard Time, specify "Asia/Tokyo" or use Session.getScriptTimeZone() to match your project settings!

// ✕ Incorrect (Risks rolling back 9 hours to the previous day)
var result = Utilities.formatDate(new Date(), "GMT", "yyyy/MM/dd HH:mm:ss");

// ◯ Correct (Outputs accurately in Japan Standard Time)
var result = Utilities.formatDate(new Date(), "Asia/Tokyo", "yyyy/MM/dd HH:mm:ss");

// ◯ Recommended (Automatically fetches your script's configured timezone)
var result = Utilities.formatDate(new Date(), Session.getScriptTimeZone(), "yyyy/MM/dd HH:mm:ss");

Trap 2: Mixing Up Uppercase MM and Lowercase mm

This is the #1 syntax mistake among beginners!

// ✕ Dangerous mistake!
var wrongDate = Utilities.formatDate(new Date(), "Asia/Tokyo", "yyyy/mm/dd HH:MM:ss");

If you run this on “January 29, 2026, 14:30”, you will get an absurd output like “2026/30/29 14:01:00”, where the month and minute positions are completely swapped.

  • MM (Two uppercase letters) ➡ Month
  • mm (Two lowercase letters) ➡ minute

Letter casing is strictly case-sensitive. Memorize this rule: “Uppercase M for Month, lowercase m for minute!”

Trap 3: Passing a Plain String Instead of a Date Object

When passing a value pulled directly from a spreadsheet cell into Utilities.formatDate(), you might hit this error message:

Exception: The parameters (String,String,String) don't match the method signature for Utilities.formatDate.

Cause

The 1st argument must be a valid Date object. If the value in your spreadsheet cell is treated as a string, GAS will throw an error stating it cannot format a string as a date.

Solution

Wrap the value with new Date(cellValue) to convert it into a true Date object before passing it into Utilities.formatDate().

var rawValue = sheet.getRange("A2").getValue(); // Fetch from cell
var dateObj = new Date(rawValue); // Convert to Date object!
var formatted = Utilities.formatDate(dateObj, "Asia/Tokyo", "yyyy/MM/dd");

Trap 4: Forgetting Quotation Marks Around the Format String

Omitting quotation marks (") around pattern arguments (like yyyy/MM/dd) causes GAS to treat your format string as undefined variable names.

// ✕ Incorrect (Treated as undefined variables and throws a syntax error)
Utilities.formatDate(new Date(), "Asia/Tokyo", yyyy/MM/dd);

// ◯ Correct (Always wrap format patterns in quotation marks as a string)
Utilities.formatDate(new Date(), "Asia/Tokyo", "yyyy/MM/dd");

6. 3 Practical Real-World Automation Examples

Formatting dates is not just for on-screen display. Here are three highly practical patterns used across workplace automations!

Use Case 1: Generating Timestamps for File Names and Logs

When exporting PDFs or creating Google Docs automatically, adding timestamps without punctuation (slashes or colons)—like “20260129_143000″—keeps file paths clean and sorting effortless.

function createTimestampFileName() {
  var now = new Date();
  
  // Clean 'YYYYMMDD_HHmmss' format perfect for file names
  var timeStamp = Utilities.formatDate(now, "Asia/Tokyo", "yyyyMMdd_HHmmss");
  
  var fileName = timeStamp + "_Sapporo_Office_Daily_Report.pdf";
  Logger.log("Generated file name: " + fileName);
  // ➡ Execution log: 20260129_143000_Sapporo_Office_Daily_Report.pdf
}

Use Case 2: Appending Cleanly Formatted Rows to Google Sheets (appendRow + formatDate)

When logging sales numbers or travel expense reports using Sheet.appendRow() (covered in Episode 7), pre-formatting your date string ensures the resulting spreadsheet rows remain uniform and spotless.

function addCleanLogRecord() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var now = new Date();
  
  // Format date as '2026/01/29 (Thu) 14:30'
  var formattedDate = Utilities.formatDate(now, "Asia/Tokyo", "yyyy/MM/dd (EEE) HH:mm");
  
  // Append as an array to the bottom of the active sheet!
  sheet.appendRow([formattedDate, "Takahashi", "Sapporo Station to New Chitose Airport JR Transit", 1590]);
  
  Logger.log("Clean travel expense log record appended successfully!");
}

Use Case 3: Embedding Human-Readable Dates into Modal Dialogs

When showing a confirmation modal to users with Ui.showModalDialog() or Ui.alert() (covered in Episode 28), clear timestamp previews prevent costly operational mistakes.

function showConfirmDialog() {
  var ui = SpreadsheetApp.getUi();
  var now = new Date();
  var dateStr = Utilities.formatDate(now, "Asia/Tokyo", "yyyy/MM/dd HH:mm");
  
  ui.alert(
    "Confirmation",
    "Start full data aggregation based on current time (" + dateStr + ")?",
    ui.ButtonSet.YES_NO
  );
}

7. Summary & What’s Next

In this guide, we explored how to use Utilities.formatDate() in Google Apps Script to design and display dates and times exactly as you want!

Key Takeaways

  1. Use Utilities.formatDate(date, timeZone, format) to transform Date objects into readable strings.
  2. Always set your timezone to "Asia/Tokyo" or Session.getScriptTimeZone().
  3. Control your years with yyyy (4 digits) or yy (2 digits).
  4. Remember that uppercase MM represents Month, while lowercase mm represents minutes.
  5. Use EEE for weekday abbreviations like Sun or Sat, and map arrays for custom naming schemes!

Date data appears across nearly every business automation workflow—sending emails, preparing reports, organizing files, and recording spreadsheet entries. Put these formatting patterns into practice to craft polished, dependable systems!

Next Up

Our 30-episode journey through Phase 3 (Automation, UI Extensions & Error Handling) is almost at the finish line!

In Episode 30, we will master try...catch blocks to prevent unexpected runtime errors from crashing your scripts midway!

We will learn how to write bulletproof, enterprise-ready code that logs errors gracefully and finishes execution without fail, even if an unexpected missing file turns up. See you in the next tutorial!