Working with timezones

Power a localized user experiences.

Use the timeZone input field in GraphQL queries to power localized user experiences.

What does the timeZone input field do?

The timeZone field specifies which timezone Propel should use when calculating time-based aggregations in your queries.

Here’s how it works:

• For queries with relative time ranges like TODAY, supported in the Counter, Data Grid, Time Series, Leaderboard, Metric Report, and Top Values APIs, the timezone determines what “today” means. For example, “today” starts at different times for users in New York versus London.

• For Time Series queries, the timezone determines the start and end of each time granule. For example, for a query with DAY time granularity, the timezone determines the start and end of each day in the user’s timezone.

By setting the timezone at query time, you can:

• Serve users across different timezones with the same underlying data
• Show each user data that aligns with their local time
• Avoid confusion from mismatched time boundaries

How to use the timeZone input field

You can set the timeZone field in Counter, Data Grid, Time Series, Leaderboard, Metric Report, and Top Values queries. By default, it is set to UTC.

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

Query

query {
  timeSeries(input: {
    ...
    timeZone: "America/Los_Angeles"
    ...
  }) {
    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 {
  timeSeries(input: {
    metricName: "Revenue",
    granularity: DAY,
    timeRange: {
      start: "2023-08-01T00:00:00-05:00Z",
      stop: "2023-08-31T23:59:59-05:00Z"
    },
    timeZone: "America/New_York",
  }) {
    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".

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