Ad Group

Abstract

The AdGroupService provides methods for creating, updating, and retrieving ad groups.

Overview

An ad group is a collection of ads and targeting objects that is associated with a particular campaign. For a campaign that runs on mobile search, ad groups will also include keywords. Ad groups help you manage different contexts within your campaign, and provide them with their own default bids, flight dates, status and targeting settings.

Important

In v3, for ad groups under install app campaigns, the ecpaGoal is required. The bidding strategy will be set to OPT_CONVERSION.

Fields

The Ad Group object contains the following fields:

Name

Description

Type

Add

Update

adGroupName

The name of the ad group. Maximum limit is 255 characters.

string

Required

Optional

advertiserId

The ID of the advertiser.

long

Required

Optional (Read-only)

bidSet

A list of bids - the value can be one or more bids. Please refer to the bidSet Object fields for more information. Note that bids should fulfill a budget-to-bid ratio of 50:1 for Native campaigns and 1:1 for Search campaigns.

bidSet[]

Required

Optional

campaignId

The ID of the campaign associated with the ad group.

long

Required

Optional (Read-Only)

id

The ID of the ad group.

long

N/A

Required

status

The status of the ad group. Valid values are:

  • ACTIVE

  • PAUSED

  • DELETED

enum

Required

Optional

startDateStr

The start date string value of the ad group (in YYYY-mm-dd format) in the timezone of the account. The time will automatically get set to 00:00:00.000

string

Required

Optional

endDateStr

The end date string value of the ad group (in YYYY-mm-dd format) in the timezone of the account. The time will automatically get set to 23:59:59.000

string

Required only if the ad group is under a campaign with a LIFTETIME budget type

Optional

advancedGeoPos

Applies only to SEARCH campaigns. For the locations you target, the recommended and default value is DEFAULT, which means you will reach people either physically in your targeted locations or who have expressed interest in these locations. LOCATION_OF_PRESENCE means reaching only people physically in the targeted location, and LOCATION_OF_INTEREST means targeting only people who have expressed interest in the location.

enum

Optional

Optional

advancedGeoNeg

Applies only to SEARCH campaigns. Similar to advancedGeoPos but applies only to locations you exclude. Valid values are DEFAULT (the default) and LOCATION_OF_PRESENCE.

enum

Optional

Optional

biddingStrategy

Note that this field is deprecated in favor Campaign bidding strategy. Refer to Campaign fields for more information. Applies only to native campaigns with either VISIT_WEB or INSTALL_APP objectives. Available values:

  • OPT_ENHANCED_CPC - This is a new bidding strategy that allows you to meet a CPC goal on average while getting more conversions by allowing your bids to be adjusted for individual impressions based on the likelihood of conversion. The bidding strategy is for native VISIT_WEB campaigns only. Note the restriction that an ecpaGoal is required.

  • OPT_POST_INSTALL - This means that Native & Search will dynamically notify your bid in order to optimize for the install and specific in-app event conversion rule for INSTALL_APP campaigns only. You also need to have at least one conversion rule set up in order to leverage this strategy, and it must be also included in the corresponding campaign’s conversionRuleIds. Note that you’ll need to have an ecpaGoal in order to set OPT_POST_INSTALL.

  • OPT_CONVERSION - This means that Native & Search will dynamically modify your bid in order to optimize for conversions. bidSet is still Native & Search and will define the initial bid that Native & Search will gradually optimize. You also need to have at least one conversion rule set up in order to leverage this strategy. Note that you need to have an ecpaGoal in order to set OPT_CONVERSION. For install app campaigns, the bidding strategy will be set to OPT_CONVERSION.

  • DEFAULT - the default bidding strategy, meaning Native & Search will optimize per your selected price type (deliver clicks for CPC ads groups, impressions for CPM ads). See an example in the Create a new ad group section.

enum

Optional

Optional

ecpaGoal

This is the value you place on the conversion. Refer to Data Dictionary to look up currency by type. Note that decreasing your ecpaGoal will typically lower the delivery of your campaign. If the bidding strategy is OPT_CONVERSION, the ecpaGoal is required. For install app campaigns, the ecpaGoal is also required.

numeric

Required for install app campaigns, otherwise, optional

If the bidding strategy is OPT_CONVERSION, the ecpaGoal is required.

