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

  • Campaign

  • Ad Group

Type WOEID refers to geo targeting. Verizon Media 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).

  • 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.

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

SITE_GROUP_X_DEVICE

No

Yes. Use this targeting type in order to set native bid modifiers by site group.

  • Campaign

  • Ad Group

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

  • MSN_US|DESKTOP

  • NEWS_US|MOBILE

The following are valid device types:

  • DESKTOP

  • MOBILE

SITE_BLOCK

No

Yes

  • Native and 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.

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

  • Ad Group

  • 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 Native 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

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

  • Native Campaigns. Allows targeting of third-party interest segments and their data providers.

Valid value is the 3P interest category segment ID.

SEGMENT_INTEREST

No

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, the campaign will serve to all users.

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

  • SEGMENT_3P

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.

enum

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

searchRetargeting

The search retargeting of the targeting attribute. Supported targeting types:

  • KEYWORD

  • WOEID (zip woeids are not allowed.)

  • DEVICE (SmartPhone, Tablet)

  • SUPPLY_GROUP

  • SHARED_SET

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?

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

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 Verizon Media 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 Verizon Media 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.