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 |
---|---|---|---|---|
|
The name of the ad group. |
string |
Required |
Optional |
|
The ID of the advertiser. |
long |
Required |
Optional (Read-only) |
|
A list of bids - the value can be one or more bids. Please refer to the bidSet Object fields for more information. |
|
Required |
Optional |
|
The ID of the campaign associated with the ad group. |
long |
Required |
Optional (Read-Only) |
|
The ID of the ad group. |
long |
N/A |
Required |
|
The status of the ad group. Valid values are:
|
enum |
Required |
Optional |
|
The start date string value of the ad group (in |
string |
Required |
Optional |
|
The end date string value of the ad group (in |
string |
Required only if the ad group is under a campaign with a LIFTETIME budget type |
Optional |
|
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 |
|
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 |
|
Applies only to native campaigns with either VISIT_WEB or INSTALL_APP objectives. Available values:
|
enum |
Optional |
Optional |
|
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? |
---|---|---|
|
The supply channel where the ads will run. Value can be:
|
Yes |
|
The pricing type. Supported types are:
|
Yes |
|
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 |
---|---|---|
|
The ID of the campaign to filter the ad groups by. |
long |
|
The maximum number of rows to retrieve. This value should not be greater than 300. |
int |
|
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 |
---|---|
|
The ID of the ad group to delete. |
|
The status of the ad group should be set to |
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"
}
}