Targeting Attribute

Overview

The TargetingAttributeService specifies objects that can be used for targeting. The type of the targeting you want to set is specified by the type field of the targeting attribute object. The supported targeting types are geo targeting (specified by WOEID), GENDER, and DEVICE.

In Gemini, targeting can be applied either at the campaign level or at the ad group level (as indicated by the parentType parameter). If targeting of the same type is not set at a lower level, the lower level inherits targeting settings from its parent. If targeting is set at a lower level, it would override targeting set at the parent level.

Targeting Rules & Logic

Targeting for General Interest and CUSTOM_AUDIENCE types follows the rules and logic of an OR join. That means, if you select General Interest and CUSTOM_AUDIENCE as your targeting types, Gemini will logically look for users corresponding to either General Interest OR Custom Audience.

When you set multiple targeting types, like LOCATION and GEO, the end user must satisfy the conditions of each target to be eligible for an ad serve. This means following an AND join logic. For example, Gender=male and Location=California would only target males in California.

When you set multiple values within a targeting type, the end user must only satisfy the conditions of one of the targets to be eligible for ad serving. Logically, this is would be an OR join. For example, Location=Washington and Location=California would target users in California OR Washington.

Available Attributes

The following table provides details on the available targeting types:

Type In search? In native content streams? Set levels Valid values Default
WOEID Yes Yes
  • Campaign
  • Ad Group
Type WOEID refers to geo targeting. Gemini currently supports valid WOEIDs (location codes) at the country, state, DMA and city levels. For more information on available location targeting values, see the data dictionary service. Note that search campaigns serve only on Yahoo US search properties and apps. If no geo targeting is set for your campaigns and ad groups, they will be targeted globally across all countries by default.
DEVICE Use this targeting type in order to set device bid modifiers. SMARTPHONE alone or TABLET alone are not supported, unless the objective is INSTALL_APP or REENGAGE_APP. If SMARTPHONE and TABLET are set together, then the campaign will run only on mobile. Campaign and Ad Group for regular device targeting (Values: DESKTOP, SMARTPHONE & TABLET). Ad Group only for advanced device targeting (example values: MOBILE_SMART_PHONES_APPLE_IPHONE, MOBILE_SMART_PHONES_SAMSUNG, etc).
  • SMARTPHONE
  • TABLET
  • DESKTOP (available on search only through bid modifiers)
Campaigns run across all devices by default. Note that device targeting can be deleted, but cannot be updated once set.
OS_VERSION No Only for the INSTALL_APP or REENGAGE_APP objective.
  • Ad Group
The device OS version of the targeted users. For more information on the available OS Versions, see the data dictionary service.  
GENDER No Yes
  • Campaign
  • MALE
  • FEMALE
If no gender targeting is set, the campaign will serve to all users.
SEGMENT Yes Yes
  • Campaign
  • Ad Group
The interest of the targeted audience. For more information on the available interests, see the data dictionary service. If no segment targeting is set, campaign will serve to all users.
RADIUS Yes No
  • Campaign
  • Ad Group
This targeting type accepts values in the following format: “latitude, longitude,radius”. These values are all decimals, and the radius should be input in miles with a range of 1-500. For example, to target a 5 mile radius around lat/long 40.961773,-74.000626, the following should be passed to the “value” field: 40.961773,-74.000626,5.0. If no radius targeting is set, the campaign will serve to all locations defined using the WOEID targeting type.
AGE No Yes
  • Campaign
  • Ad Group

The following age ranges can be passed as strings in the value field:

  • 18-24
  • 25-34
  • 35-44
  • 45-54
  • 55-64
  • 65-120
If no age targeting is set, all ages will be targeted.
URL Yes No
  • Campaign
This targeting type allows you to block your search campaign from serving on specific domains. Valid values are URL strings, for example: https://www.blockdomain.com. When setting URL targeting objects exclude should be set to TRUE. If no URL targeting is set, no domains will be blocked and your search campaign will be eligible for all of Gemini search supply.
AD_SCHEDULE Yes Yes
  • Campaign
  • Ad Group
