Adds support for Audience Intelligence (#160)

* Added support for Audience Intelligence
* removes untitled
* replaces hardcoded version with `API_VERSION`

Author: tushdante

examples/audience_intelligence.py

@@ -0,0 +1,47 @@
+from twitter_ads.client import Client
+from twitter_ads.audience import AudienceIntelligence
+from twitter_ads.enum import CONVERSATION_TYPE, AUDIENCE_DEFINITION
+
+CONSUMER_KEY = 'your consumer key'
+CONSUMER_SECRET = 'your consumer secret'
+ACCESS_TOKEN = 'access token'
+ACCESS_TOKEN_SECRET = 'access token secret'
+ACCOUNT_ID = 'account id'
+
+# initialize the client
+client = Client(CONSUMER_KEY, CONSUMER_SECRET, ACCESS_TOKEN, ACCESS_TOKEN_SECRET)
+
+# load the advertiser account instance
+account = client.accounts(ACCOUNT_ID)
+
+# create a new instance of AI to get conversations
+ai = AudienceIntelligence(account)
+ai.targeting_inputs = [{
+	  "targeting_type": 'GENDER',
+	  "targeting_value": '2'
+	}, {
+	  "targeting_type": 'AGEBUCKET',
+	  "targeting_value": 'AGE_OVER_50'
+	}]
+ai.conversation_type = CONVERSATION_TYPE.HASHTAG
+ai.audience_definition = AUDIENCE_DEFINITION.TARGETING_CRITERIA
+response = ai.conversations()
+for i in range(0, response.count):
+	ai = response.next()
+	print ai.localized['targeting_type']
+	print ai.localized['targeting_value']
+	print "\n"
+
+# create a new instance of AI to get demographics
+ai = AudienceIntelligence(account)
+ai.targeting_inputs =  [{
+    "targeting_type": 'BROAD_MATCH_KEYWORD',
+    "targeting_value": 'womensmarch2018',
+    "start_time": '2017-12-31'
+	}]
+ai.audience_definition = AUDIENCE_DEFINITION.KEYWORD_AUDIENCE
+response = ai.demographics()
+for key in response.keys():
+	print key
+	print response[key]
+	print "\n"

twitter_ads/audience.py

@@ -9,6 +9,8 @@
 from twitter_ads.cursor import Cursor
 from twitter_ads import API_VERSION
 
+import json
+
 
 class TailoredAudience(Resource):
 
@@ -183,3 +185,67 @@ def delete(self):
 resource_property(TailoredAudiencePermission, 'tailored_audience_id')
 resource_property(TailoredAudiencePermission, 'granted_account_id')
 resource_property(TailoredAudiencePermission, 'permission_level')
+
+
+class AudienceIntelligence(Resource):
+
+    PROPERTIES = {}
+
+    RESOURCE_BASE = '/' + API_VERSION + '/accounts/{account_id}/audience_intelligence/'
+    RESOURCE_CONVERSATIONS = RESOURCE_BASE + 'conversations'
+    RESOURCE_DEMOGRAPHICS = RESOURCE_BASE + 'demographics'
+    METHOD = 'post'
+    HEADERS = {'Content-Type': 'application/json'}
+
+    @classmethod
+    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 conversations(self):
+        """
+        Get the conversation topics for an input targeting criteria
+        """
+        body = {
+            "conversation_type": self.conversation_type,
+            "audience_definition": self.audience_definition,
+            "targeting_inputs": self.targeting_inputs
+        }
+        return self.__get(account=self.account, client=self.account.client, params=json.dumps(body))
+
+    def demographics(self):
+        """
+        Get the demographic breakdown for an input targeting criteria
+        """
+        body = {
+            "audience_definition": self.audience_definition,
+            "targeting_inputs": self.targeting_inputs
+        }
+        resource = self.RESOURCE_DEMOGRAPHICS.format(account_id=self.account.id)
+        response = Request(
+            self.account.client, self.METHOD,
+            resource, headers=self.HEADERS, body=json.dumps(body)).perform()
+        return response.body['data']
+
+
+# tailored audience permission properties
+# read-only
+resource_property(AudienceIntelligence, 'operator_type', readonly=True)
+resource_property(AudienceIntelligence, 'targeting_type', readonly=True)
+resource_property(AudienceIntelligence, 'targeting_value', readonly=True)
+resource_property(AudienceIntelligence, 'localized', readonly=True)
+# writable
+resource_property(AudienceIntelligence, 'conversation_type')
+resource_property(AudienceIntelligence, 'targeting_inputs')
+resource_property(AudienceIntelligence, 'audience_definition')
+# demographics only
+resource_property(AudienceIntelligence, 'start_time', transform=TRANSFORM.TIME)
+resource_property(AudienceIntelligence, 'end_time', transform=TRANSFORM.TIME)

twitter_ads/enum.py

@@ -171,3 +171,14 @@ def enum(**enums):
     REMOVE='REMOVE',
     REPLACE='REPLACE'
 )
+
+AUDIENCE_DEFINITION = enum(
+    KEYWORD_AUDIENCE='KEYWORD_AUDIENCE',
+    TARGETING_CRITERIA='TARGETING_CRITERIA'
+)
+
+CONVERSATION_TYPE = enum(
+    HASHTAG='HASHTAG',
+    HANDLE='TARGETING_CRITERIA',
+    EVENT='EVENT'
+)