The Secret Handshake of Time
You are parsing a timestamp from an API response. The string is 2023-10-27T14:30:00Z. You write time.Parse("YYYY-MM-DD", input) because every other language you have used works that way. The compiler accepts the code. You run the program. It panics with a parsing error. You try %Y-%m-%d. Still broken. You try 2006-01-02 on a whim because a forum post mentioned it. It works. You feel like you just learned a secret handshake.
Go does not use format codes. There are no %Y or YYYY tokens. Go uses a reference time. The reference time is a specific moment in history: November 2, 2006, at 15:04:05, in the MST timezone. You build your layout by rearranging the components of this specific timestamp. If you want the year, you write 2006. If you want the month, you write 01. If you want the hour, you write 15. The parser looks at your layout string, finds the numbers from the reference time, and maps them to the corresponding fields in the input string.
Memorize the reference time. Write layouts from memory. Trust the parser.
The Reference Time
The reference time is Mon Jan 2 15:04:05 MST 2006. This string contains every component you might need. The components follow a mnemonic sequence based on the numbers 1 through 6.
The month is 1. In the reference time, the month is Jan, which is the first month. The day is 2. The reference time is the 2nd of the month. The hour is 3. The reference time is 15:04, which is 3 PM. The minute is 4. The second is 5. The year is 6. The reference year is 2006.
This sequence makes the layout intuitive once you know it. You do not need to remember that 01 means month and 02 means day. You just look at the reference time. 01 is the month slot. 02 is the day slot. 15 is the hour slot. 04 is the minute slot. 05 is the second slot. 2006 is the year slot.
The reference time also includes Mon for the day of the week and MST for the timezone. Mon is the abbreviated day name. Monday is the full day name. MST is the timezone abbreviation. Z represents UTC. 07:00 represents a numeric offset like +05:30.
Go provides constants for common layouts. time.RFC3339 is the standard ISO 8601 format used in most APIs. time.RFC3339Nano includes nanoseconds. time.UnixDate is the format used by the date command. Use these constants whenever possible. They prevent typos and make the code readable.
Use constants for standards. Write custom layouts only when necessary.
Minimal Example
package main
import (
"fmt"
"time"
)
// ParseAndFormat demonstrates the reference time layout.
func ParseAndFormat() {
// Layout uses the reference time: Mon Jan 2 15:04:05 MST 2006.
// 2006 is year, 01 is month, 02 is day.
// 15 is hour, 04 is minute, 05 is second.
layout := "2006-01-02 15:04:05"
// Parse converts a string to a time.Time value using the layout.
// The input string must match the layout exactly.
t, err := time.Parse(layout, "2023-10-27 14:30:00")
if err != nil {
// Handle the error. time.Parse returns an error if the string doesn't match.
// Always check the error. A zero time value indicates failure.
panic(err)
}
// Format converts a time.Time value back to a string using the layout.
// The same layout works for both parsing and formatting.
result := t.Format(layout)
fmt.Println(result)
}
func main() {
ParseAndFormat()
}
How Parsing Works
When you call time.Parse, the function reads your layout string character by character. It identifies the reference time components. It scans the input string for matching values.
If the layout contains 2006, the parser looks for a four-digit year in the input. It extracts the digits and sets the year field. If the layout contains 01, the parser looks for a two-digit month. It extracts the digits and sets the month field. The parser continues until the entire layout is consumed.
If the input string has extra characters that the layout did not request, time.Parse rejects it. The layout must match the input exactly. If the layout asks for 2006-01-02 and the input is 2023-10-27 extra, the parser fails. The layout does not consume the extra part.
If the input string is missing data, the parser fails. If the layout asks for 15:04:05 and the input is 14:30, the parser fails. The layout expects seconds. The input does not provide them.
If parsing fails, time.Parse returns a zero time value and an error. The zero time is January 1, year 1, 00:00:00 UTC. Using a zero time value silently produces wrong results. Always check the error. The if err != nil pattern is standard in Go. The community accepts the boilerplate because it makes the unhappy path visible. Ignoring the error is a bug waiting to happen.
Errors are signals. Handle them. Don't ignore the return value.
Realistic Example
package main
import (
"fmt"
"time"
)
// ParseAPIResponse handles timestamps from external services.
// It uses the RFC3339 constant for ISO 8601 compliance.
func ParseAPIResponse(input string) (time.Time, error) {
// time.RFC3339 is defined as "2006-01-02T15:04:05Z07:00".
// This layout accepts Z for UTC or an offset like +00:00.
// Using the constant avoids typos and documents the expected format.
return time.Parse(time.RFC3339, input)
}
// FormatLogEntry creates a high-precision timestamp for logs.
func FormatLogEntry(t time.Time) string {
// Layout includes nanoseconds for debugging concurrent operations.
// 00:00:00.000000000 represents the time with fractional seconds.
// The dot is a literal character. The zeros are the reference second.
layout := "2006-01-02 15:04:05.000000000"
return t.Format(layout)
}
func main() {
// Simulate an API response timestamp.
apiTime := "2023-10-27T14:30:00Z"
// Parse the incoming time.
t, err := ParseAPIResponse(apiTime)
if err != nil {
// Log the error and return.
// In production, return the error to the caller.
fmt.Println("Failed to parse:", err)
return
}
// Format for local logging.
logLine := FormatLogEntry(t)
fmt.Println("Log:", logLine)
}
Pitfalls and Conventions
The most common mistake is using format codes. If you write YYYY-MM-DD, Go treats Y as a literal character. It expects the input string to contain the letter Y. The compiler does not catch this. The error happens at runtime. time.Parse returns an error like parsing time "2023-10-27" as "YYYY-MM-DD": cannot parse "2023-10-27" as "Y". You get a zero time value and an error. If you ignore the error, your program uses the zero time. The zero time is year 1. Your logic breaks silently.
Zero-padding is a silent killer. 01 means the month must be two digits. 1 means the month can be one or two digits. If your data has 9 for September, 01 will fail. If your data has 09, 1 will succeed. Choose based on your data source. If you control the output, 01 is safer for sorting. If you are parsing external data, check the spec. If the spec says ISO 8601, months are zero-padded. Use 01.
Timezones require care. The reference time includes MST. If your layout has MST, the parser expects a timezone name. If you use Z, it expects the literal Z. If you use 07:00, it expects a numeric offset. time.RFC3339 uses Z07:00. This means it accepts either Z or an offset like +00:00. The Z part is optional if the offset is present. This flexibility is built into the constant. If you write your own layout, you must be precise. Z only matches Z. 07:00 only matches offsets. Z07:00 matches both.
time.Parse assumes UTC if the layout does not include a timezone component. If you parse 2023-10-27 14:30:00 with layout 2006-01-02 15:04:05, the result is in UTC. If the input represents local time, you get the wrong time. Use time.ParseInLocation to force a location. time.ParseInLocation takes a *time.Location as the first argument. It interprets the parsed time in that location. If the layout has no timezone, the result uses the provided location. If the layout has a timezone, the result uses the parsed timezone.
time.Time is a value type. It contains two int64 fields. Passing it by value is cheap. Do not use *time.Time in function signatures unless you need to represent a null time. If a field is optional, use a pointer. If it is required, use the value. This keeps the API clean and avoids nil pointer panics. The convention is to pass values, not pointers, for cheap types.
Trust the reference time. Check the error. Use constants.
Decision Matrix
Use time.Parse with a custom layout when you need to read a timestamp from a string that does not match a standard format.
Use time.Parse with a constant like time.RFC3339 when your data follows a widely adopted standard.
Use time.ParseInLocation when you need to interpret a timestamp in a specific timezone that is not present in the input string.
Use time.Format when you need to convert a time.Time value into a string for display or storage.
Use time.Now() to get the current time in the local timezone.
Use time.Date to construct a time value from components like year, month, and day.
Use time.Unix when you are working with Unix timestamps or epoch seconds.