> ## Documentation Index
> Fetch the complete documentation index at: https://www.propeldata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with timezones

> Power a localized user experiences.

<div />

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](/docs/query-apis/counter), [Data Grid](/docs/query-apis/data-grid), [Time Series](/docs/query-apis/time-series), [Leaderboard](/docs/query-apis/leaderboard), [Metric Report](/docs/query-apis/metric-report), and [Top Values](/docs/query-apis/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](/docs/query-apis/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](/docs/query-apis/counter), [Data Grid](/docs/query-apis/data-grid), [Time Series](/docs/query-apis/time-series), [Leaderboard](/docs/query-apis/leaderboard), [Metric Report](/docs/query-apis/metric-report), and [Top Values](/docs/query-apis/top-values) queries. By default, it is set to `UTC`.

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

<CodeGroup>
  ```graphql Query theme={"system"}
  query {
    timeSeries(input: {
      ...
      timeZone: "America/Los_Angeles"
      ...
    }) {
      labels
      values
    }
  }
  ```

  ```json Response theme={"system"}
  {
    "data": {
      "timeSeries": {
        "labels": [
          "2023-09-06T07:00:00Z",
          "2023-09-07T07:00:00Z",
          "2023-09-08T07:00:00Z"
        ],
        "values": [
          "288.25",
          "0",
          "0"
        ]
      }
    }
  }
  ```
</CodeGroup>

The `timeZone` field can be any timezone in the [tz database](https://en.wikipedia.org/wiki/Tz_database), for example "America/New\_York" or "Europe/Paris". You can view the full list of tz database timezones on [this Wikipedia page.](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

## 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).

<CodeGroup>
  ```graphql theme={"system"}
  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
    }
  }
  ```

  ```json Response theme={"system"}
  {
    "data": {
      "timeSeries": {
        "labels": [
          "2023-08-01T04:00:00Z",
          "2023-08-02T04:00:00Z",
          "2023-08-03T04:00:00Z",
          "2023-08-04T04:00:00Z",
          ...
          "2023-08-29T04:00:00Z",
          "2023-08-30T04:00:00Z",
          "2023-08-31T04:00:00Z",
          "2023-09-01T04:00:00Z"
        ],
        "values": [
          "0",
          "0",
          "0",
          "253.75",
          ...
          "361",
          "552",
          "783",
          "36.25"
        ]
      }
    }
  }
  ```
</CodeGroup>

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`.
</Tip>