targeting-options

Targeting Options

App Store Categories
Conversation
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.x.com/12/targeting_criteria/app_store_categories

Parameters¶

Name Description

Name	Description
q optional	An optional query to scope a targeting criteria. Omit this parameter to retrive all. Type: string Example: `music`
os_type optional	Scope the results by a specific app store. Type: enum Possible values: `ANDROID`, `IOS`

q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: music

os_type
optional

Scope the results by a specific app store.

Type: enum

Possible values: ANDROID, IOS

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS

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",
      "os_type": "IOS"
    }
  }
}

GET targeting_criteria/conversations¶

Discover available conversation-based targeting criteria for Promoted Products.

Resource URL¶

https://ads-api.x.com/12/targeting_criteria/conversations

Parameters¶

Name Description

Name	Description
conversation_type optional	An optional query to scope to a certain conversation type. Type: enum Possible values: `ACTORS`, `ATHLETES`, `BOOK_GENRES`, `BOOKS`, `BRAND_CATEGORIES`, `BRANDS`, `CELEBRITIES`, `COACHES`, `DIGITAL_CREATORS`, `ENTERTAINMENT_BRANDS`, `ENTERTAINMENT_PERSONALITIES`, `FICTIONAL_CHARACTERS`, `JOURNALISTS`, `LIFESTYLES`, `MOVIE_GENRES`, `MOVIES`, `MUSIC_GENRES`, `MUSICIANS`, `NEWS_STORIES`, `NEWS`, `PERSONS`, `PLACES`, `PODCASTS`, `POLITICAL_AFFILIATIONS`, `POLITICIANS`, `PRODUCTS`, `RADIO_STATIONS`, `SPORTS_LEAGUES`, `SPORTS_PERSONALITIES`, `SPORTS_TEAMS`, `SPORTS`, `TRENDS`, `TV_SHOWS`, `VIDEO_GAME_PLATFORMS`, `VIDEO_GAME_PUBLISHERS`, `VIDEO_GAMES`
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: `8x7v00oow`

conversation_type
optional

An optional query to scope to a certain conversation type.

Type: enum

Possible values: ACTORS, ATHLETES, BOOK_GENRES, BOOKS, BRAND_CATEGORIES, BRANDS, CELEBRITIES, COACHES, DIGITAL_CREATORS, ENTERTAINMENT_BRANDS, ENTERTAINMENT_PERSONALITIES, FICTIONAL_CHARACTERS, JOURNALISTS, LIFESTYLES, MOVIE_GENRES, MOVIES, MUSIC_GENRES, MUSICIANS, NEWS_STORIES, NEWS, PERSONS, PLACES, PODCASTS, POLITICAL_AFFILIATIONS, POLITICIANS, PRODUCTS, RADIO_STATIONS, SPORTS_LEAGUES, SPORTS_PERSONALITIES, SPORTS_TEAMS, SPORTS, TRENDS, TV_SHOWS, VIDEO_GAME_PLATFORMS, VIDEO_GAME_PUBLISHERS, VIDEO_GAMES

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: 8x7v00oow

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2

Example Response¶

{
  "request": {
    "params": {
      "count": 2
    }
  },
  "next_cursor": "1f7m7",
  "data": [
    {
      "targeting_type": "CONVERSATION",
      "targeting_value": "a1",
      "name": "NFL",
      "conversation_type": "SPORTS"
    },
    {
      "targeting_type": "CONVERSATION",
      "targeting_value": "a2",
      "name": "NBA",
      "conversation_type": "SPORTS"
    }
  ]
}

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.x.com/12/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: apple

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone

Example Response¶

