Targeting Attribute¶
Abstract¶
The TargetingAttributeService specifies objects that can be used for targeting.
Overview¶
Targeting can be applied either at the campaign or 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.
To set the targeting type, you specify the field type of the targeting attribute object. The supported targeting types are described in the table below.
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, Native 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.
Important
There is a 10,000 maximum limit when using WOEID codes applied to location targeting for campaigns or adgroups. Once you reach that limit and go beyond it, an error message is returned, indicating that you’ve exceeded the limit. You could use Designated Market Area (for example, San Francisco Bay Area) or city targeting to help reduce the number of location targets that would otherwise exceed those limits, particularly if you’re using zipcodes.
Endpoint¶
Resource URI
https://api.gemini.yahoo.com/v3/rest/targetingattribute/
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 |
|
Type WOEID refers to geo targeting. Yahoo Native API currently supports valid WOEIDs (location codes) at the country, state, DMA and city levels. Zip code level targeting is also available. 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). |
|
Campaigns run across all devices by default. Note that device targeting can be deleted, but cannot be updated once set. |
SITE_X_DEVICE |
No |
Yes. Use this targeting type in order to set native bid modifiers by site. |
|
The value must be in the following format:
The following are valid device types:
|
|
SITE_GROUP_X_DEVICE |
No |
Yes. Use this targeting type in order to set native bid modifiers by site group. |
|
The value must be in the following format:
The following are valid device types:
|
|
SITE_BLOCK |
No |
Yes |
|
Note that it does not allow modifiers. You can specify the |
|
OS_VERSION |
No |
Only for the INSTALL_APP or REENGAGE_APP objective. |
|
The device OS version of the targeted users. For more information on the available OS Versions, see the data dictionary service. |
|
GENDER |
No |
Yes |
|
|
If no gender targeting is set, the campaign will serve to all users. |
SEGMENT |
Yes |
Yes |
|
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 |
|
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 |
|
The following age ranges can be passed as strings in the value field:
|
If no age targeting is set, all ages will be targeted. |
URL |
Yes |
No |
|
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 Native search supply. |
AD_SCHEDULE |
Yes |
Yes |
|
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 |
|
Refer to the custom audience section for details. |
|
CONNECTION |
No |
Only for video ads |
|
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. |
|
The following are valid values:
Group 1 is Native’s best-performing placements, including all Yahoo O&O. Groups 2 & 3 are third-party publisher placements that have traditionally not offered the same level of performance as Group 1. An individual publisher’s sections fall into all three Groups. Group A covers both desktop and tablet and group B denotes mobile |
|
SEGMENT_3P |
No |
Yes |
|
Valid value is the 3P interest category segment ID. |
|
SEGMENT_INTEREST |
No |
Yes |
|
The interest of the targeted audience. For more information on the available interests, see the data dictionary service. |
If no segment targeting is set, the campaign will serve to all users. |
Fields¶
The Targeting Attribute object contains the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The ID of the advertiser associated with the targeting attribute. |
long |
Required |
Optional (Read-Only) |
|
The ID of the targeting attribute. |
long |
N/A |
Required |
|
The ID of the targeting attribute parent. |
long |
Required |
Optional |
|
The type of parent. Value can be:
|
enum |
Required |
Optional |
|
Valid values:
|
enum |
Required |
Optional |
|
The type of targeting attribute. Supported targeting types:
See the table in the TargetingAttribute Overview section for more details. |
enum |
Required |
Optional |
|
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 |
|
Specifies whether to exclude (TRUE) or include (FALSE) for targeting. This is either true for negative targeting or false for positive targeting. |
enum |
Required |
Optional |
|
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 |
|
The search retargeting of the targeting attribute. Supported targeting types:
|
enum |
Required |
Optional |
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? |
---|---|---|---|
|
The ID of the targeting attribute parent to filter the targeting attributes by (denoted as pi). |
long |
Yes |
|
The type of targeting attribute parent to filter the targeting attributes by (denoted as pt). Valid values are:
|
enum |
Yes |
|
The maximum number of rows to retrieve. |
int |
Optional |
|
The start index or the first element to retrieve. |
int |
Optional |
|
The type of targeting to filter by (denoted as t). |
enum |
Optional |
|
The targeting value. |
enum |
Optional |
|
The exclude flag. This is either |
string |
Optional |
|
The status of the targeting attribute. |
enum |
|
|
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 |
---|---|
|
The ID of the targeting attribute to delete. |
|
The status of the targeting attribute set to |
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
}
}
Read a TargetingAttribute with a third-party segment
Method: To retrieve targeting attributes by type for a third-party segment, make a GET call:
https://api.gemini.yahoo.com/v3/rest/targetingattribute/
Response: The targeting attributes based on the third-party segment:
{
"errors":null,
"timestamp":"2018-01-19 1:09:07",
"response":[
{
"status":"ACTIVE",
"type":"SEGMENT_3P",
"id":274993080022,
"advertiserId":15209,
"createdDate":1516318038707,
"lastUpdateDate":1516318038707,
"parentType":"CAMPAIGN",
"parentId":22896,
"exclude":"FALSE",
"value":"20097120",
"bidModifier":null
}
]
}
Note
The targeting type is SEGMENT_3P. The value is the 3P interest category segment ID.
Valid site names for SITE_X_DEVICE targeting
For a list of valid site names for site x device targets, refer to Data Dictionary Example for the List of Supported Sites.
Site Block Targeting¶
Site block targeting is a targeting type available at the campaign level and for app install campaigns. Note that it does not allow modifiers. You can specify the exclude
field as TRUE to enable this. Site blocking accepts the domain and package name as user input. You specify the value
as the site (http://thirdpartyurl.com) you wish to block.
Example Representations¶
Site Block Targeting Attribute
{
“errors”: null,
“timestamp”: "2018-09-21 1:02:01",
“response”: {
“type”: "SITE_BLOCK",
“status”: "ACTIVE",
“parentType”: "CAMPAIGN",
“id”: 333,
“exclude”: "TRUE",
“advertiserId”: 111,
“parentId”: 222,
“value”: "thirdpartyurl.com" or “com.tubify.cc”
}
}
Create a new site block TargetingAttribute
Method: To create a new targeting attribute using site blocking, make a POST call to the TargetingAttribute endpoint. The response will be the newly created targeting attribute for site blocking.
For example:
POST https://api.gemini.yahoo.com/v3/rest/targetingattribute/
Data passed
{
"value": "http://thirdpartyurl.com",
"type": "SITE_BLOCK",
"status": "ACTIVE",
"exclude": "TRUE",
"advertiserId": 3393204,
"parentType": "CAMPAIGN",
"parentId": 13137246
}
Example response
{
"type": "SITE_BLOCK",
"status": "ACTIVE",
"id": 13441072,
"exclude": "TRUE",
"advertiserId": 3393204,
"sourceType": null,
"parentType": "CAMPAIGN",
"lastUpdateDate": 1534540025628,
"parentId": 13137246,
"createdDate": 1534540025628,
"value": "thirdpartyurl.com"
}
Important
You will not be able to block any Yahoo Native sites, such as yahoo.com, aol.com, and so on.
Site X Device Targeting¶
Site X Device targeting 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, Shopping 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 Yahoo Native API.
Note
The maximum limit is 300 for site x device targeting attributes. An error will be returned if you exceed that limit.
Site Group X Device Targeting¶
Site X Device targeting allows native advertisers to modify their bids on a per-site group, per-device basis on selected site groups, and is applicable to native channels-only, as well as VisitWeb, Shopping or PromoteBrand objectives-only. Site group 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.
Site Group X Device targeting is supported in the latest versions of the API, as well as both Bulk v2+ and API v2+. The new targeting type is SITE_GROUP_X_DEVICE
:
Site Group X Device Example
{
"value": "MSN_US_HOMEPAGE|DESKTOP",
"id": 338497,
"type": "SITE_GROUP_X_DEVICE",
"status": "ACTIVE",
"advertiserId": 87292,
"parentType": "CAMPAIGN",
"parentId": 46756,
"exclude": "FALSE",
"bidModifier": 0.2
}
Refer to the Data Dictionary service for more information about the /bbsxd_supported_site_groups
API, which enables you to fetch external names for just site groups. Note that the /bbsxd_supported_site_groups
API fetches only site groups that can be targeted as a SITE_GROUP_X_DEVICE.
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 |
SITE_GROUP_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 - 9.0 |
Native |
SUPPLY_GROUP |
GROUP_1_B |
0.6 - 7.0 |
Native |
SUPPLY_GROUP |
GROUP_2_A |
0.7 - 9.0 |
Native |
SUPPLY_GROUP |
GROUP_2_B |
0.3 - 7.0 |
Native |
SUPPLY_GROUP |
GROUP_3_A |
0.5 - 9.0 |
Native |
SUPPLY_GROUP |
GROUP_3_B |
0.2 - 7.0 |
Native |
Device bid modifiers
Important
DEVICE bid modifiers are slightly different than bid modifiers for other targeting types. Native 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.