Allows you to set a schedule for your ads to serve on specific days and times of the week. Multiple schedules can be set for a given campaign or ad group. A schedule can consist of both day (MONDAY, TUESDAY…) and time intervals defined by hour (0 to 23) and minutes in 15 minute increments (ZERO, FIFTEEN…). Days and time should be separated by the pipe (|) symbol. Here is an example of scheduling ads to run on Wednesdays and Fridays between 9am and 5:30pm: WEDNESDAY,FRIDAY|9:ZERO-17:THIRTY. Note that spaces are not allowed. The schedule applies to the user’s timezone. If no schedule has been set, then your ads are eligible to show in all relevant auctions throughout each calendar day.
CUSTOM_AUDIENCE Yes Yes
  • Campaign
  • Ad Group
Refer to the custom audience section for details.  
CONNECTION No Only for video ads
  • Ad Group
Allows targeting WIFI or ANY connection types. Applies only to video ads with a CPV price type. Video ads run on all connection types by default.
SUPPLY_GROUP No Yes. Use this targeting type in order to set native bid modifiers by supply.
  • Campaign
  • Ad Group

The following are valid values:

  • GROUP_1_A
  • GROUP_1_B
  • GROUP_2_A
  • GROUP_2_B
  • GROUP_3_A
  • GROUP_3_B
 

v3 Site X Device Targeting

The v3 Gemini API introduces site bid adjustments, or site x device targeting. This allows native advertisers to modify their bids on a per-site, per-device basis on selected sites, and is applicable to native channels-only, as well as VisitWeb or PromoteBrand objectives-only. Site X Device targeting can be set at either the campaign or ad group level.

Note that you can create or delete these targets, but only change the bid modifier.

Important

Site X Device targeting is also supported in the v2 Gemini API.

The following table provides details on the site x device targeting type:

Type In search? In native content streams? Set levels Valid values Default
SITE_X_DEVICE No Yes. Use this targeting type in order to set native bid modifiers by site.
  • Campaign
  • Ad Group

The value must be in the following format: site_name|device_type. For example:

  • HOMEPAGE_US|DESKTOP
  • NEWS_US|MOBILE

The following are valid device types:

  • DESKTOP
  • MOBILE
 

Valid site names for SITE_X_DEVICE targeting

The following are valid site names for site x device targets:

  • MAIL_US
  • HOMEPAGE_US
  • MAIL_APP_2
  • MAIL_APP
  • NEWS_TW
  • MAIL_IN
  • AT&T_MAIL_US_2
  • TUMBLR
  • MONEY_TW
  • HOMEPAGE_TW
  • MAIL_BR_2
  • MAIL_FR
  • MAIL_UK
  • NEWS_US
  • CHEETAH_MOBILE_SECURITY
  • TANGO_ANDROID
  • KK_EMOJI_KEYBOARD
  • TANGO_IOS
  • CLEAN_MASTER
  • FINANCE_US
  • OLX_TESTE_MOBILE
  • CHEETAH_MOBILE_LAUNCHER
  • MAIL_AU
  • MAIL_TW
  • MAIL_ES_2
  • HOMEPAGE_FR
  • OLX_TESTE_DESKTOP
  • SPORTS_US_2
  • BLACKBERRY_MESSENGER
  • GAME
  • HOMEPAGE_HK
  • MAIL_MX_2
  • WORDS_WITH_FRIENDS_WEB
  • CHEETAH_MOBILE_SECURITY_2
  • MAIL_CA
  • MAIL_PH
  • MAIL_AR
  • MAIL_DE
  • SPORTS_US
  • NEWS_TW_2
  • DISCUSS_FORUM
  • MAIL_IT
  • TEXTNOW_ANDROID
  • CHEETAH_MOBILE_LOCKSCREEN
  • MAIL_HK
  • BT_MAIL_UK
  • HOMEPAGE_TW_2
  • CLEAN_MASTER_2
  • WORLD_STAR_HIP_HOP
  • CELEBRITY_US
  • REDDITISFUN_APP
  • FINANCE_APP
  • SCRIBOL
  • NEWS_APP_US_2
  • MAIL_BR
  • NEWS_APP_US_3
  • FANTASY_SPORTS
  • NEWS_FR
  • AVG_ANTIVIRUS
  • TUBIDY
  • DM5
  • NEWS_HK
  • HOMEPAGE_CA
  • WEATHER
  • GMA
  • 123_KUBO
  • HOMEPAGE_UK
  • DM5_2
  • TUBIDY_2
  • HOMEPAGE_IN
  • HOMEPAGE_BR
  • AUCTION_TW
  • TOUCHPAL_KEYBOARD
  • AOL_MAIL
  • MPCS_PHOTO_GALLERY
  • MAIL_SG
  • SKY_MAIL_UK
  • TEXTNOW
  • PHOTO_GRID
  • MAIL_GR
  • MAIL_VN
  • MAIL_MX
  • HOMEPAGE_US_SPANISH
  • CELEBRITY_HK
  • NEWS_APP_US
  • VERIZON_MAIL_US
  • FRONTIER_MAIL_US
  • BLACKBERRY_MESSENGER_2
  • TELEVISION_US
  • NEWS_UK
  • CHEETAH_MOBILE_SECURITY_3
  • CHATOUS_APP
  • UWANTS
  • ANSWERS_US
  • MPCS_GPW
  • IKANMAN
  • MAIL_MY
  • PSAFE_TOTAL
  • DICTIONARY_TW
  • COCO01
  • MAIL_ID
  • TEEPR
  • MAIL_NZ
  • AT&T_MAIL_US
  • STYLE_US
  • MAIL_ES

