Targeting Options
targeting-options

Targeting Options

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
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
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
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"
    }
  }
}