We have recently discovered a new undocumented requirement in the Ads API and would like some clarification. The Reach Estimate endpoint (https://dev.twitter.com/ads/reference/get/accounts/%3Aaccount_id/reach_estimate) is requiring us to provide 2 countries (any countries) to receive a reach estimate.
If you look at the following twurl and API trace, it is clear from the response “An additional country is required for reach estimation”
twurl -H "https://ads-api.twitter.com/" "/0/accounts/18ce53yrq2p/reach_estimate?product_type=PROMOTED_TWEETS&objective=TWEET_ENGAGEMENTS&locations=6416b8512febefc9" -t opening connection to ads-api.twitter.com...
opened
<- "GET /0/accounts/18ce53yrq2p/reach_estimate?product_type=PROMOTED_TWEETS&objective=TWEET_ENGAGEMENTS&locations=6416b8512febefc9 HTTP/1.1\r\nAccept: */*\r\nUser-Agent: OAuth gem v0.4.7\r\nContent-Type: application/x-www-form-urlencoded\r\nAuthorization: OAuth oauth_consumer_key=\"EC2gKPePluhEBh49u26nA\", oauth_nonce=\"z5hYw50E9C8qEnkMy9cufHAATiV0Za6Bs8Llfl4hdc\", oauth_signature=\"mdbLCve9Krvbo1mp%2BfGT8e%2F%2BKuY%3D\", oauth_signature_method=\"HMAC-SHA1\", oauth_timestamp=\"1457738179\", oauth_token=\"3073813016-2Gxuh05I9karD6Vpj60XQVsPeZ85oXQ8pDhJsYL\", oauth_version=\"1.0\"\r\nConnection: close\r\nHost: ads-api.twitter.com\r\nContent-Length: 0\r\n\r\n"
<- ""
-> "HTTP/1.1 400 Bad Request\r\n"
-> "connection: close\r\n"
-> "content-disposition: attachment; filename=json.json\r\n"
-> "content-length: 132\r\n"
-> "content-type: application/json;charset=utf-8\r\n"
-> "date: Fri, 11 Mar 2016 23:16:19 GMT\r\n"
-> "server: tsa_a\r\n"
-> "set-cookie: guest_id=v1%3A145773817988557211; Domain=.twitter.com; Path=/; Expires=Sun, 11-Mar-2018 23:16:19 UTC\r\n"
-> "strict-transport-security: max-age=631138519\r\n"
-> "x-access-level: read-write-directmessages\r\n"
-> "x-connection-hash: 874cb7e421eaa3f6a2961381119e6fa4\r\n"
-> "x-content-type-options: nosniff\r\n"
-> "x-frame-options: SAMEORIGIN\r\n"
-> "x-rate-limit-limit: 2000\r\n"
-> "x-rate-limit-remaining: 1991\r\n"
-> "x-rate-limit-reset: 1457738672\r\n"
-> "x-response-time: 31\r\n"
-> "x-runtime: 0.02029\r\n"
-> "x-transaction: 651b842d9ae6a8d1\r\n"
-> "x-xss-protection: 1; mode=block\r\n"
-> "\r\n"
reading 132 bytes...
-> ""
-> "{\"errors\":[{\"code\":\"INVALID_PARAMETER\",\"message\":\"An additional country is required for reach estimation\"}],\"request\":{\"params\":{}}}"
{"errors":[{"code":"INVALID_PARAMETER","message":"An additional country is required for reach estimation"}],"request":{"params":{}}}read 132 bytes
Conn close
And when we do provide two countries, the API does respond with a reach estimate:
twurl -H "https://ads-api.twitter.com/" "/0/accounts/18ce53yrq2p/reach_estimate?product_type=PROMOTED_TWEETS&objective=TWEET_ENGAGEMENTS&locations=6416b8512febefc9,96683cc9126741d1" -t
opening connection to ads-api.twitter.com...
opened
<- "GET /0/accounts/18ce53yrq2p/reach_estimate?product_type=PROMOTED_TWEETS&objective=TWEET_ENGAGEMENTS&locations=6416b8512febefc9%2C96683cc9126741d1 HTTP/1.1\r\nAccept: */*\r\nUser-Agent: OAuth gem v0.4.7\r\nContent-Type: application/x-www-form-urlencoded\r\nAuthorization: OAuth oauth_consumer_key=\"EC2gKPePluhEBh49u26nA\", oauth_nonce=\"7ucZ8tx1OHAOMZnCrl3fdyXOtafmKZ8ESQARMk0Y\", oauth_signature=\"gqCfsYmxusp65DAcM1ufIeOVPGE%3D\", oauth_signature_method=\"HMAC-SHA1\", oauth_timestamp=\"1457738166\", oauth_token=\"3073813016-2Gxuh05I9karD6Vpj60XQVsPeZ85oXQ8pDhJsYL\", oauth_version=\"1.0\"\r\nConnection: close\r\nHost: ads-api.twitter.com\r\nContent-Length: 0\r\n\r\n"
<- ""
-> "HTTP/1.1 200 OK\r\n"
-> "connection: close\r\n"
-> "content-disposition: attachment; filename=json.json\r\n"
-> "content-length: 272\r\n"
-> "content-type: application/json;charset=utf-8\r\n"
-> "date: Fri, 11 Mar 2016 23:16:06 GMT\r\n"
-> "server: tsa_a\r\n"
-> "set-cookie: guest_id=v1%3A145773816638987093; Domain=.twitter.com; Path=/; Expires=Sun, 11-Mar-2018 23:16:06 UTC\r\n"
-> "strict-transport-security: max-age=631138519\r\n"
-> "x-access-level: read-write-directmessages\r\n"
-> "x-connection-hash: ecae3be936e8f1adddbad8a25c7c4c09\r\n"
-> "x-content-type-options: nosniff\r\n"
-> "x-frame-options: SAMEORIGIN\r\n"
-> "x-rate-limit-limit: 2000\r\n"
-> "x-rate-limit-remaining: 1992\r\n"
-> "x-rate-limit-reset: 1457738672\r\n"
-> "x-response-time: 199\r\n"
-> "x-runtime: 0.190416\r\n"
-> "x-transaction: bb8c2d7eada6bcdb\r\n"
-> "x-xss-protection: 1; mode=block\r\n"
-> "\r\n"
reading 272 bytes...
-> ""
-> "{\"data_type\":\"reach_estimate\",\"data\":{\"count\":0,\"infinite_bid_count\":57886189},\"request\":{\"params\":{\"locations\":[\"6416b8512febefc9\",\"96683cc9126741d1\"],\"product_type\":\"PROMOTED_TWEETS\",\"objective\":\"TWEET_ENGAGEMENTS\",\"account_id\":\"18ce53yrq2p\",\"followers_of_users\":null}}}"
{"data_type":"reach_estimate","data":{"count":0,"infinite_bid_count":57886189},"request":{"params":{"locations":["6416b8512febefc9","96683cc9126741d1"],"product_type":"PROMOTED_TWEETS","objective":"TWEET_ENGAGEMENTS","account_id":"18ce53yrq2p","followers_of_users":null}}}read 272 bytes
Conn close
We would like to understand why this is a new requirement? And with two countries in place, which country is the reach estimate referring to?