Fields

The Targeting Attribute object contains the following fields:

Name Description Type Add Update
advertiserId The ID of the advertiser associated with the targeting attribute. long Required Optional (Read-Only)
id The ID of the targeting attribute. long N/A Required
parentId The ID of the targeting attribute parent. long Required Optional
parentType

The type of parent. Value can be:

  • CAMPAIGN
  • ADGROUP
enum Required Optional
status

Valid values:

  • ACTIVE
  • DELETED
  • PAUSED
enum Required Optional
type

The type of targeting attribute. Supported targeting types:

  • GENDER
  • WOEID
  • DEVICE
  • SEGMENT
  • RADIUS

See the table in the TargetingAttribute Overview section for more details.

enum Required Optional
value The actual targeting value. Based on type, this field will either be a string value or a more complex JSON representation. Maximum number of characters is 1000. string Required Optional
exclude Specifies whether to exclude (TRUE) or include (FALSE) for targeting. This is either true for negative targeting or false for positive targeting. boolean Required Optional
bidModifier Bid modifiers allow you to increase or decrease your search campaign bids based on certain targeting types. Refer to the Bid modifiers section below for details on how to use bid modifiers. double Optional, Optional

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/targetingattribute/

Example Representations

Targeting Attribute

{
  "value": "23424977",
  "id": 338497,
  "type": "WOEID",
  "status": "ACTIVE",
  "advertiserId": 87292,
  "parentType": "ADGROUP",
  "parentId": 46756,
  "exclude": "FALSE",
  "bidModifier": null
}

Targeting Attribute Array

[
  {
      "value": "2347573",
      "id": 338508,
      "type": "WOEID",
      "status": "ACTIVE",
      "advertiserId": 87292,
      "parentType": "CAMPAIGN",
      "parentId": 31369,
      "exclude": "FALSE",
      "bidModifier": null
  },
  {
      "value": "2347568",
      "id": 338509,
      "type": "WOEID",
      "status": "ACTIVE",
      "advertiserId": 87292,
      "parentType": "CAMPAIGN",
      "parentId": 31369,
      "exclude": "FALSE",
      "bidModifier": null
  }
]

Targeting Attribute Response

{
  "errors": null,
  "response": {
      "value": "23424977",
      "id": 338497,
      "type": "WOEID",
      "status": "ACTIVE",
      "advertiserId": 87292,
      "parentType": "ADGROUP",
      "parentId": 46756,
      "exclude": "FALSE",
      "bidModifier": null
  }
}

Operations

Read

Method: To retrieve targeting attributes grouped by type for a specific parent, make a GET call with the following parameters:

Name Description Type Required?
parentId The ID of the targeting attribute parent to filter the targeting attributes by (denoted as pi). long Yes
parentType

