Campaign Management
Targeting Options¶
- App Store Categories
- Behavior Taxonomies
- Behaviors
- Devices
- Events
- Interests
- Languages
- Locations
- Network Operators
- Platform Versions
- Platforms
- TV Markets
- TV Shows
GET targeting_criteria/app_store_categories¶
Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only.
Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/app_store_categories
Parameters¶
Name | Description |
---|---|
q
optional
|
An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: |
store
optional
|
Scope the results by a specific app store. Type: enum Possible values: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/app_store_categories?q=music&store=IOS_APP_STORE
Example Response¶
{
"data": [
{
"name": "Games: Music",
"targeting_type": "APP_STORE_CATEGORY",
"targeting_value": "qouq",
"os_type": "IOS"
},
{
"name": "Music",
"targeting_type": "APP_STORE_CATEGORY",
"targeting_value": "qov2",
"os_type": "IOS"
}
],
"request": {
"params": {
"q": "music",
"store": "IOS_APP_STORE"
}
}
}
GET targeting_criteria/behavior_taxonomies¶
This endpoint is used to list the full (or partial) structure of behavior taxonomy trees.
When building the complete taxonomy structure in your UI, please ensure you compare the results from the taxonomy against the behaviors obtained via the GET targeting_critertia/behaviors endpoint.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/behavior_taxonomies
Parameters¶
Name | Description |
---|---|
behavior_taxonomy_ids
optional
|
Scope the response to just the desired behavior taxonomies by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: |
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
parent_behavior_taxonomy_ids
optional
|
Scope the response to just the behavior taxonomies under specific parent nodes by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided Type: string Example: |
sort_by
optional
|
Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: |
with_total_count
optional
|
Include the Note: This parameter will be ignored if Note: Requests which include Type: boolean Default:
false Possible values:
true , false |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/behavior_taxonomies?behavior_taxonomy_ids=5e
Example Response¶
{
"data": [
{
"name": "Travel services",
"parent_id": "31",
"id": "5e",
"created_at": "2015-01-21T21:51:28Z",
"updated_at": "2015-01-21T21:51:28Z"
}
],
"next_cursor": null,
"request": {
"params": {
"behavior_taxonomy_ids": [
"5e"
]
}
}
}
GET targeting_criteria/behaviors¶
Discover available behavior-based targeting criteria for Promoted Products.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/behaviors
Parameters¶
Name | Description |
---|---|
behavior_ids
optional
|
Scope the response to just the desired behaviors by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: |
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
country_code
optional
|
An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned. Type: string Default: |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
sort_by
optional
|
Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: |
with_total_count
optional
|
Include the Note: This parameter will be ignored if Note: Requests which include Type: boolean Default:
false Possible values:
true , false |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/behaviors?behavior_ids=lfrt
Example Response¶
{
"data": [
{
"name": "Auto service buyer",
"targetable_types": [
"BEHAVIOR",
"NEGATIVE_BEHAVIOR",
"BEHAVIOR_LOOKALIKE_EXPANDED"
],
"country_code": "US",
"id": "lfrt",
"partner_source": "Datalogix",
"behavior_taxonomy_id": "2",
"audience_size": 9583030
}
],
"next_cursor": null,
"request": {
"params": {
"behavior_ids": [
"lfrt"
]
}
}
}
GET targeting_criteria/devices¶
Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/devices
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
q
optional
|
An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/devices?count=2&q=iphone
Example Response¶
{
"data": [
{
"name": "iPhone 3GS",
"manufacturer": "Apple",
"platform": "iOS",
"targeting_value": "1q",
"targeting_type": "DEVICE"
},
{
"name": "iPhone 4",
"manufacturer": "Apple",
"platform": "iOS",
"targeting_value": "1r",
"targeting_type": "DEVICE"
}
],
"request": {
"params": {
"q": "iphone",
"count": 2
}
}
}
GET targeting_criteria/events¶
Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item.
Event targeting is currently immutable and not supported on the PUT accounts/:account_id/targeting_criteria endpoint.
Note: Events often exist across timezones, leading to complications when
considering event times from cross-timezone perspectives. To simplify this, all
event start_time
and end_time
values on this endpoint are represented in
UTC±00:00, irrespective of the event’s locale and timezone. This design should
be kept in mind when querying and interacting with event start_time
and end_time
values. For example, Independence Day for the US is represented
as start_time=2017-07-04T00:00:00Z
and end_time=2017-07-05T00:00:00Z
in UTC±00:00, and thus avoids the issue of this holiday existing across multiple
timezones within the US.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/events
Parameters¶
Name | Description |
---|---|
event_types
required
|
An optional query to scope to certain event types. Type: enum Possible values: |
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
country_codes
optional
|
An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned. Type: string Default: |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
end_time
optional
|
The time, expressed in ISO 8601, that the campaign will end. Type: string Example: |
ids
optional
|
Scope the response to just the desired events by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: |
start_time
optional
|
The time, expressed in ISO 8601, that the line item will begin serving. Note: Defaults to the current time. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/events?ids=lex
Example Response¶
{
"request": {
"params": {
"ids": [
"1ex"
]
}
},
"data_type": "events",
"data": [
{
"reach": {
"total_reach": null
},
"name": "New Year's",
"start_time": "2017-12-31T00:00:00Z",
"top_users": [],
"top_tweets": [],
"top_hashtags": [],
"gender_breakdown_percentage": {},
"end_time": "2018-01-02T00:00:00Z",
"country_code": null,
"device_breakdown_percentage": {},
"id": "1ex",
"is_global": true,
"event_type": "HOLIDAY",
"country_breakdown_percentage": {}
}
],
"next_cursor": null
}
GET targeting_criteria/interests¶
Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/interests
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
q
optional
|
An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/interests?q=books
Example Response¶
{
"data": [
{
"name": "Books and literature/Biographies and memoirs",
"targeting_type": "INTEREST",
"targeting_value": "1001"
}
],
"request": {
"params": {
"q": "books",
"count": 1
}
},
"next_cursor": "6by4n4"
}
GET targeting_criteria/languages¶
Discover languages available for targeting.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/languages
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
q
optional
|
An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/languages?q=english
Example Response¶
{
"data": [
{
"name": "English",
"targeting_type": "LANGUAGE",
"targeting_value": "en"
}
],
"request": {
"params": {
"q": "english"
}
},
"next_cursor": null
}
GET targeting_criteria/locations¶
Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level.
Note: The location_type
enums are now plural. COUNTRY
is now
COUNTRIES
, REGION
is now REGIONS
, and so on.
Note: Version 2 makes it possible to target specific cities (only for
ads accounts that have been granted the CITY_TARGETING
account feature),
such as San Francisco or New York, using the CITIES
enum. In version 1, cities
(the CITY
enum) referred to Designated Market Areas (DMA) or “metros.” To
target these metro areas in version 2, use the METROS
enum.
Note: City targeting is only available for cities in the US.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/locations
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
country_code
optional
|
An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries. Type: string Example: |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
location_type
optional
|
Scope the results by a specific kind of location. More granular targeting than
Type: enum Possible values: |
q
optional
|
An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/locations?location_type=CITIES&q=los angeles
Example Response¶
{
"data": [
{
"name": "Los Angeles, Los Angeles CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "3b77caf94bfc81fe",
"targeting_type": "LOCATION"
},
{
"name": "East Los Angeles, Los Angeles CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "67571a7baaa5906b",
"targeting_type": "LOCATION"
},
{
"name": "Lake Los Angeles, Los Angeles CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "ea9bfbd43c93400f",
"targeting_type": "LOCATION"
},
{
"name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "a2de7c70b82b0ca0",
"targeting_type": "LOCATION"
},
{
"name": "Los Altos, Monterey-Salinas CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "6a4364ea6f987c10",
"targeting_type": "LOCATION"
},
{
"name": "Los Banos, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "b1b6fc646de75904",
"targeting_type": "LOCATION"
},
{
"name": "Los Alamitos, Los Angeles CA, CA, USA",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "0799ff0a3c1006e9",
"targeting_type": "LOCATION"
},
{
"name": "Los Angeles, US",
"country_code": "US",
"location_type": "CITIES",
"targeting_value": "019940ae78c7b3bc",
"targeting_type": "LOCATION"
}
],
"request": {
"params": {
"location_type": "CITIES",
"q": "los angeles"
}
},
"next_cursor": null
}
GET targeting_criteria/network_operators¶
Discover available network operator-based targeting criteria for Promoted Products.
This endpoint enables you to lookup targetingable carriers, such as AT&T, Verizon, Sprint, T-Mobile, etc., in multiple countries.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/network_operators
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
country_code
optional
|
An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned. Type: string Default: |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
q
optional
|
An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/network_operators?count=5&country_code=US
Example Response¶
{
"data": [
{
"country_code": "US",
"targeting_type": "NETWORK_OPERATOR",
"name": "Advantage",
"targeting_value": "2l"
},
{
"country_code": "US",
"targeting_type": "NETWORK_OPERATOR",
"name": "Aeris",
"targeting_value": "1b"
},
{
"country_code": "US",
"targeting_type": "NETWORK_OPERATOR",
"name": "Airadigm",
"targeting_value": "2t"
},
{
"country_code": "US",
"targeting_type": "NETWORK_OPERATOR",
"name": "Airlink PCS",
"targeting_value": "14"
},
{
"country_code": "US",
"targeting_type": "NETWORK_OPERATOR",
"name": "Airpeak",
"targeting_value": "1i"
}
],
"request": {
"params": {
"country_code": "US",
"count": 5
}
},
"next_cursor": "o7x9iet1a5u608olj4"
}
GET targeting_criteria/platform_versions¶
Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/platform_versions
Parameters¶
Name | Description |
---|---|
q
optional
|
An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/platform_versions
Example Response¶
{
"data": [
{...},
{
"name": "Ice Cream Sandwich",
"number": "4.0",
"platform": "Android",
"targeting_type": "PLATFORM_VERSION",
"targeting_value": "17"
},
{
"name": "Jelly Bean",
"number": "4.1",
"platform": "Android",
"targeting_type": "PLATFORM_VERSION",
"targeting_value": "18"
},
{...}
],
"data_type": "targeting_criterion",
"request": {
"params": {}
}
}
GET targeting_criteria/platforms¶
Discover available platform-based targeting criteria for Promoted Products.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/platforms
Parameters¶
Name | Description |
---|---|
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
q
optional
|
An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: |
lang
optional
|
Using a ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response. Type: int, string Example: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/platforms
Example Response¶
{
"data": [
{
"name": "iOS",
"targeting_type": "PLATFORM",
"targeting_value": "0"
},
{
"name": "Android",
"targeting_type": "PLATFORM",
"targeting_value": "1"
},
{
"name": "BlackBerry phones and tablets",
"targeting_type": "PLATFORM",
"targeting_value": "2"
},
{
"name": "Mobile web on other devices",
"targeting_type": "PLATFORM",
"targeting_value": "3"
},
{
"name": "Desktop and laptop computers",
"targeting_type": "PLATFORM",
"targeting_value": "4"
}
],
"request": {
"params": {}
}
}
GET targeting_criteria/tv_markets¶
Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the GET targeting_criteria/tv_shows endpoint.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/tv_markets
Parameters¶
None
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/tv_markets
Example Response¶
{
"data": [
{
"id": "6",
"name": "France",
"country_code": "FR",
"locale": "fr-FR"
},
{
"id": "i",
"name": "Chile",
"country_code": "CL",
"locale": "es-CL"
},
{
"id": "a",
"name": "Germany",
"country_code": "DE",
"locale": "de-DE"
},
{
"id": "p",
"name": "Netherlands",
"country_code": "NL",
"locale": "nl-NL"
},
{
"id": "1",
"name": "United States",
"country_code": "US",
"locale": "en-US"
},
{
"id": "k",
"name": "Venezuela",
"country_code": "VE",
"locale": "es-VE"
},
{
"id": "5",
"name": "Brazil",
"country_code": "BR",
"locale": "pt-BR"
},
{
"id": "d",
"name": "Mexico",
"country_code": "MX",
"locale": "es-MX"
},
{
"id": "g",
"name": "Colombia",
"country_code": "CO",
"locale": "es-CO"
},
{
"id": "2",
"name": "United Kingdom",
"country_code": "GB",
"locale": "en-GB"
},
{
"id": "c",
"name": "Argentina",
"country_code": "AR",
"locale": "es-AR"
},
{
"id": "9",
"name": "Japan",
"country_code": "JP",
"locale": "ja-JP"
},
{
"id": "3",
"name": "Canada",
"country_code": "CA",
"locale": "en-CA"
},
{
"id": "7",
"name": "Spain",
"country_code": "ES",
"locale": "es-ES"
},
{
"id": "b",
"name": "Italy",
"country_code": "IT",
"locale": "it-IT"
},
{
"id": "4",
"name": "United States - Hispanic",
"country_code": "US",
"locale": "es-US"
},
{
"id": "f",
"name": "Ireland",
"country_code": "IE",
"locale": "en-IE"
}
],
"request": {
"params": {}
}
}
GET targeting_criteria/tv_shows¶
Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the GET targeting_criteria/tv_markets endpoint for available markets.
Note: Any audience that contains fewer than 1,000 users will appear with an
estimated_users
value of 1000
.
Note: TV channel and genre targeting options are no longer supported.
Resource URL¶
https://ads-api.twitter.com/3/targeting_criteria/tv_shows
Parameters¶
Name | Description |
---|---|
tv_market_locale
required
|
A required parameter that specifies the tv_market_locale to query for available
TV shows. TV markets are queried based on Type: string Example: |
count
optional
|
Specifies the number of records to try and retrieve per distinct request. Type: int Default:
200 Min, Max:
1 , 1000 |
cursor
optional
|
Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: |
q
optional
|
An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: |
Example Request¶
GET https://ads-api.twitter.com/3/targeting_criteria/tv_shows?tv_market_locale=en-US&q=news&count=1
Example Response¶
{
"request": {
"params": {}
},
"data": [
{
"name": "BBC World News",
"id": 10002546242,
"estimated_users": 1000,
"genre": "NEWS"
},
{
"name": "E! News",
"id": 10000283242,
"estimated_users": 977634,
"genre": "TALK"
}
],
"data_type": "targeting_criterion",
"total_count": 77,
"next_cursor": "c-2"
}