Audiences
Audience Intelligence¶
All parameters are sent in the request body and a Content-Type of application/json is required.
The maximum batch size is 30.
POST accounts/:account_id/audience_intelligence/conversations¶
Retrieve audience conversations based on a given conversation_type for a set of targeting_inputs and audience_definition.
Note: For an audience_definition of TARGETING_CRITERIA, the targeting_type must be any combination of AGEBUCKET, GENDER and GEO.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/audience_intelligence/conversations
Parameters¶
| Name | Description |
|---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
conversation_type
required
|
The type of conversation being requested for the given set of
Type: enum Example: |
targeting_inputs
required
|
The set of targeting criteria corresponding to an audience or set of users
This is an array of JSON objects of targeting criteria consisting of
targeting_type and targeting_value pairs |
audience_definition
required
|
The type of inputs used to define the audience. Currently, only the value of
TARGETING_CRITERIA is accepted |
Example Request¶
POST https://ads-api.twitter.com/4/accounts/:account_id/audience_intelligence/conversations
{
"conversation_type": "HASHTAG",
"audience_definition": "TARGETING_CRITERIA",
"targeting_inputs": [{
"targeting_type": "GENDER",
"targeting_value": "2"
}, {
"targeting_type": "AGEBUCKET",
"targeting_value": "AGE_OVER_50"
}]
}
Example Response¶
{
"data": [
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "flashbackfriday",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "flashbackfriday"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "californiawildfires",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "californiawildfires"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "whyiwrite",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "whyiwrite"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "whitelivesmatter",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "whitelivesmatter"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "freerosa",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "freerosa"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "nycstrong",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "nycstrong"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "nationalsandwichday",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "nationalsandwichday"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "throwbackthursday",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "throwbackthursday"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "otd",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "otd"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "electionday",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "electionday"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "alertthedaycarestaff",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "alertthedaycarestaff"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "dayofthegirl",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "dayofthegirl"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "happyhallowen",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "happyhallowen"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "daylightsavingstime",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "daylightsavingstime"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "jfkfiles",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "jfkfiles"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "obamasummit",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "obamasummit"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "twd",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "twd"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "truth",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "truth"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "happiest5wordsentence",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "happiest5wordsentence"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "rip",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "rip"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "maga",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "maga"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "nyc",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "nyc"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "lasvegas",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "lasvegas"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "oneamericaappeal",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "oneamericaappeal"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "puertorico",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "puertorico"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "breaking",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "breaking"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "fridayfeeling",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "fridayfeeling"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "mondaymotivation",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "mondaymotivation"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "metoo",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "metoo"
}
},
{
"operator_type": "EQ",
"targeting_type": "BROAD_KEYWORD",
"targeting_value": "halloween",
"localized": {
"targeting_type": "Keyword",
"targeting_value": "halloween"
}
}
],
"conversation_type": "HASHTAG"
}
POST accounts/:account_id/audience_intelligence/demographics¶
Retrieve the demographic breakdown of an audience based on a given set of targeting_inputs and audience_definition.
Note:
For an audience_definition of KEYWORD_AUDIENCE the targeting_type must be set to BRAOD_MATCH_KEYWORD
For an audience_definition of TARGETING_CRITERIA, the targeting_type must be any combination of AGEBUCKET, GENDER and GEO.
Resource URL¶
https://ads-api.twitter.com/4/accounts/:account_id/audience_intelligence/demographics
Parameters¶
| Name | Description |
|---|---|
account_id
required
|
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: |
targeting_inputs
required
|
The set of targeting criteria corresponding to an audience or set of users
This is an array of JSON objects of targeting criteria consisting of
targeting_type and targeting_value pairs |
audience_definition
required
|
The type of inputs used to define the audience. Currently, only the value of
TARGETING_CRITERIA and KEYWORD_AUDIENCE is accepted |
start_time
sometimes required
|
Scopes the retrieved data to the specified start time
(expressed in ISO-8601). Only valid
with an Type: string Example: |
end_time
sometimes required
|
Scopes the retrieved data to the specified end time
(expressed in ISO-8601). Only valid
with an Type: string Example: |
Example Request¶
POST https://ads-api.twitter.com/2/accounts/:account_id/audience_intelligence/demographics
// using TARGETING_CRITERIA
{
"audience_definition": "TARGETING_CRITERIA",
"targeting_inputs": [{
"targeting_type": "GENDER",
"targeting_value": "2"
}, {
"targeting_type": "AGEBUCKET",
"targeting_value": "AGE_OVER_50"
}]
}
// using KEYWORD_AUDIENCE
{
"audience_definition": "KEYWORD_AUDIENCE",
"targeting_inputs": [{
"targeting_type": "BROAD_MATCH_KEYWORD",
"targeting_value": "womensmarch2018",
"start_time": "2017-12-31",
"end_time": "2018-01-05"
}]
}
Example Response¶
{
"data": {
"tv_shows": {
"results": [
{
"name": "Fútbol Americano de la NFL",
"value": "4m2wijc",
"percentage": 70.47
},
{
"name": "Futebol NFL",
"value": "4lxmqn3",
"percentage": 70.47
},
{
"name": "Saturday Night Live (United States)",
"value": "4le416r",
"percentage": 44.81
},
{
"name": "NFL Football (Canada)",
"value": "4lx1ott",
"percentage": 74.54
},
{
"name": "Fox and Friends",
"value": "4le18vb",
"percentage": 58.04
},
{
"name": "Today (United States)",
"value": "4ldwpw1",
"percentage": 43.58
},
{
"name": "Hannity",
"value": "4le18op",
"percentage": 55.4
},
{
"name": "Morning Joe (United States)",
"value": "4ldwxhe",
"percentage": 55.6
},
{
"name": "NFL Football (United States)",
"value": "4le3u79",
"percentage": 76.17
},
{
"name": "The Rachel Maddow Show (United States)",
"value": "4ldwxic",
"percentage": 56.01
}
]
},
"home_value": {
"results": [
{
"name": "Home value: $99,999 and under",
"value": "Home value: $99,999 and under",
"percentage": 8.26
},
{
"name": "Home value: $300,000 - $499,000",
"value": "Home value: $300,000 - $499,000",
"percentage": 22.48
},
{
"name": "Home value: $500,000 and higher",
"value": "Home value: $500,000 and higher",
"percentage": 26.61
},
{
"name": "Home value: $100,000 - $199,000",
"value": "Home value: $100,000 - $199,000",
"percentage": 24.77
},
{
"name": "Home value: $200,000 - $299,000",
"value": "Home value: $200,000 - $299,000",
"percentage": 17.89
}
],
"match_rate": 41.5,
"source": "Datalogix"
},
"marital_status": {
"results": [],
"match_rate": 13.5,
"source": "Acxiom"
},
"credit_card_holders": {
"results": [],
"match_rate": 11,
"source": "Datalogix"
},
"aftermarket_auto_buyer_types": {
"results": [
{
"name": "Auto parts buyer",
"value": "Auto parts buyer",
"percentage": 36.41
},
{
"name": "Vehicle purchase: 13-24 months ago",
"value": "Vehicle purchase: 13-24 months ago",
"percentage": 15.05
},
{
"name": "Vehicle purchase: 48+ months ago",
"value": "Vehicle purchase: 48+ months ago",
"percentage": 26.7
},
{
"name": "Auto service buyer",
"value": "Auto service buyer",
"percentage": 49.51
},
{
"name": "Vehicle purchase: 7-12 months ago",
"value": "Vehicle purchase: 7-12 months ago",
"percentage": 10.19
},
{
"name": "Vehicle purchase: 37-48 months ago",
"value": "Vehicle purchase: 37-48 months ago",
"percentage": 6.31
},
{
"name": "Vehicle purchase: 25-36 months ago",
"value": "Vehicle purchase: 25-36 months ago",
"percentage": 7.77
},
{
"name": "Vehicle purchase: 0-6 months ago",
"value": "Vehicle purchase: 0-6 months ago",
"percentage": 18.93
}
],
"match_rate": 39.2,
"source": "Datalogix"
},
"metros": {
"results": [
{
"name": "San Francisco-Oakland-San Jose CA, US",
"value": "5122804691e5fecc",
"percentage": 5.1
},
{
"name": "Washington DC, US",
"value": "97e96d6456068c5e",
"percentage": 2.55
},
{
"name": "Dallas-Fort Worth TX, US",
"value": "212620dc7cd34699",
"percentage": 2.94
},
{
"name": "Seattle-Tacoma WA, US",
"value": "724b7141cbd1c731",
"percentage": 3.33
},
{
"name": "Boston MA-Manchester NH, US",
"value": "988257060feb2e4b",
"percentage": 2.94
},
{
"name": "Detroit MI, US",
"value": "fb258467e0f621f3",
"percentage": 1.76
},
{
"name": "Chicago IL, US",
"value": "a922fabd203ea9f4",
"percentage": 2.35
},
{
"name": "New York NY, US",
"value": "b6c2e04f1673337f",
"percentage": 9.61
},
{
"name": "Philadelphia PA, US",
"value": "7466cbad7a909d94",
"percentage": 3.53
},
{
"name": "Los Angeles CA, US",
"value": "e4315a8602024dcb",
"percentage": 9.02
}
]
},
"consumer_buying_styles": {
"results": [],
"match_rate": 35.8,
"source": "Datalogix"
},
"tv_genres": {
"results": [
{
"name": "Drama",
"value": "4",
"percentage": 84.52
},
{
"name": "Children & Family",
"value": "1",
"percentage": 53.97
},
{
"name": "News",
"value": "d",
"percentage": 63.54
},
{
"name": "Sports",
"value": "b",
"percentage": 87.98
},
{
"name": "Talk",
"value": "c",
"percentage": 85.34
},
{
"name": "Documentary & Special Interest",
"value": "3",
"percentage": 46.23
},
{
"name": "Movies",
"value": "5",
"percentage": 60.29
},
{
"name": "Reality",
"value": "8",
"percentage": 55.8
},
{
"name": "Sci-fi",
"value": "9",
"percentage": 53.36
},
{
"name": "Comedy",
"value": "2",
"percentage": 78.21
}
]
},
"regions": {
"results": [
{
"name": "Virginia, US",
"value": "5635c19c2b5078d1",
"percentage": 3.33
},
{
"name": "New York, US",
"value": "94965b2c45386f87",
"percentage": 8.63
},
{
"name": "California, US",
"value": "fbd6d2f5a4e4a15e",
"percentage": 17.25
},
{
"name": "Illinois, US",
"value": "f54a2170ff4b15f7",
"percentage": 2.94
},
{
"name": "Florida, US",
"value": "4ec01c9dbc693497",
"percentage": 3.14
},
{
"name": "Ontario, CA",
"value": "89b2eb8b2b9847f7",
"percentage": 3.33
},
{
"name": "Texas, US",
"value": "e0060cda70f5f341",
"percentage": 5.1
},
{
"name": "Pennsylvania, US",
"value": "dd9c503d6c35364b",
"percentage": 4.71
},
{
"name": "Washington, US",
"value": "bc3a38d3d5999b4b",
"percentage": 3.73
},
{
"name": "New Jersey, US",
"value": "65b4760a2b411e11",
"percentage": 3.33
}
]
},
"countries": {
"results": [
{
"name": "Turkey",
"value": "682c5a667856ef42",
"percentage": 0.2
},
{
"name": "Iraq",
"value": "b62cd77425868341",
"percentage": 0.2
},
{
"name": "Italy",
"value": "c799e2d3a79f810e",
"percentage": 0.59
},
{
"name": "Germany",
"value": "fdcd221ac44fa326",
"percentage": 0.98
},
{
"name": "Canada",
"value": "3376992a082d67c7",
"percentage": 6.27
},
{
"name": "United States",
"value": "96683cc9126741d1",
"percentage": 87.45
},
{
"name": "United Kingdom",
"value": "6416b8512febefc9",
"percentage": 1.18
},
{
"name": "India",
"value": "b850c1bfd38f30e0",
"percentage": 0.39
},
{
"name": "Norway",
"value": "0ce8b9a7b2742f7e",
"percentage": 0.39
},
{
"name": "Netherlands",
"value": "879d7cfc66c9c290",
"percentage": 0.39
}
]
},
"political_affiliation": {
"results": []
},
"languages": {
"results": [
{
"name": "English",
"value": "en",
"percentage": 100
},
{
"name": "Italian",
"value": "it",
"percentage": 0.38
},
{
"name": "Spanish",
"value": "es",
"percentage": 0.95
},
{
"name": "Hindi",
"value": "hi",
"percentage": 0.19
},
{
"name": "German",
"value": "de",
"percentage": 0.19
},
{
"name": "Arabic",
"value": "ar",
"percentage": 0.38
},
{
"name": "French",
"value": "fr",
"percentage": 0.38
},
{
"name": "Norwegian",
"value": "no",
"percentage": 0.19
},
{
"name": "Finnish",
"value": "fi",
"percentage": 0.19
},
{
"name": "Japanese",
"value": "ja",
"percentage": 0.19
}
]
},
"education": {
"results": [],
"match_rate": 9.9,
"source": "Acxiom"
},
"network_operators": {
"results": [
{
"name": "Telus(Kudoo, Public mobile)",
"value": "a0",
"percentage": 5.25
},
{
"name": "Sprint",
"value": "1v",
"percentage": 12.98
},
{
"name": "Verizon",
"value": "2b",
"percentage": 41.16
},
{
"name": "Rogers Wireless",
"value": "8",
"percentage": 6.91
},
{
"name": "Vodafone UK",
"value": "4e",
"percentage": 1.93
},
{
"name": "Bell(Virgin mobile)",
"value": "a1",
"percentage": 4.97
},
{
"name": "U.S. Cellular",
"value": "3m",
"percentage": 2.21
},
{
"name": "T-Mobile",
"value": "11",
"percentage": 24.03
},
{
"name": "T-Mobile UK",
"value": "4r",
"percentage": 2.21
},
{
"name": "AT&T",
"value": "1d",
"percentage": 49.17
}
]
},
"net_worth": {
"results": [],
"match_rate": 8.6,
"source": "Acxiom"
},
"interests": {
"results": [
{
"name": "Business news and general info",
"value": "4n4",
"percentage": 83.04
},
{
"name": "Political elections",
"value": "8hp",
"percentage": 79.77
},
{
"name": "Government",
"value": "4mt",
"percentage": 65.32
},
{
"name": "Comedy (Movies and television)",
"value": "1jp",
"percentage": 80.15
},
{
"name": "Financial news",
"value": "cck",
"percentage": 57.42
},
{
"name": "Books news and general info",
"value": "s2",
"percentage": 57.03
},
{
"name": "Business and news",
"value": "1jo",
"percentage": 93.45
},
{
"name": "Movie news and general info",
"value": "1k0",
"percentage": 82.66
},
{
"name": "Business and finance",
"value": "ru",
"percentage": 55.68
},
{
"name": "Politics and current events",
"value": "s0",
"percentage": 95.57
}
]
},
"household_income_categories": {
"results": [
{
"name": "Household income: $75,000 - $99,999",
"value": "Household income: $75,000 - $99,999",
"percentage": 15.13
},
{
"name": "Household income: $200,000 - $249,999",
"value": "Household income: $200,000 - $249,999",
"percentage": 10.33
},
{
"name": "Household income: $150,000 - $199,999",
"value": "Household income: $150,000 - $199,999",
"percentage": 9.96
},
{
"name": "Household income: $100,000 - $124,999",
"value": "Household income: $100,000 - $124,999",
"percentage": 16.97
},
{
"name": "Household income: $200,000 - $249,999",
"value": "Household income: $200,000 - $249,999",
"percentage": 8.49
}
],
"match_rate": 51.6,
"source": "Acxiom"
},
"consumer_goods_purchases": {
"results": [
{
"name": "Chocolate candy",
"value": "Chocolate candy",
"percentage": 38.43
},
{
"name": "Yogurt",
"value": "Yogurt",
"percentage": 40.39
},
{
"name": "Milk",
"value": "Milk",
"percentage": 43.53
},
{
"name": "Salty snacks",
"value": "Salty snacks",
"percentage": 42.35
},
{
"name": "Cheese",
"value": "Cheese",
"percentage": 43.14
},
{
"name": "Beer",
"value": "Beer",
"percentage": 38.04
},
{
"name": "Crackers",
"value": "Crackers",
"percentage": 41.18
},
{
"name": "Eggs",
"value": "Eggs",
"percentage": 43.92
},
{
"name": "Meat",
"value": "Meat",
"percentage": 40
},
{
"name": "Fresh produce",
"value": "Fresh produce",
"percentage": 40.78
}
],
"match_rate": 48.6,
"source": "Datalogix"
},
"occupation": {
"results": [],
"match_rate": 22.3,
"source": "Datalogix"
},
"devices": {
"results": [
{
"name": "iOS",
"value": "Ios",
"percentage": 52.27
},
{
"name": "Android",
"value": "Android",
"percentage": 34.12
},
{
"name": "Other mobile",
"value": "OtherMobile",
"percentage": 0.59
},
{
"name": "Desktop",
"value": "Desktop",
"percentage": 91.52
}
]
},
"gender": {
"results": [
{
"name": "Male",
"value": "Male",
"percentage": 23.39
},
{
"name": "Female",
"value": "Female",
"percentage": 76.61
}
]
}
}
}
