New in Formulas 2.0
The parseDate() function takes an ISO 8601-formatted date string (an international standard) and returns it as a date object.
parseDate(string) string.parseDate()
A standard ISO 8601-formatted date looks like the following. The dashes - and colons : are optional but are recommended for readability.
YYYY-MM-DDTHH:MM:SSZ YYYYMMDDTHHMMSSZ
Each date and time value requires a fixed number of digits that are padded with leading zeros.
| Token | Item | Values | Notes |
|---|---|---|---|
YYYY |
Year |
0000 – 9999
|
|
MM |
Month |
01 – 12
|
|
DD |
Date |
01 – 31
|
|
T |
Time | Required between the date and the time | |
HH |
Hour |
00 – 23
|
|
MM |
Minute |
00 – 59
|
|
SS |
Second | Notion does not support seconds in date objects | |
Z |
Timezone Offset |
Z+00:00-01:00
|
Z can be used as is (zero offset UTC), or alternatively options like +01:00 and -04:00 can be used directly following the time |
Example Formulas
parseDate("2023-07-29") /* Output: July 29, 2023 */
"20151021T1608".parseDate() /* Output: October 21, 2015 4:08 PM */
Additional Tokens
While you’ll likely only need to use the standard YYYY-MM-DDTHH:MM:SSZ tokens, there are also some others that are supported.
Week Dates
Week dates utilise a year number, an ISO week date number, and a day of the week number.
YYYY-Www-D YYYYWwwD
| Token | Item | Values | Notes |
|---|---|---|---|
| YYYY | Year | 0000 – 9999 | |
| Www | Week | W01 – W53 | |
| D | Day | 1 – 7 | 1 = Monday, 7 = Sunday, etc. |
"2020-W01-1".parseDate() /* Output: December 30, 2019 */
parseDate("2020-W53-7") /* Output: January 3, 2021 */
Ordinal Dates
Ordinal dates utilise a year number and a day of the year number.
YYYY-DDD YYYYDDD
| Token | Item | Values | Notes |
|---|---|---|---|
| YYYY | Year | 0000 – 9999 | |
| DDD | Day of the year | 001 – 366 | Predictably, 366 only works for leap years |
parseDate("1981-095") /* Output: December 29, 2008 */
"2015-294T04:08".parseDate() /* Output: October 21, 2015 4:08 PM */