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.

Endpoint¶

Resource URI

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

Available Attributes¶

The following table provides details on the available targeting types:

Fields¶

The Targeting Attribute object contains the following fields:

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:

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:

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

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

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.

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:

Device bid modifiers

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.