Snapchat API Date and timezone shenanigans – “The start time should be start of a Local Time Zone day for DAY query”

Have been dealing with Snapchat API for the past few days, and boy is that a terrible API to work with…

When querying the Campaign stats endpoint and want to get stats on a day level, you need to specify start_date and end_date. That makes sense. It also specifies date format should follow ISO 8601. That is the only sane date format in the world, so great!

I could take you through my frustrating journey of trial and error, talk about how stupid the date handling is, but let’s skip that part and get straight to the solution.

Use ISO 8601 date/time format INCLUDING time zone information (and url encode your values)

That format looks like this, with date, time and timezone.

2018-10-15T00:00:00+01:00

You need to URL encode it though, or else…

2018-10-15T00%3A00%3A00%2B01%3A00

The time zone information HAS TO MATCH the time zone of the ad account, NOT the zone you are in!

How do you find that information?

SnapcHAt Business Interface

Using the Snapchat business interface, go to:

Settings > Ad Accounts > Select Ad Account

Using API

List all organizations for an account:

https://adsapi.snapchat.com/v1/me/organizations

List all ad accounts for an organization:

https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts

Convert that timezone value to a UTC offset.

Whether you get it from API or interface, you need to take that timezone string and look it up somewhere to get the UTC offset (-08:00 in this case).

But wait, what about Daylight Saving Time?

Be aware that Daylight Saving Time (needs to die in a fire, but that’s for another day/rant) WILL affect the current UTC offset!

Failure to account for DST and the effect on UTC offsets will get you this lovely error:

‘Unsupported Stats Query: Timeseries queries with DAY granularity must have a start time that is the start of day (00:00:00) for the account’s timezone. This account’s timezone is: America/Los_Angeles’

If your snapchat account is set to “America/Los_Angeles”, and you want to query data for January 1st, your date parameter should look like this:

2019-01-01T00:00:00.000-08:00

That is because on January 1st , the UTC offset in Los Angeles is -08:00.

However, if you want to query on April 1st, Daylist Saving Time is now in effect in LA, so the UTC offset is now -07:00!

So your date parameter should now look like this:

2019-04-01T00:00:00.000-07:00