Date, time, and date-time expressions

Examples of report expressions for date, time, and date-time questions are provided below.

To ensure that date and date-time questions are presented in a way that's accurate for your region's formatting, you can use an expression to format the question to match a provided locale. Place the locale method first in the expression, and the locale code must be lowercase:

${datetime | locale:"pt-br"}

Note:

For information about a specific language's locale code, see Wikipedia's List of ISO 639-1 codes. However, not all of these languages are supported by Survey123.

All date and date-time values in a feature layer are stored in coordinated universal time (UTC). By default, all date and date-time values returned in a report are in the same time zone as the web browser that was used to request the report generation. You can use the utcOffset method to alter the display of these values in a report to match a specific time zone. The following expression displays the response to a date-time question offset +1 hour from UTC:

${datetime | utcOffset:"+01:00"}

The utcOffset method supports the +01:00, +0100, and +01 formats and returns the same result. You can also use this method to alter the display of the response submission time. Be aware that utcOffset does not work with time questions.

For date and date-time questions, you can use an expression to format the date using DD, MM, and YYYY placeholders for day, month, and year, respectively. The following expression displays only the day and month, omitting the year:

${date | format:"DD/MM"}

You can also format the time in date-time questions, using HH, mm, and ss as placeholders for hours, minutes, and seconds, respectively. The following expression displays the day, month, hours, and minutes:

${datetime | format:"DD/MM HH:mm"}

You can display dates and times in the ISO 8601 format of YYYY-MM-DDTHH:mm:ss±HH:mm by leaving the value for the format method blank, as shown in the following example:

${datetime | format:""}

For more information about date and time formats, see the table below.

Note:

You must place the format method at the end of the expression.

You can print the date and time the report was generated using the $date keyword. Use the format method to control whether to print the date, the time, or both. The following example prints the date the report was generated (without the time) in the default date format for your locale:

${$date}

The following expression prints the month, day, year, hours, and minutes for the date and time the report was generated:

${$date | format:"MM/DD/YYYY HH:mm"}

The following expression prints the time the report was generated (without the date) in hours, minutes, and seconds in 12-hour time:

${$date | format:"h:mm:ss A"}

The $date keyword also supports the utcOffset and locale methods. The locale method is ignored when both format and locale are specified.

Date and time formats

The following table lists the most common placeholders that can be used with the format method to format dates and times in a report:

Placeholder	Description
YY	Last two digits of the year. Example: 2023 would be represented as 23.
YYYY	Four digits of the year. Example: 2023 would be represented as 2023.
M	Month number between 1 and 12. Example: January would be represented as 1.
MM	Month number in two digits. Example: January would be represented as 01.
MMM	Month in three letters. Example: January would be represented as Jan.
MMMM	Month written in full. Example: January would be represented as January.
D	Day number between 1 and 31. Example: The first day of the month is represented as 1.
DD	Day number in two digits. Example: The first day of the month is represented as 01.
Do	Day number that includes ordinal suffixes. Example: The first day of the month is represented as 1st.
H	Hour number in 24-hour time. Example: 11 p.m. would be represented as 23.
HH	Hour number in 24-hour time in two digits. Example: 2 a.m. would be represented as 02.
h	Hour number in 12-hour time. Example: 11 p.m. would be represented as 11.
hh	Hour number in 12-hour time in two digits. Example: 2 a.m. would be represented as 02.
m	Minute number between 0 and 59. Example: 8 minutes would be represented as 8.
mm	Minute number in two digits. Example: 8 minutes would be represented as 08.
ss	Seconds number in two digits. Example: 9 seconds would be represented as 09.
Z	Time zone offset in hours using separator. Examples: -07:00, +13:00
ZZ	Time zone offset in hours with no separator. Examples: -0700, +1300
x	UNIX millisecond time stamp. Example: 9 p.m. on 4 May 2023 GMT would be represented as 1683234000000.
X	UNIX time stamp. Example: 9 p.m. on 4 May 2023 GMT would be represented as 1683234000.
a	Lowercase morning or afternoon notation. Example: a.m. would be represented as am, and p.m. would be represented as pm.
A	Uppercase morning or afternoon notation. Example: a.m. would be represented as AM, and p.m. would be represented as PM.