Date Functions

The Date functions provide methods for creating date objects and getting various properties of the objects. The DateAdd() and DateDiff() functions are convenient for adjusting the desired date based on a specified interval. The Now() function may also be used to get the current time in the local time of the client.

---

Date

This function has 3 signatures:

• Date( year, month, day, hour?, minute?, second?, millisecond? ) -> Date
• Date( epoch? ) -> Date
• Date( timestamp? ) -> Date

Date( year, month, day, hour?, minute?, second?, millisecond? ) -> Date

Parses a value or set of values to a Date object. Dates that are manually created are assumed to be UTC. See the example snippets below to view various ways this function may be used.

Name	Type	Description
year	Number	A number representing a year.
month	Number	The month (0-11) where 0 is January and 11 is December.
day	Number	The day of the month (1-31).
hour	Number	optional The hour of the day (0-23).
minute	Number	optional The minute of the hour (0-59).
second	Number	optional The second of the minute (0-59).
millisecond	Number	optional The millisecond of the second (0-999).

Returns: Date

Example

Year, month, day

prints 'Tue Jun 02 1987 00:00:00 GMT-0700 (PDT)'

Date(1987,05,02)

With no parameters

prints the current date and time

Date()

Date( epoch? ) -> Date

Converts a Unix epoch number to a Date object.

Name	Type	Description
epoch	Number	optional The number of milliseconds since January 1, 1970 UTC.

Returns: Date

Example

Create a date with the value of a date field

returns a date object based on a field value

var recordDate = Date($feature.dateField)

Milliseconds since epoch

prints 'Thu Oct 20 2016 11:23:03 GMT-0700 (PDT)'

Date(1476987783555)

Date( timestamp? ) -> Date

Converts an ISO 8601 string to a Date object.

Name	Type	Description
timestamp	Text	optional An ISO 8601 string to be converted into a date.

Returns: Date

Example

ISO 8601 string

prints 'Thu Oct 20 2016 10:41:37 GMT-0700 (PDT)'

Date('2016-10-20T17:41:37+00:00')

---

DateAdd

DateAdd( date, addValue, units ) -> Date

Adds a specified amount of time in the given units to a date and returns a new date.

Name	Type	Description
date	Date	The input date to which to add time.
addValue	Number	The value to add to the date in the given units.
units	Text	The units of the number to add to the date. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years

Returns: Date

Example

Adds 7 days to the date in the provided field

var startDate = Date($feature.dateField);
var oneWeekLater = DateAdd(startDate, 7, 'days');
return oneWeekLater;

---

DateDiff

DateDiff( date1, date2, units? ) -> Number

Subtracts two dates, and returns the difference in the specified units.

Name	Type	Description
date1	Date	The date value from which to subtract a second date.
date2	Date	The date value to subtract from the first given date.
units	Text	optional The units in which to return the difference of the two given dates. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years. The default value is milliseconds.

Returns: Number

Example

Subtracts two dates and returns the age

var startDate = Date($feature.startDateField);
var endDate = Date($feature.endDateField);
var age = DateDiff(endDate, startDate, 'years');
return age;

---

Day

Day( dateValue ) -> Number

Returns the day of the month of the given date.

Name	Type	Description
dateValue	Date	A date value from which to get the day of the month.

Returns: Number

Example

Gets the day of the month of the current date

Day(Now())

---

Hour

Hour( dateValue ) -> Number

Returns the hour of the time in the given date (0-23).

Name	Type	Description
dateValue	Date	A date value from which to get the hour of the time.

Returns: Number

Example

Gets the hour of the current time

Hour(Now())

---

ISOMonth

ISOMonth( dateValue ) -> Number

Since version 1.12

Returns the month of the given date, based on the ISO 8601 standard. Values range from 1-12 where January is 1 and December is 12.

Name	Type	Description
dateValue	Date	A date value from which to get the month.

Returns: Number

Example

Gets the month of the given date, based on the ISO 8601 standard. Returns 12, for the month of December.

ISOMonth(Date(1980, 11, 31))

---

ISOWeek

ISOWeek( dateValue ) -> Number

Since version 1.12

Returns the week in the year of the given date, based on the ISO 8601 week date calendar. Values range from 1-53 where the first week of the year is 1 and the last week of the year is 52 or 53, depending on the year.

Name	Type	Description
dateValue	Date	A date value from which to get the week.

Returns: Number

Example

Gets the week of the given date, based on the ISO 8601 standard. Returns 1, since this date is included in the first week of the following year.

ISOWeek(Date(1980, 11, 31))

---

ISOWeekday

ISOWeekday( dateValue ) -> Number

Since version 1.12

Returns the day of the week of the given date, based on the ISO 8601 standard. Values range from 1-7 where Monday is 1 and Sunday is 7.

Name	Type	Description
dateValue	Date	A date value from which to return the day of the week.

Returns: Number