productSetId

The id of the associate product set.

long

Optional

Optional

Endpoint

Resource URI

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

v3 Upgraded URL Attributes

Important

For the v3 Native API, Upgraded URL (UU) attributes are now supported for the Ad group object type.

The following table describes the supported UU attributes per the Ad object type in v3 Native & Search API.

Object

Landing Url

Display Url

Final Url

Mobile Final Url

TrackingUrl

Custom Parameters

Display Url Path1

Display Url Path2

Ad

dp

dp

yes

yes

yes

yes

yes

yes

Note

dp stands for deprecated in the above table.

Note

The landing page url is deprecated only for search. The Final url will be eligible in a native context. Native-only ads are not required to use the final URL and may continue to use the landing page url.

For more information on Upgraded URLs in v3, refer to Upgraded URLs.

Example Representations

AdGroup

{
  "id": 1,
  "status": "ACTIVE",
  "adGroupName": "SearchAdGroup",
  "advertiserId": 87292,
  "campaignId": 31363,
  "startDateStr": "2014-04-01",
  "endDateStr": "2015-01-01",
  "advancedGeoPos": "DEFAULT",
  "advancedGeoNeg": "DEFAULT",
  "biddingStrategy": "DEFAULT",
  "ecpaGoal":null,
  "bidSet": {
      "bids": [
          {
              "priceType": "CPC",
              "value": 2,
              "channel": "SEARCH"
          }
      ]
  }
}

AdGroup Array

[
  {
  "id": 46750,
  "status": "PAUSED",
  "advertiserId": 87292,
  "campaignId": 31364,
  "adGroupName": "MobileSearchDeals",
  "advancedGeoPos": "DEFAULT",
  "advancedGeoNeg": "DEFAULT",
  "biddingStrategy": "DEFAULT",
  "ecpaGoal":null,
  "bidSet": {
      "bids": [
          {
              "priceType": "CPC",
              "value": 2,
              "channel": “SEARCH”
          }
      ]
  },
  "startDateStr": "2014-04-01",
  "endDateStr": "2015-01-01"
  },
  {
      "id": 46751,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignId": 31364,
      "adGroupName": "NativeAdsDeals",
      "advancedGeoPos": "DEFAULT",
      "advancedGeoNeg": "DEFAULT",
      "biddingStrategy": "DEFAULT",
      "ecpaGoal":null,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": “NATIVE”
              }
          ]
      },
      "startDateStr": "2014-04-01",
      "endDateStr": "2015-01-01"
  }
]

AdGroupResponse

{
  "errors": null,
  "response": {
      "id": 46759,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignId": 31363,
      "adGroupName": "MultiChannelAdGroup",
      "advancedGeoPos": "DEFAULT",
      "advancedGeoNeg": "DEFAULT",
      "biddingStrategy": "DEFAULT",
      "ecpaGoal":null,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              },
              {
                  "priceType": "CPC",
                  "value": 3,
                  "channel": "NATIVE"
              }
          ]
      },
      "startDateStr": "2014-04-01",
      "endDateStr": "2015-01-01"
  }
}

bidSet object

The bidSet object is used to specify bids. Both the ad group and the keyword objects can carry bids. As a rule, the lower level bid (keyword is the lowest level) overrides bids set at a higher level. Ad groups that run on mobile search, for example, will carry a bid with a channel value of SEARCH and a priceType of CPC.

Note

To have your ads serve on a given channel, you need to set a bid for the channel. For native ads, a bid for channel=NATIVE needs to be set at the ad group level. For mobile search ads, either a default bid for channel=SEARCH at the ad group level or keyword level bids need to be set.

Note

Bids should fulfill a budget-to-bid ratio of 50:1 for Native campaigns and 1:1 for Search campaigns.

Example

To set bids:

"bids": [
             {
           "priceType": "CPC",
           "value": 1.5,
           "channel": "NATIVE"},
             {
           "priceType": "CPC",
           "value": 2.5,
           "channel": "SEARCH"}
     ]

bids Fields

Parameter

Description

Required?

channel

The supply channel where the ads will run. Value can be:

  • SEARCH - for mobile search ads.

  • NATIVE - for native ads in native content streams.

Yes

priceType

