def attach(klass, account, **kwargs):
"""
Associate one or more Tweets with the specified line item.
"""
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'post', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
def load(klass, account, tweet_ids=None, tweet_type=None):
params = {}
params['tweet_ids'] = ','.join(map(str, tweet_ids))
params['tweet_type'] = tweet_type
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=params)
return Cursor(klass, request, init_with=[account])
def async_stats_job_result(klass, account, **kwargs):
"""
Returns the results of the specified async job IDs
"""
resource = klass.RESOURCE_ASYNC.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(Analytics, request, init_with=[account])
def all(klass, account, tailored_audience_id, **kwargs):
"""Returns a Cursor instance for the given tailored audience permission resource."""
resource = klass.RESOURCE_COLLECTION.format(
account_id=account.id, tailored_audience_id=tailored_audience_id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
def all(klass, account, custom_audience_id, **kwargs):
"""Returns a Cursor instance for the given targeted custom audience resource."""
resource = klass.RESOURCE.format(
account_id=account.id,
custom_audience_id=custom_audience_id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
def all(klass, account, line_item_ids, **kwargs):
"""Returns a Cursor instance for a given resource."""
params = {'line_item_ids': ','.join(line_item_ids)}
params.update(kwargs)
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=params)
return Cursor(klass, request, init_with=[account])
def get_resource(stream_name, client, path, params=None):
resource = '/{}/{}'.format(API_VERSION, path)
try:
request = Request(client, 'get', resource, params=params) #, stream=True)
except Error as err:
# see twitter_ads.error for more details
LOGGER.error('Stream: {} - ERROR: {}'.format(stream_name, err.details))
raise err
cursor = Cursor(None, request)
return cursor
def __get(klass, account, client, params):
"""
Helper function to get the conversation data
Returns a Cursor instance
"""
resource = klass.RESOURCE_CONVERSATIONS.format(account_id=account.id)
request = Request(
account.client, klass.METHOD,
resource, headers=klass.HEADERS, body=params)
return Cursor(klass, request, init_with=[account])
def get_published_tweets(self):
"""
Step 1 of 'ENTITY - CARD' report generation process:
Returns details on 'PUBLISHED' tweets, as a generator of dictionaries
Documentation: https://developer.twitter.com/en/docs/ads/creatives/api-reference/tweets
"""
resource = f"/{API_VERSION}/accounts/{self.account.id}/tweets"
params = {"tweet_type": "PUBLISHED"}
request = Request(self.client, "get", resource, params=params)
yield from Cursor(None, request)
def status(self):
"""
Returns the status of all changes for the current tailored audience instance.
"""
if not self.id:
return None
resource = self.RESOURCE_UPDATE.format(account_id=self.account.id)
request = Request(self.account.client, 'get', resource, params=self.to_params())
cursor = list(Cursor(None, request))
return filter(lambda change: change['tailored_audience_id'] == self.id, cursor)
def async_stats_job_result(klass, account, job_ids=None, **kwargs):
"""
Returns the results of the specified async job IDs
"""
params = {}
params.update(kwargs)
if isinstance(job_ids, list):
params['job_ids'] = ','.join(map(str, job_ids))
resource = klass.RESOURCE_ASYNC.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=params)
return Cursor(None, request, init_with=[account])
def load(klass, account, **kwargs):
# check whether both are specified or neither are specified
if all([kwargs.get('card_uris'), kwargs.get('card_id')]) or \
not any([kwargs.get('card_uris'), kwargs.get('card_id')]):
raise ValueError('card_uris and card_id are exclusive parameters. ' +
'Please supply one or the other, but not both.')
if kwargs.get('card_uris'):
resource = klass.FETCH_URI.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
else:
resource = klass.FETCH_ID.format(account_id=account.id, id=kwargs.get('card_id'))
response = Request(account.client, 'get', resource, params=kwargs).perform()
return klass(account).from_response(response.body['data'])
def load(klass, account, card_uris=None, card_id=None, with_deleted=None):
# check whether both are specified or neither are specified
if all([card_uris, card_id]) or not any([card_uris, card_id]):
raise ValueError(
'card_uris and card_id are exclusive parameters. ' +
'Please supply one or the other, but not both.')
params = {}
if with_deleted:
params['with_deleted'] = 'true'
if card_uris:
params['card_uris'] = ','.join(card_uris)
resource = klass.FETCH_URI.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=params)
return Cursor(klass, request, init_with=[account])
else:
params['card_id'] = card_id
resource = klass.FETCH_ID.format(account_id=account.id, id=card_id)
response = Request(account.client, 'get', resource,
params=params).perform()
return klass(account).from_response(response.body['data'])
def get_reach_report(self):
"""
Get 'REACH' report through the 'Reach and Average Frequency' endpoint of Twitter Ads API.
Documentation: https://developer.twitter.com/en/docs/ads/analytics/api-reference/reach
"""
resource = f"/{API_VERSION}/stats/accounts/{self.account.id}/reach/{self.entity.lower()}s"
entity_ids = self.get_active_entity_ids()
for chunk_entity_ids in split_list(entity_ids, MAX_ENTITY_IDS_PER_JOB):
try:
params = {
"account_id": self.account.id,
f"{self.entity.lower()}_ids": ",".join(entity_ids),
"start_time": self.start_date.strftime(API_DATEFORMAT),
"end_time": self.end_date.strftime(API_DATEFORMAT),
}
request = Request(self.client, "get", resource, params=params)
yield from Cursor(None, request)
except Exception:
ex_type, ex, tb = sys.exc_info()
logger.warning(
f"Failed to ingest post with error: {ex}. Traceback: {traceback.print_tb(tb)}"
)
def network_operators(klass, account, **kwargs):
"""Returns a list of supported network operators"""
resource = klass.RESOURCE_OPTIONS + 'network_operators'
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def locations(klass, account, **kwargs):
"""Returns a list of supported locations"""
resource = klass.RESOURCE_OPTIONS + 'locations'
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def behavior_taxonomies(klass, account, **kwargs):
"""Returns a list of supported behavior taxonomies"""
resource = klass.RESOURCE_OPTIONS + 'behavior_taxonomies'
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def app_store_categories(klass, account, **kwargs):
"""Returns a list of supported app store categories"""
resource = klass.RESOURCE_OPTIONS + 'app_store_categories'
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def tv_markets(klass, account, **kwargs):
"""Returns a list of supported TV markets"""
resource = klass.RESOURCE_OPTIONS + 'tv_markets'
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def all(klass, client, **kwargs):
"""Returns a Cursor instance for a given resource."""
resource = klass.RESOURCE_COLLECTION
request = Request(client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[client])
# load up the account instance
account = client.accounts(ADS_ACCOUNT)
# using the Request object you can manually request any
# twitter ads api resource that you want.
resource = '/' + API_VERSION + '/accounts/{account_id}/features'.format(
account_id=account.id)
params = {'feature_keys': 'AGE_TARGETING,CPI_CHARGING'}
# try, build and execute the request with error handling
try:
response = Request(client, 'get', resource, params=params).perform()
print(response.body['data'][0])
except Error as e:
# see twitter_ads.error for more details
print(e.details)
raise
# you can also manually construct requests to be
# used in Cursor objects.
resource = '/' + API_VERSION + '/targeting_criteria/locations'
params = {'location_type': 'CITIES', 'q': 'port'}
request = Request(client, 'get', resource, params=params)
cursor = Cursor(None, request)
# execute requests and iterate cursor until exhausted
for obj in cursor:
print(obj['name'])
def all(klass, account, **kwargs):
"""Returns a Cursor instance for a given resource."""
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
def all(klass, account, **kwargs):
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(None, request)
def load(klass, account, **kwargs):
resource = klass.RESOURCE_COLLECTION.format(account_id=account.id)
request = Request(account.client, 'get', resource, params=kwargs)
return Cursor(klass, request, init_with=[account])