The type of targeting attribute parent to filter the targeting attributes by (denoted as pt). Valid values are:

  • CAMPAIGN
  • ADGROUP
enum Yes
mr The maximum number of rows to retrieve. int Optional
si The start index or the first element to retrieve. int Optional
type The type of targeting to filter by (denoted as t). enum Optional
value The targeting value. enum Optional
exclude The exclude flag. This is either true for negative targeting or false for positive targeting. string Optional
status The status of the targeting attribute. enum  
advertiserId The id of the targeting attribute that belongs to the advertiser. long  

Important

Only one parentId or advertiserId parameter is allowed to be passed in as a query parameter when retrieving targeting attributes.


Note: The lowest value currently supported is the Device type. Only grouping of targeting attributes that are grouped by type are allowed for a specific parentID, i.e., DEVICE.

For example:

Method: Get the geo targeting for a specific campaign:

https://api.gemini.yahoo.com/v3/rest/targetingattribute/?pi=31369&pt=CAMPAIGN&t=WOEID

Response: The list of targeting attributes based on the given filters:

{
  "errors": null,
  "response": [
      {
          "value": "2347571",
          "id": 338498,
          "type": "WOEID",
          "status": "ACTIVE",
          "advertiserId": 87292,
          "parentType": "CAMPAIGN",
          "parentId": 31369,
          "exclude": "TRUE",
          "bidModifier": null
      },
      {
          "value": "2347577",
          "id": 338500,
          "type": "WOEID",
          "status": "ACTIVE",
          "advertiserId": 87292,
          "parentType": "CAMPAIGN",
          "parentId": 31369,
          "exclude": "FALSE",
           "bidModifier": null
      },
      {
          "value": "2347568",
          "id": 338509,
          "type": "WOEID",
          "status": "ACTIVE",
          "advertiserId": 87292,
          "parentType": "CAMPAIGN",
          "parentId": 31369,
          "exclude": "FALSE",
          "bidModifier": null
      }
  ]
}

Update existing targeting attributes

Method: For targeting attributes, the only fields that can be updated are “status” and “bidModifier”. You can do this by making a PUT call with one or more TargetingAttribute passing the id in the request body. For anything else, including updating the “value” field, the existing targeting attribute must be deleted and new one should be created with the desired values.

Create a new TargetingAttribute

Method: To create a new targeting attribute, make a POST call to the TargetingAttribute endpoint. The response will be the newly created targeting attribute. Batch create is supported; either a targeting attribute or a targeting attribute array can be passed.

For example:

POST  https://api.gemini.yahoo.com/v3/rest/targetingattribute/

Data passed

[
  {
      "advertiserId": 87292,
      "type": "WOEID",
      "parentType": "CAMPAIGN",
      "parentId": 31391,
      "value": 2347573,
      "status": "ACTIVE",
      "exclude": "FALSE"
  },
  {
      "advertiserId": 87292,
      "type": "WOEID",
      "parentType": "CAMPAIGN",
      "parentId": 31391,
      "value": 2347568,
      "status": "ACTIVE",
      "exclude": "FALSE"
  }
]

Example response

{
  "errors": null,
  "response": [
      {
          "value": "2347573",
          "id": 338728,
          "type": "WOEID",
          "status": "ACTIVE",
          "advertiserId": 87292,
          "parentType": "CAMPAIGN",
          "parentId": 31391,
          "exclude": "FALSE",
          "bidModifier": null
      },
      {
          "value": "2347568",
          "id": 338729,
          "type": "WOEID",
          "status": "ACTIVE",
          "advertiserId": 87292,
          "parentType": "CAMPAIGN",
          "parentId": 31391,
          "exclude": "FALSE",
          "bidModifier": null
      }
  ]
}

Delete a TargetingAttribute

Method: To delete a targeting attribute, make a PUT call with the TargetingAttribute object. Batch delete is supported; either a targeting attribute or a targeting attribute array can be passed. The following parameters are required:

Field Description
id The ID of the targeting attribute to delete.
status The status of the targeting attribute set to DELETED to delete the targeting attribute.

Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

