Timezones, Accounts, and Billing

Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value.) Datetimes may be specified in any timezone in a POST or PUT command using the ISO 8601 standard format for timezone. Time is represented using a subset of ISO-8601. More specifically, the strptime string for our date format is "%Y-%m-%dT%l:%M:%S%z". The timezone of the advertiser’s account determines the actual time that the official billing numbers are frozen.

When querying the API at the account level (GET accounts), you will get timezone information that looks like this:

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "API McTestface",
    "business_name": null,
    "timezone": "America/Los_Angeles",
    "timezone_switch_at": "2016-07-21T07:00:00Z",
    "id": "18ce54d4x5t",
    "created_at": "2016-07-21T22:42:09Z",
    "salt": "54cb7b5a34183f77d82dd6d0f4329691",
    "updated_at": "2017-09-09T06:42:14Z",
    "business_id": null,
    "approval_status": "ACCEPTED",
    "deleted": false
  }
}

This includes two timezone values: timezone (see timezones at wikipedia for an overview) and timezone_switch_at. Note that timezone_switch_at is given in the UTC timezone (+00:00), but will always represent midnight in the given timezone.

The advertiser’s timezone is not editable via the API. This attribute is set at the contractual/billing level by the advertiser’s account manager at Twitter.

Please be aware of the timezone_switch_at value when creating reports and querying our analytics endpoints as there will be a gap on the day the account switches from the America/Los_Angeles timezone to the new local value.

Specifying Datetime Values With Timezone

Datetime values are always returned in UTC time (as indicated by the Z at the end of the datetime value). Datetimes may be specified in any timezone in a POST or PUT command using the ISO 8601 standard format for timezone. For example, 2017-07-10T08:00:00-0800 is an acceptable input value and will be automatically translated to the UTC value of 2017-07-10T16:00:00Z.

When using the analytics endpoints with granularity of DAY or TOTAL, the start_time value must be specified at midnight of the desired day in the local timezone of the account holder. The timezone offset to be used will be the offset of the current day, not the offset of the day in question. For example, for an ads account in America/Los_Angeles during Pacific Daylight Savings time, the UTC offset is -0700. Thus, in an analytics request, the time should be specified as: start_time=2017-05-21T07:00:00Z or start_time=2017-05-21T00:00:00-0700. If the ads account was in Asia/Tokyo, where the offset is always +09:00, the values would be specified as: start_time=2017-05-20T15:00:00Z or start_time=2017-05-21T00:00:00+0900.