Example

Returns the day of the week of the given date, based on the ISO 8601 standard. Returns 3, for Wednesday.

ISOWeekday(Date(1980, 11, 31))

---

ISOYear

ISOYear( dateValue ) -> Number

Since version 1.12

Returns the year of the given date based on the ISO 8601 week date calendar.

Name	Type	Description
dateValue	Date	A date value from which to get the year.

Returns: Number

Example

Gets the year of the given date, based on the ISO 8601 week date calendar. Returns 1981, since this date is included in the first week of the following year.

ISOYear(Date(1980, 11, 31))

---

Millisecond

Millisecond( dateValue ) -> Number

Returns the millisecond of the time in the date.

Name	Type	Description
dateValue	Date	A date value from which to get the millisecond of the time.

Returns: Number

Example

Gets the millisecond of the current time

Millisecond(Now())

---

Minute

Minute( dateValue ) -> Number

Returns the minute of the time in the given date.

Name	Type	Description
dateValue	Date	A date value from which to get the minute of the time.

Returns: Number

Example

Gets the minute of the current time

Minute(Now())

---

Month

Month( dateValue ) -> Number

Returns the month of the given date. Values range from 0-11 where January is 0 and December is 11.

Name	Type	Description
dateValue	Date	A date value from which to get the month.

Returns: Number

Example

Gets the month of the given Date. Returns 11, for the month of December.

Month(Date(1980, 11, 31))

---

Now

Now( ) -> date

Returns the current date and time in the local time of the client.

Returns: date

Example

Returns the current date and time

e.g. Mon Oct 24 2016 12:09:34 GMT-0700 (PDT)

Now()

---

Second

Second( dateValue ) -> Number

Returns the second of the time in the date.

Name	Type	Description
dateValue	Date	A date value from which to get the second of the time.

Returns: Number

Example

Gets the second of the current time

Second(Now())

---

Timestamp

Timestamp( ) -> Date

Since version 1.1

Returns the current date and time in UTC time.

Returns: Date

Example

Returns the current date and time in UTC time

e.g. 29 Mar 2017 08:37:33 pm

Timestamp()

---

Today

Today( ) -> Date

Returns the current date in the local time of the client.

Returns: Date

Example

Returns the current date with time truncated

e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)

Today()

---

ToLocal

ToLocal( utcDate ) -> Date

Since version 1.1

Converts the given UTC date to a date value in the local time of the client.

Name	Type	Description
utcDate	Date	A UTC date value to convert to the local time of the client. This value is assumed to be in UTC time.

Returns: Date

Example

Convert a UTC date to the local time of the client running the app

e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)

ToLocal(Timestamp())

---

ToUTC

ToUTC( localDate ) -> Date

Since version 1.1

Converts the given date value from the client's local time to UTC time. Date values in Arcade are already assumed to be UTC. Sometimes dates in databases are stored in local time. Use this function to normalize dates stored in local time with other dates created in Arcade expressions.

Name	Type	Description
localDate	Date	A date value in local time to convert to UTC time. This value is assumed to be in local time.

Returns: Date

Example

Returns the current date and time in UTC

e.g. 29 Mar 2017 08:37:33 pm

// 29 Mar 2017 01:37:33 pm
Now()
// 29 Mar 2017 08:37:33 pm
ToUTC(Now())

---

Week

Week( dateValue, startDay? ) -> Number

Since version 1.14

Returns the week number in the year of the given date. Values range from 0-53 where the first week of the year is 0 and the last week of the year is 51, 52, or 53, depending on the year. The first and last weeks may not be a full seven days in length.

Name	Type	Description
dateValue	Date	A date value from which to get the week.
startDay	Number	optional A number representing the start day of the week. Sunday = 0; Monday = 1; Tuesday = 2; Wednesday = 3; Thursday = 4; Friday = 5; Saturday = 6. The default is 0 (Sunday).

Returns: Number

Example

Use the default start of the week (Sunday)

Week( Date(1974,0,3) )
// Returns 0

Set start of week to Thursday

Week( Date(1974,0,3), 4 )
// Returns 1

Set start of week to Friday

Week( Date(1974,0,3), 5 )
// Returns 0

Week( Date(1945,8,23) )
// Returns 38

Week( Date(2022,7,20) )
// Returns 33

---

Weekday

Weekday( dateValue ) -> Number

Returns the day of the week of the given date. Values range from 0-6 where Sunday is 0 and Saturday is 6.

Name	Type	Description
dateValue	Date	A date value from which to return the day of the week.

Returns: Number

Example

Returns the day of the week of the given date. Returns 3, for Wednesday.

Weekday(Date(1980, 11, 31))

---

Year

Year( dateValue ) -> Number

Returns the year of the given date.

Name	Type	Description
dateValue	Date	A date value from which to get the year.

Returns: Number

Example

Gets the year of the current date

Year(Now())

---