{
  "data": [
    {
      "name": "iPhone 3GS",
      "manufacturer": "Apple",
      "os_type": "iOS",
      "targeting_value": "1q",
      "targeting_type": "DEVICE"
    },
    {
      "name": "iPhone 4",
      "manufacturer": "Apple",
      "os_type": "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.

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.x.com/12/targeting_criteria/events

Parameters¶

Name	Description
event_types required	An optional query to scope to certain event types. Type: enum Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS`
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, all events are returned. Type: string
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
end_time optional	The time, expressed in ISO 8601, that the campaign will end. Type: string Example: `2017-10-05T00:00:00Z`
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: `2017-07-05T00:00:00Z`

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/events?count=1

Example Response¶

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "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": {},
      "targeting_value": "1ex",
      "is_global": true,
      "event_type": "HOLIDAY",
      "country_breakdown_percentage": {}
    }
  ],
  "next_cursor": "uww0"
}

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.x.com/12/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: 8x7v00oow

q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: books

Example Request¶

GET https://ads-api.x.com/12/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.x.com/12/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: 8x7v00oow

q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: english

Example Request¶

GET https://ads-api.x.com/12/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: To retrieve specific targetable cities, such as San Francisco or New York, use the CITIES enum with the location_type request parameter.

To target Designated Market Areas (DMAs), use the METROS enum.

Resource URL¶

https://ads-api.x.com/12/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: `JP`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
location_type optional	Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations. Type: enum Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES`
q optional	An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results. Type: string Example: `New York`

Example Request¶

GET https://ads-api.x.com/12/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.x.com/12/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: `US`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
q optional	An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: `Airpeak`

Example Request¶

GET https://ads-api.x.com/12/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.x.com/12/targeting_criteria/platform_versions

Parameters¶

Name Description

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: `jelly bean`

q
optional

An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: jelly bean

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/platform_versions

Example Response¶

{
    "data": [
        {...},
        {
            "name": "Ice Cream Sandwich",
            "number": "4.0",
            "os_type": "Android",
            "targeting_type": "PLATFORM_VERSION",
            "targeting_value": "17"
        },
        {
            "name": "Jelly Bean",
            "number": "4.1",
            "os_type": "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.x.com/12/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: ios, blackberry

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: fr

Example Request¶

GET https://ads-api.x.com/12/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.x.com/12/targeting_criteria/tv_markets

Parameters¶

None

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/tv_markets

Example Response¶

{
  "data": [
    {
      "name": "France",
      "country_code": "FR",
      "locale": "fr-FR"
    },
    {
      "name": "Chile",
      "country_code": "CL",
      "locale": "es-CL"
    },
    {
      "name": "Germany",
      "country_code": "DE",
      "locale": "de-DE"
    },
    {
      "name": "Netherlands",
      "country_code": "NL",
      "locale": "nl-NL"
    },
    {
      "name": "United States",
      "country_code": "US",
      "locale": "en-US"
    },
    {
      "name": "Venezuela",
      "country_code": "VE",
      "locale": "es-VE"
    },
    {
      "name": "Brazil",
      "country_code": "BR",
      "locale": "pt-BR"
    },
    {
      "name": "Mexico",
      "country_code": "MX",
      "locale": "es-MX"
    },
    {
      "name": "Colombia",
      "country_code": "CO",
      "locale": "es-CO"
    },
    {
      "name": "United Kingdom",
      "country_code": "GB",
      "locale": "en-GB"
    },
    {
      "name": "Argentina",
      "country_code": "AR",
      "locale": "es-AR"
    },
    {
      "name": "Japan",
      "country_code": "JP",
      "locale": "ja-JP"
    },
    {
      "name": "Canada",
      "country_code": "CA",
      "locale": "en-CA"
    },
    {
      "name": "Spain",
      "country_code": "ES",
      "locale": "es-ES"
    },
    {
      "name": "Italy",
      "country_code": "IT",
      "locale": "it-IT"
    },
    {
      "name": "United States - Hispanic",
      "country_code": "US",
      "locale": "es-US"
    },
    {
      "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.x.com/12/targeting_criteria/tv_shows

Parameters¶

Name	Description
locale required	A required parameter that specifies the tv_market_locale to query for available TV shows. TV markets are queried based on `locale` returned from the GET targeting_criteria/tv_markets. Type: string Example: `en-US`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `50` Min, Max: `1`, `50`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
q optional	An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results. Type: string Examples: `ios`, `blackberry`

Example Request¶

GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1

Example Response¶

{
  "data": [
    {
      "name": "NewsWatch",
      "targeting_value": 10027243420,
      "genre": "PAID",
      "locales": [
        {
          "language": "en",
          "country": "US"
        }
      ]
    }
  ],
  "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ",
  "request": {
    "params": {
      "locale": {
        "countryCode": "US",
        "languageCode": "en"
      },
      "count": 1,
      "q": "news"
    }
  }
}