Time and Date Functions

Studio provides a set of functions for working with time and dates in expressions.

They are documented at the end of this page.

Function	Description
`parseTime`	Parses a string into a timestamp
`formatTime`	Formats a timestamp into a string
`getTimezone`	Get the user's local time zone
`geoToTimezone`	Look up the time zone for a location

About Timestamps

Studio internally represents time as timestamps.

Timestamps are integer values representing the number of milliseconds since Jan 1, 1970 (UNIX Epoch).

Timestamps are defined in UTC time (Coordinated Universal Time), meaning that timestamps are independent of time zones, DST (Daylight Savings Time) etc.

Format Codes

Like most time parsing and formatting libraries, Studio uses format codes. Format codes help the user specify:

how strings representing dates should be parsed into timestamps (using parseTime())
how timestamps should be converted to strings (using formatTime())

Studio time functions support two common format code conventions:

1-4 letter codes (JavaScript-style codes, familiar to users of libraries such as momentjs and dayjs).
% + letter codes (Python-style codes, familiar to users of Pandas to_datetime() and Python strptime() and strftime() functions).

Date and Time Format Codes Supported in Studio Expressions

Code	Alt	Example	Description
`YY`	`%y`	18	Two-digit year, without century, zero-padded
`YYYY`	`%Y`	2018	Four-digit year, with century
`M`	`%-m`	1-12	Month as number, beginning at 1
`MM`	`%m`	01-12	Month as 2-digit zero-padded number
`MMM`	`%b`	Jan-Dec	Month as locale’s abbreviated name.
`MMMM`	`%B`	January-December	Month as locale’s full name.
`D`	`%-d`	1-31	Day of the month as number
`DD`	`%d`	01-31	Day of the month as 2-digit zero-padded number
`d`	`%w`	0-6	The day of the week, with Sunday as 0
`dd`		Su-Sa	Weekday as locale’s minimal name.
`ddd`	`%a`	Sun-Sat	Weekday as locale’s abbreviated name.
`dddd`	`%A`	Sunday-Saturday	Weekday as locale’s full name.
`H`	`%-H`	0-23	Hour (24 hour clock)
`HH`	`%H`	00-23	Hour (24 hour clock), 2-digits zero-padded
`h`	`%-I`	1-12	The hour, 12-hour clock
`hh`	`%I`	01-12	The hour, 12-hour clock, 2-digits
`m`	`%-M`	0-59	The minute
`mm`	`%M`	00-59	The minute, 2-digits
`s`	`%-S`	0-59	The second
`ss`	`%S`	00-59	The second, 2-digits
`SSS`		000-999	The millisecond, 3-digits
`Z`		+05:00	The offset from UTC, ±HH:mm
`ZZ`	`%z`	+0500	The offset from UTC, ±HHmm
`A`	`%p`	AM PM	Locale’s equivalent of post or ante meridiem, upper-case
`a`		am pm	Locale’s equivalent of post or ante meridiem, lower-case
`Do`		1st-31st	Day of Month with ordinal
	`%%`	`%`	A literal `%` character

Examples:

Parsing a date string into a timestamp using a format string

TypeScript

parseTime("25/01/2019", "DD/MM/YYYY"); // => 1548403200000
parseTime("25/01/2019", "%d/%m/%Y"); // => 1548403200000

Formatting a timestamp into a date string using a format string

TypeScript

formatTime(1548403200000, "MM/DD/YY"); // => '01/25/19'
formatTime(1548403200000, "%m/%d/%y"); // => '01/25/19'

Time Zones

Time zones affect the conversion of UTC timestamps into local time. The formatTime() and parseTime() functions accept a timezone that lets you

If not specified, the default timezone is used. This timezone is returned by the

getTimezone() function.

It is also possible to calculate the local timezone for a specific location, using the geoToTimezone() function.

Time zones are represented as strings. There are a number of ways to specify timezones. Below is a list of US time zones.

U.S. Time Zone	UTC offset	DST offset
`Pacific/Honolulu`	−10:00	−10:00
`America/Adak`	−10:00	−09:00
`America/Anchorage`	−09:00	−08:00
`America/Los_Angeles`	−08:00	−07:00
`America/Denver`	−07:00	−06:00
`America/Phoenix`	−07:00	−07:00
`America/Chicago`	−06:00	−05:00
`America/New_York`	−05:00	−04:00
`America/Detroit`	−05:00	−04:00

Locales

Strings representing dates and times can contain language specific words (e.g. names of months and weekdays). Accordingly some formatting codes are locale dependent.

Studio currently only supports a default English locale. Please reach out to info-studio@foursquare.com if you need support for additional locales.

parseTime

Parse a string into a timestamp.

TypeScript

parseTime(time: string, format?: string, timezone?: string): timestamp

time A string representing a date and/or time.
format An optional string describing the format of the date/time strings to be parsed. If no format is provided, the date is assumed to be in ISO 8601 format.
timezone An optional string representing the time zone that the times should be interpreted in, if not provided, the current timezone (defined by the user's browser and operating system) will be used.
Returns: an integer timestamp.

Example: No format string provided. ISO 8601 formatted dates can be parsed.

TypeScript

parseTime("2018-04-04");
parseTime("2018-04-04T16:00:00.000Z");

formatTime

Format a timestamp into a string.

TypeScript

formatTime(ts: timestamp, format?: string, timezone?: string): string

timestamp An integer timestamp
format An optional string describing the format of the resulting date/time strings. If no format is provided, the date will be formatted in ISO 8601 format.
timezone An optional string representing the time zone that the timestamp should be converted to, if not provided, the current timezone (defined by the user's browser and operating system) will be used.

getTimezone

Returns the users current timezone.

TypeScript

getTimezone(): string

Returns a string representing the local time zone that can be used in other functions accepting timezones, including parseTime() and formatTime(). The format would normally be a long string such as America/Los_Angeles. Note that different users may get different values depending on

their location in the world and settings in their browser and operating system.

geoToTimezone

Looks up the timezone for a specific location.

TypeScript

geoToTimezone(lng: number, lat: number): string

lng longitude in degrees
lat longitude in degrees
Returns an IANA timezone database string (such as America/Los_Angeles) representing the local time zone that can be used in other functions accepting timezones, including parseTime() and formatTime().

Remarks:

The timezones returned by this function are approximate: since the official timezone database is so large, lossy compression is necessary for a small footprint and fast lookups. Expect errors near timezone borders far away from populated areas. However, for most use-cases, accuracy should be adequate.