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

Function bundle: Core

Creates a Date object from a set of parameters. By default, dates are created in the local time of the client or system.

Parameters

• 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 (Optional): Number - The hour of the day (0-23).
• minute (Optional): Number - The minute of the hour (0-59).
• second (Optional): Number - The second of the minute (0-59).
• millisecond (Optional): Number - The millisecond of the second (0-999).

Return value: Date

Examples

Creates a date representing the given time in the local time of the system running Arcade

1
2
// Date that represents Jun 02, 1987, 12:00:00 AM PST
Date(1987,05,02)

Creates a date representing the current time in the local time of the system running Arcade

1
2
// Date represents Jan 27, 2023, 12:41:20 PM PST
Date()

Date(epoch?) -> Date

Function bundle: Core

Creates a date with the given Unix epoch number in the local time zone of the client or system.

Parameter

• epoch (Optional): Number - The number of milliseconds since January 1, 1970 UTC.

Return value: Date

Example

Milliseconds since January 1, 1970

1
Date(1476987783555) // 'Thu Oct 20 2016 11:23:03 GMT-0700 (PDT)'

Date(timestamp?) -> Date

Function bundle: Core

Converts an ISO 8601 text value to a Date object in the local time zone of the client or system.

Parameter

• timestamp (Optional): Text - An ISO 8601 text value to be converted into a date.

Return value: Date

Example

ISO 8601 text value

1
Date('2016-10-20T17:41:37+00:00') // 'Thu Oct 20 2016 10:41:37 GMT-0700 (PDT)'

DateAdd

DateAdd(dateValue, addValue, units?) -> Date

Function bundle: Core

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

Parameters

• dateValue: Date - The input date to which to add time.
• addValue: Number - The value to add to the date in the given units.
• units (Optional): Text - The units of the number to add to the date. Default is 'milliseconds. The supported unit types include milliseconds, seconds, minutes, hours, days, months, years`

Return value: Date

Example

Adds 7 days to the date in the provided field

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

DateDiff

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

Function bundle: Core

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

Parameters

• 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 (Optional): Text - 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.

Return value: Number

Example

Subtracts two dates and returns the age

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

Day

Day(dateValue) -> Number

Function bundle: Core

Returns the day of the month of the given date.

Parameter

• dateValue: Date - A date value from which to get the day of the month.

Return value: Number

Example

Gets the day of the month of the current date

1
Day(Now())

Hour

Hour(dateValue) -> Number

Function bundle: Core

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

Parameter

• dateValue: Date - A date value from which to get the hour of the time.

Return value: Number

Example

Gets the hour of the current time

1
Hour(Now())

ISOMonth

ISOMonth(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date - A date value from which to get the month.

Return value: Number

Example

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

1
ISOMonth(Date(1980, 11, 31))

ISOWeek

ISOWeek(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date - A date value from which to get the week.

Return value: 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.

1
ISOWeek(Date(1980, 11, 31))

ISOWeekday

ISOWeekday(dateValue) -> Number

Since version 1.12

Function bundle: Core

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.

Parameter

• dateValue: Date - A date value from which to return the day of the week.

Return value: Number

Example

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

1
ISOWeekday(Date(1980, 11, 31))

ISOYear

ISOYear(dateValue) -> Number

Since version 1.12

Function bundle: Core

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

Parameter

• dateValue: Date - A date value from which to get the year.

Return value: 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.

1
ISOYear(Date(1980, 11, 31))

Millisecond

Millisecond(dateValue) -> Number

Function bundle: Core

Returns the millisecond of the time in the date.

Parameter

• dateValue: Date - A date value from which to get the millisecond of the time.

Return value: Number

Example

Gets the millisecond of the current time

1
Millisecond(Now())

Minute

Minute(dateValue) -> Number

Function bundle: Core

Returns the minute of the time in the given date.

Parameter

• dateValue: Date - A date value from which to get the minute of the time.

Return value: Number

Example

Gets the minute of the current time

1
Minute(Now())

Month

Month(dateValue) -> Number

Function bundle: Core

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

Parameter

• dateValue: Date - A date value from which to get the month.

Return value: Number

Example

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

1
Month(Date(1980, 11, 31))

Now

Now() -> Date

Function bundle: Core

Creates a date value in the local or system time of the client.

Return value: Date

Example

Returns the current date and time

1
2
// Date represents Jan 27, 2023, 12:41:20 PM PST
Now()

Second

Second(dateValue) -> Number

Function bundle: Core

Returns the second of the time in the date.

Parameter

• dateValue: Date - A date value from which to get the second of the time.

Return value: Number

Example

Gets the second of the current time

1
Second(Now())

Timestamp

Timestamp() -> Date

Since version 1.1

Function bundle: Core

Creates a date value representing the current date and time in UTC.

Return value: Date

Example

Creates a date in UTC time

1
2
// Date that represents Jan 27, 2023, 8:41:20 PM UTC
Timestamp()

Today

Today() -> Date

Function bundle: Core

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

Return value: Date

Example

Returns the current date with time truncated, e.g. Mon Oct 24 2016 00:00:00 GMT-0700 (PDT)

1
Today()

ToLocal

ToLocal(inputDate) -> Date

Since version 1.1

Function bundle: Core

Creates a new date value matching the epoch of the input date and sets the time zone to the local or system time zone of the client.

Parameter

• inputDate: Date - A date value to convert to the local time of the client.

Return value: Date

Example

Converts a UTC date to the local time of the client

1
2
3
4
// Date represents Jan 27, 2023, 8:41:20 PM UTC
Timestamp()
// Date represents Jan 27, 2023, 12:41:20 PM PST
ToLocal(Timestamp())

ToUTC

ToUTC(inputDate) -> Date

Since version 1.1

Function bundle: Core

Creates a new date value matching the epoch of the input date and sets the time zone to UTC.

Parameter

• inputDate: Date - A date value to convert to UTC time.

Return value: Date

Example

Converts the date object from local time to UTC

1
2
3
4
// Date represents Jan 27, 2023, 12:41:20 PM PST
Now()
// Date represents Jan 27, 2023, 8:41:20 PM UTC
ToUTC(Now())

Week

Week(dateValue, startDay?) -> Number

Since version 1.14

Function bundle: Core

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.

Parameters

• dateValue: Date - A date value from which to get the week.
• startDay (Optional): Number - 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).

Return value: Number

Examples

Use the default start of the week (Sunday)

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

Set start of week to Thursday

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

Set start of week to Friday

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

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

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

Weekday

Weekday(dateValue) -> Number

Function bundle: Core

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

Parameter

• dateValue: Date - A date value from which to return the day of the week.

Return value: Number

Example

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

1
Weekday(Date(1980, 11, 31))

Year

Year(dateValue) -> Number

Function bundle: Core

Returns the year of the given date.

Parameter

• dateValue: Date - A date value from which to get the year.

Return value: Number

Example

Gets the year of the current date

1
Year(Now())