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 |
---|---|---|---|---|
|
The name of the ad group. Maximum limit is 255 characters. |
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. 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. |
|
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 |
|
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:
|
enum |
Optional |
Optional |
|
This is the value you place on the conversion. Refer to Data Dictionary to look up currency by type. Note that decreasing your |
numeric |
Required for install app campaigns, otherwise, optional |
If the bidding strategy is OPT_CONVERSION, the |
|
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 Yahoo Native 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? |
---|---|---|
|
The supply channel where the ads will run. Value can be:
|
Yes |
|
The pricing type. Supported types are:
|
Yes |
|
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 |
---|---|---|
|
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 |
|
The ad status to filter the ads by. |
enum |
|
The ID of the advertiser associated with the ad. |
long |
Important
advertiserId
parameter is a required query parameter for all filtered list ad group GET calls.
Example: GET call for a filtered list of ad groups:
https://api.gemini.yahoo.com/v3/rest/adgroup/?campaignId=31336&mr=2&advertiserid=87292
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 |
---|---|
|
The ID of the ad group to delete. |
|
The status of the ad group should be set to |
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"
}
}