Skip to main content

How to use time zones in Propel GraphQL queries

In this guide, you will learn what the time zone input field does and how to use it in GraphQL queries to power a localized user experience.

What does the timeZone input field do?​

The timeZone field tells Propel what time zone to use when aggregating data in a query.

For example, if a user requests a Counter with a TODAY relative time range, the definition of today depends on the time zone. By passing the time zone field at query time, users can get data for today in their own time zone. Similarly, if a user asks for a Time Series with DAY granularity, the start and end of each day granule depend on the time zone.

The big advantage of passing the time zone at query time is that you can serve users in multiple time zones with the same data.

How to use the timeZone input field​

You can set the timeZone field in Counter, Time Series, Leaderboard, and Metric Report queries. By default, it’s set to UTC.

A Time Series query with a timeZone field looks like this:

query TimeSeriesExample($input: TimeSeriesInput!) {
  timeSeries(input: $input) {
    labels
    values
  }
}

The timeZone field can be any timezone in the tz database, for example "America/New_York" or "Europe/Paris". You can view the full list of tz database timezones on this Wikipedia page.

What about the absolute timeRange?​

The absolute time range is defined by start and end ISO 8601 timestamps that include time zone information, for example, "2023-08-03T00:00:00Z" or "2023-08-03T00:00:00+02:00". Therefore, the time zone parameter has no effect on the absolute time range. However, in Time Series queries, it does affect how the granules of the time granularity are calculated.

For instance, here’s a Time Series query for the month of August 2023 in the "America/New_York" time zone (UTC-5 when Daylight Saving Time is not in effect).

query TimeSeriesExample($input: TimeSeriesInput!) {
  timeSeries(input: $input) {
    labels
    values
  }
}

Note: We used “2023-08-01T00:00:00-05:00Z” and “2023-08-31T23:59:59-05:00Z” as the start and stop time stamps to specify the absolute time range to query.

Then we used "timeZone": "America/New_York" to specify the starting and end times for "granularity": "DAY".

tip

JavaScript developers can use the built-in Date object and call toISOString(). It will return the correct format for timeRange.

Resources​