The pricing type. Supported types are:

  • CPC - only if campaign objective is VISIT_WEB or REENGAGE_APP

  • CPM - only if campaign objective is PROMOTE_BRAND

  • CPC - only for video ads in INSTALL_APP campaigns

  • CPM, CPV - only for video ads in PROMOTE_BRAND campaigns

Yes

value

The bid amount. Refer to Data Dictionary to look up currency by type.

Yes

Operations

Read specific ad group data

Method: To retrieve data for a specific ad group, make a GET call with the id parameter. For example:

https://api.gemini.yahoo.com/v3/rest/adgroup/46888

The response will be the ad group associated with the given id:

{
  "errors": null,
  "response": {
      "id": 46888,
      "status": "PAUSED",
      "campaignId": 31364,
      "advertiserId": 87292,
      "advancedGeoPos": "DEFAULT",
      "advancedGeoNeg": "DEFAULT",
      "biddingStrategy": "DEFAULT",
      "ecpaGoal":null,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              }
          ]
      },
      "startDateStr": "2014-04-01",
      "endDateStr": "2015-01-01",
      "adGroupName": "MobileSearchDeals"
  }
}

Example: Make a GET call and pass in multiple IDs. Please note that when you pass multiple IDs, all other filters besides id will be ignored:

https://api.gemini.yahoo.com/v3/rest/adgroup/?id=8312337373&id=7718653454

Response: The ad groups associated with the given IDs:

{
  "errors": null,
  "timestamp": "2015-09-09 18:47:22",
  "response": [
      {
          "id": 8312337373,
          "status": "ACTIVE",
          "campaignId": 338017028,
          "startDateStr": "2015-09-10",
          "endDateStr": "2016-09-11",
          "adGroupName": "Optimize for conversions",
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2,
                      "channel": "NATIVE"
                  }
              ]
          },
          "advertiserId": 976108,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "OPT_CONVERSION",
          "ecpaGoal": 15
      },
      {
          "id": 7718653454,
          "status": "ACTIVE",
          "campaignId": 338017028,
          "startDateStr": "2014-12-09",
          "endDateStr": "2014-12-11",
          "adGroupName": "Oath mobile  search",
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 1,
                      "channel": "SEARCH"
                  }
              ]
          },
          "advertiserId": 976108,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "DEFAULT",
          "ecpaGoal": null
      }
  ]
}

Read data for filtered list of ad groups

Method: To retrieve data for a filtered list of ad groups, make a GET call with the following parameters:

Name

Description

Type

campaignId

The ID of the campaign to filter the ad groups by.

long

mr

The maximum number of rows to retrieve. This value should not be greater than 300.

int

si

The start index or the first element to retrieve.

int

status

The ad status to filter the ads by.

enum

advertiserId

The ID of the advertiser associated with the ad.

long


Important

Only one campaignId or advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists ad group calls.

Example: GET call for a filtered list of ad groups:

https://api.gemini.yahoo.com/v3/rest/adgroup/?campaignId=31336&mr=2

The response will be the list of ad groups matching the given filter:

{
  "errors": null,
  "response": [
      {
          "id": 46722,
          "status": "PAUSED",
          "campaignId": 31336,
          "advertiserId": 87292,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "DEFAULT",
          "ecpaGoal": null,
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 4.5,
                      "channel": "NATIVE"
                  }
              ]
          },
          "startDateStr": "2014-04-01",
          "endDateStr": "2015-01-01",
          "adGroupName": "descriptive name 1"
      },
      {
          "id": 46727,
          "status": "PAUSED",
          "campaignId": 31336,
          "advertiserId": 87292,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "DEFAULT",
          "ecpaGoal": null,
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2,
                      "channel": "SEARCH"
                  }
              ]
          },
          "startDateStr": "2014-04-01",
          "endDateStr": "2015-01-01",
          "adGroupName": "descriptive name 2"
      }
  ]
}

Update existing ad groups

Method: To update existing ad groups, make a PUT call with one or more AdGroup objects. Specify the fields to update. Please note that id is the only required parameter, all other fields are optional. Partial update is supported; fields that are either not passed or passed as null will be ignored during update.

Note

biddingStrategy is optional, except for install app campaigns, where it is read-only.

For example, to update the status for an array of ad groups:

PUT https://api.gemini.yahoo.com/v3/rest/adgroup

Data passed

{
  {
    "id": 46756,
    "status": "ACTIVE"
  },
      {
    "id": 46758,
    "status": "ACTIVE"
  }
}

Example response

{
  "errors": null,
  "response": [
      {
          "id": 46756,
          "status": "ACTIVE",
          "campaignId": 31369,
          "advertiserId": 87292,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "DEFAULT",
          "ecpaGoal": null,
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2,
                      "channel": "SEARCH"
                  }
              ]
          },
          "startDateStr": "2014-04-01",
          "endDateStr": "2015-01-01",
          "adGroupName": "MobileSearch"
      },
      {
          "id": 46758,
          "status": "ACTIVE",
          "campaignId": 31369,
          "advertiserId": 87292,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
          "biddingStrategy": "DEFAULT",
          "ecpaGoal": null,
          "bidSet": {
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2.5,
                      "channel": "NATIVE"
                  }
              ]
          },
          "startDateStr": "2014-04-01",
          "endDateStr": "2015-01-01",
          "adGroupName": "NativeAds"
      }
  ]
}

Create a new ad group

Method: To create a new ad group, make a POST call with the AdGroup object. Batch create is supported - either an ad group or an ad group array can be passed. The response will be the newly created ad group. For example, to create a new ad group with a default bid for the mobile search channel:

Example:

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

Data passed

{
       "status": "ACTIVE",
       "adGroupName": "MobileSearchAdGroup",
       "advertiserId": 87292,
       "campaignId": 31363,
       "startDateStr": "2014-04-01",
       "endDateStr": "2015-01-01",
       "bidSet": {
           "bids": [
               {
                  "priceType": "CPC",
                   "value": 2.5,
                   "channel": "SEARCH"
                }
              ]
          }
      }

Example response

{
  "errors": null,
  "response": {
      "id": 46890,
      "status": "ACTIVE",
      "campaignId": 31363,
      "advertiserId": 87292,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT",
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2.5,
                  "channel": "SEARCH"
              }
          ]
      },
      "startDateStr": "2014-04-01",
      "endDateStr": "2015-01-01",
      "adGroupName": "MobileSearchAdGroup"
  }
}

Method: To create a new ad group with a bidding strategy of optimizing for conversions, make the following POST call:

Example:

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

Data passed

{
  "status": "ACTIVE",
  "campaignId": 338017028,
  "bidSet": {
      "bids": [
          {
              "priceType": "CPC",
              "value": 2.5,
              "channel": "NATIVE"
          }
      ]
  },
  "advertiserId": 976108,
  "adGroupName": "US apparel - optimize for conversions",
  "startDateStr": "2015-09-10",
  "endDateStr": "2016-09-11",
  "ecpaGoal":10,
  "biddingStrategy":"OPT_CONVERSION"
}

Example response

{
  "errors": null,
  "timestamp": "2015-09-22 18:28:33",
  "response": {
      "status": "ACTIVE",
      "id": 8325500360,
      "campaignId": 338017028,
      "adGroupName": "US apparel - optimize for conversions",
      "startDateStr": "2015-09-10",
      "endDateStr": "2016-09-11",
      "biddingStrategy":"OPT_CONVERSION",
      "ecpaGoal":10,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2.5,
                  "channel": "NATIVE"
              }
          ]
      },
      "advancedGeoPos": "DEFAULT",
      "advancedGeoNeg": "DEFAULT",
      "advertiserId": 976108
  }
}

Delete an ad group

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

Field

Description

id

The ID of the ad group to delete.

status

The status of the ad group should be set to DELETED in order to delete the ad group.


Note

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

Example:

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

Data passed

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

Example response

{
  "errors": null,
  "response": {
      "id": 46890,
      "status": "DELETED",
      "campaignId": 31363,
      "advertiserId": 87292,
      "advancedGeoPos": "DEFAULT",
      "advancedGeoNeg": "DEFAULT",
      "biddingStrategy": "DEFAULT",
      "ecpaGoal": null,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2.5,
                  "channel": "SEARCH"
              }
          ]
      },
      "startDateStr": "2014-04-01",
      "endDateStr": "2015-01-01",
      "adGroupName": "MobileSearchAdGroup"
  }
}