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 Position | Parameter Name | Purpose and Value to Specify | Concrete Example |
| 1st Argument | date | The original date data to convert (Date object) | new Date() or a date retrieved from a cell |
| 2nd Argument | timeZone | The reference standard time zone to use for calculation | "Asia/Tokyo" or Session.getScriptTimeZone() |
| 3rd Argument | format | The 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 Symbol | Description | Output Example (Jan 29, 2026) |
yyyy | Full year (4 digits) | 2026 |
yy | Last 2 digits of the year | 26 |
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 Symbol | Description | January (Jan) | March (Mar) | April (Apr) |
MM | 2-digit number (zero-padded) | 01 | 03 | 04 |
M | 1- to 2-digit number | 1 | 3 | 4 |
MMM | English 3-letter abbreviation | Jan | Mar | Apr |
MMMM | English full month name | January | March | April |
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 Symbol | Description | Example (Jan 29, 2026 / Thu) | Sunday Example | Saturday Example |
E or EEE | 3-letter weekday abbreviation | Thu | Sun | Sat |
EEEE | Full weekday name | Thursday | Sunday | Saturday |
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 viaweekNames[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!
| Unit | Pattern Symbol | Description | Example (2026/01/29 14:05:09) |
| Day | dd | 2-digit day (zero-padded) | 29 |
d | 1- to 2-digit day | 29 | |
| Hour | HH | 24-hour format (2 digits, 00–23) | 14 |
hh | 12-hour format (2 digits, 01–12) | 02 | |
| Minute | mm | 2-digit minute (lowercase!) | 05 |
| Second | ss | 2-digit second | 09 |
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) ➡ Monthmm(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
- Use
Utilities.formatDate(date, timeZone, format)to transform Date objects into readable strings. - Always set your timezone to
"Asia/Tokyo"orSession.getScriptTimeZone(). - Control your years with
yyyy(4 digits) oryy(2 digits). - Remember that uppercase
MMrepresents Month, while lowercasemmrepresents minutes. - Use
EEEfor 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!