PUT  https://api.gemini.yahoo.com/v3/rest/targetingattribute/
DELETE https://api.gemini.yahoo.com/v3/rest/targetingattribute/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/targetingattribute?id=123&id=1234&...

Data passed

{
  "id": 338508,
  "status": "DELETED"
}

Example response

{
  "errors": null,
  "response": {
      "value": "2347573",
      "id": 338508,
      "type": "WOEID",
      "status": "DELETED",
      "advertiserId": 87292,
      "createdDate": 1393816683000,
      "parentType": "CAMPAIGN",
      "parentId": 31369,
      "exclude": "FALSE",
      "bidModifier": null
  }
}

Bid Modifiers

Bid modifiers allow you to increase or decrease your search campaign bids based on certain targeting types. You can do this by leveraging the optional bidModifier field in the TargetingAttribute object. For example, if you are bidding $1 CPC on the keyword “sushi” in campaign id 456, and you want to improve the odds of getting your ad shown to users who have searched for “sushi” on a smartphone, you may choose to increase your bid by 30% for such users by creating the following TargetingAttribute object:

{
  "type": "DEVICE",
  "id": 39698778
  "advertiserId": 31,
  "status": "ACTIVE",
  "parentType": "CAMPAIGN",
  "parentId": 333875672,
  "exclude": "FALSE",
  "value": "SMARTPHONE",
  "bidModifier": 1.3
}

The bidModifier value adjusts your bid by multiplying it. So if, in the example above, the the bid for a smartphone user when the keyword “sushi” is matched would be $1 * 1.3 = $1.3. If the bidModifier was set to 0.5, then the bid would be $1 * 0.5 = $0.5.

Note that multiple bid modifiers may be applied, depending on your campaign settings and on a given impression. For example, if you have an original CPC bid of $1, a 1.3 bidModifier set for smartphones per the above example, and also the following 0.9 bidModifier set for users in California:

{
  "type": "WOEID",
  "id": 35698508,
  "advertiserId": 31,
  "status": "ACTIVE",
  "parentType": "CAMPAIGN",
  "parentId": 333875672,
  "exclude": "FALSE",
  "value": "2347563",
  "bidModifier": 0.9
}

In this case, the bid for a smartphone user in California when the keyword “sushi” is matched would be $1 * 1.3 * 0.9 = $1.17.

The maximum precision for bid modifier values is 2 decimal places. 1 indicates that no bid modifier has been set. The following table provides details on the supported targeting types and values for bid modifiers:

Targeting type Targeting value Bid modifier range Channel
WOEID Any valid WOEID 0.1 - 10.0 Search
RADIUS Any valid radius value 0.1 - 10.0 Search
DEVICE SMARTPHONE 0, 0.1 - 10.0. Note that 0 is a special value which allows you to opt out of smartphone traffic. Search
DEVICE TABLET 0, 0.1 - 10.0. Search
DEVICE DESKTOP 0, 0.1 - 10.0. Search
SITE_X_DEVICE ... 0.2 - 9 Native
SEGMENT Any valid segment id 0.1 - 10.00 Search
CUSTOM_AUDIENCE Any valid custom audience id 0.1 - 10.00 Search
SUPPLY_GROUP GROUP_1_A 1.0 - 5.0 Native
SUPPLY_GROUP GROUP_1_B 0.7 - 5.0 Native
SUPPLY_GROUP GROUP_2_A 0.7 - 5.0 Native
SUPPLY_GROUP GROUP_2_B 0.3 - 5.0 Native
SUPPLY_GROUP GROUP_3_A 0.5 - 5.0 Native
SUPPLY_GROUP GROUP_3_B 0.2 - 5.0 Native

Device bid modifiers

It is important to note that DEVICE bid modifiers are slightly different than bid modifiers for other targeting types. Gemini search campaigns run across all devices in order to maximize your reach - the presence of a bid modifier does not indicate explicit targeting. For example, a $1 CPC bid with a 1.5 bid modifier value for smartphones means that on a smartphone the bid would be modified to $1.5. The ad group will still serve on desktop and tablets with a $1 CPC bid. For other targeting types, bid modifiers imply both targeting as well as bid modification.