Timezones

Timezone in the Ads API

Timezone, Accounts, and Billing

The timezone of the advertiser’s account determines the actual time that the official billing numbers are frozen. Before this change, all billing numbers for the previous day were frozen at 9am Pacific Standard Time (“America/Los Angeles” timezone). After this change, the official billing numbers are frozen at 9am in the advertiser’s local timezone.

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

{
    "created_at": "2012-03-10T17:58:22Z",
    "currency": "USD",
    "deleted": false,
    "id": "hkk5",
    "name": "Soda US",
    "timezone": "Asia/Tokyo",
    "timezone_switch_at": "2012-06-10T15:00:00Z",
    "updated_at": "2012-11-10T22:55:01Z"
}

As of 2013-05-22T09:00:00-0800, two new values will be present, 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 /stats/ 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, 2012-06-10T08:00:00-0800 is an acceptable input value and will be automatically translated to the UTC value of 2012-06-10T16:00:00Z.

When using the /stats/ 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, my account is in America/Los_Angeles, and we are currently in Pacific Daylight Savings time, so my offset from UTC is -0700. Thus I must specify start_time=2013-05-21T07:00:00Z or start_time=2013-05-21T00:00:00-0700. If the advertiser account was in Asia/Tokyo, where the offset is always +09:00, I would need to use start_time=2013-05-20T15:00:00Z or start_time=2013-05-21T00:00:00+0900.

Accepted UTC Offset Formats

See ISO 8601 Time zone designators.

Supported: Z, -HHMM, +HHMM, -HH:MM, +HH:MM, -HH, +HH