Async v1 Stats TON endpoint format clarifications

[hyfn]

Stats created by a batch Async Stats Job (https://dev.twitter.com/ads/reference/1/post/stats/jobs/accounts/%3Aaccount_id) are made available via the GET version of the Jobs API (https://dev.twitter.com/ads/reference/1/get/stats/jobs/accounts/%3Aaccount_id), and the url attribute in the response links to a file in .zip format.

I’m documenting this here because the GET API was not documented until just today, and the TON API https://ton.twimg.com/advertiser-api-async-analytics seems entirely undocumented at this point.

The format of the content available at this API would be more obvious if Twitter returned a Content-Type header; we suggest Content-Type: application/zip. I’d also recommend documenting the download portion in the newly-released V0 -> V1 migration guide https://dev.twitter.com/ads/analytics/migration-guide-v0-v1

Example headers currently returned by https://ton.twimg.com/advertiser-api-async-analytics:
HTTP/1.1 200 OK Date: Thu, 31 Mar 2016 17:42:55 GMT Server: Apache content-md5: S7Vd0EqxMr0lej+1vVYFYw== etag: "S7Vd0EqxMr0lej+1vVYFYw==" expires: Mon, 04 Apr 2016 21:31:38 GMT last-modified: Mon, 28 Mar 2016 21:27:27 GMT x-connection-hash: b443912b9fd4b2c90b6f8e23620040a4 x-response-time: 7 x-ton-expected-size: 332 x-ton-expires: Mon, 04 Apr 2016 21:27:27 GMT Cache-Control: max-age=31536000 Content-Length: 332 Accept-Ranges: bytes Via: 1.1 varnish Age: 245477 X-Served-By: cache-tw-lax1-cr1-3-TWLAX1 X-Cache: HIT X-Content-Type-Options: nosniff

[hwz]

That’s great feedback. We’ll add the details around results files to our GET and POST https://dev.twitter.com/ads/reference/1/get/stats/jobs/accounts/%3Aaccount_id endpoints docs. This is mentioned already in the Analytics Overview, but can certainly be added to the endpoint docs as well for added clarity.

We have no plans to document https://ton.twimg.com/advertiser-api-async-analytics as it’s not a Ads API endpoint, and the expectation is only for developers to fetch the results files from the provided URL via a straightforward GET request. However, we’ll definitely investigate adding a more clear Content-Type to the headers for those files. Stay tuned for updates on that.

[hyfn]

Great! Thanks.

Thanks for pointing out https://dev.twitter.com/ads/analytics, we hadn’t seen those changes yet and it clarifies some things.

[hector_borras]

Hi @hyfn

I highly recommend this service

Twitter API overview - Hitch

[hyfn]

Ha! We’re big fans of API Changelog @hector_borras - it’s vital. Thanks for the tip!

[hector_borras]

Hahahaha

I think it takes more or less 24 to 48 h to send you the update mail!

[msbukkuri]

@hector_borras I think the best thing is to just know the docs and know when you look at them to notice the updates that are put up, for instance the new section for Dynamic Product Ads. The link appeared a week before it showed up on the API Changelog feed.

[hector_borras]

You’re right @msbukkuri !

It’s easier than if it’s a big change, but it is little for instance, a new parameter. With the change log you can detect it sooner.

Also I rely more in an app than in my eyes… Hahahaha

[msbukkuri]

@hector_borras Yep, you’re right on that one. Those ninja and phantom updates!