Ad Group

Overview

The AdGroupService provides methods for creating, updating, and retrieving ad groups. 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.

Fields

The Ad Group object contains the following fields:

Name Description Type Add Update
adGroupName The name of the ad group. 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. 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

Applies only to native campaigns with either VISIT_WEB or INSTALL_APP objectives. Available values:

  • OPT_CONVERSION - means that Gemini will dynamically modify your bid in order to optimize for conversions. bidSet is still required and will define the initial bid that Gemini 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.
  • DEFAULT - the default bidding strategy, meaning Gemini 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 Required when biddingStrategy is OPT_CONVERSION. This is the value you place on the conversion. The minimum is $1. Note that decreasing your ecpaGoal will typically lower the delivery of your campaign. numeric Optional Optional

Endpoint

Resource URI

https://api.admanager.yahoo.com/v1/rest/adgroup

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. Please note that in order 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.

Example

Please see below for more information on how 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 INSTALL_WEB
  • CPM - only if campaign objective is PROMOTE_BRAND
  • CPV - only for video ads in either PROMOTE_BRAND or INSTALL_APP campaigns
Yes
value The bid amount. The minimum accepted CPC bid is $0.05. The minimum accepted CPM bid is $0.25. 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.admanager.yahoo.com/v1/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.admanager.yahoo.com/v1/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": "Gemini 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

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

https://api.admanager.yahoo.com/v1/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. For example, in order to update the status for an array of ad groups:

PUT https://api.admanager.yahoo.com/v1/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.admanager.yahoo.com/v1/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.admanager.yahoo.com/v1/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.

Example:

PUT https://api.admanager.yahoo.com/v1/rest/adgroup

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