Ad Extensions¶
Abstract¶
Ad extensions are extensions of your ads, allowing your ads to take up more real estate and to offer more details and value to your customers.
Overview¶
You use standard GET, PUT and POST calls to read, update, create and delete ad extensions using the ad extensions endpoint.
Important
For v2, sitelink has been deprecated in favor of shared sitelink.
Call extensions¶
Call extensions, often referred to as Click-to-Call, display an advertiser-provided phone number in the format of a Call button for text ads on smartphones. Call extensions are available for search campaigns and can be set at the campaign level. Only one call extension is allowed per campaign.
Note
The adxtype for call extensions is not supported because the Click-to-Call link doesn’t load an advertiser’s landing page.
Fields¶
Call extensions contain the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The ID of the advertiser associated with the call extension. This field cannot be updated. |
long |
Required |
Optional (Read-Only) |
|
The ID of the call extension. IDs are unique across all ad extensions. |
long |
N/A |
Required |
|
The ID of the parent. |
long |
Required |
Optional |
|
The type of parent. This value needs to be set to CAMPAIGN |
enum |
Required |
Optional |
|
Valid values:
|
enum |
Required |
Optional |
|
The type of ad extension. For call extensions, the type should be set to CALL. |
enum |
Required |
Optional |
|
The phone number to be included in the ad. It must be a valid phone number for the country code provided in the phoneCountry field. Valid phone numbers provided will be reformatted to (555) 555-5555 format. |
string |
Required |
Optional |
|
The country code - for example US or CA. |
string |
Required |
Optional |
|
Determines whether the phone number is the only clickable element in the ad. This value defaults to FALSE. |
boolean |
Required |
Optional |
Example Representations¶
Call Extension
{
"type": "CALL",
"phoneNumber": "(888) 442-2862",
"phoneCountry": "US",
"isCallOnly": "FALSE",
"status": "ACTIVE",
"advertiserId": 11610,
"parentId": 332817035,
"parentType": "CAMPAIGN"
}
Call Extension Response
{
"errors": null,
"response": [
{
"type": "CALL",
"phoneNumber": "(888) 442-2862",
"phoneCountry": "US",
"isCallOnly": "FALSE",
"id": 335888024,
"status": "ACTIVE",
"advertiserId": 11610,
"parentId": 332817035,
"parentType": "CAMPAIGN"
}
]
}
Endpoint¶
Resource URI
https://api.gemini.yahoo.com/v3/rest/adextension/
Read data for a filtered list of ad extensions¶
Call: To retrieve data for a filtered list of ad extensions, make a GET call with the following parameters - you can either specify the parentId and parentType filters, or use the other filters on the list:
Name |
Description |
Type |
Required |
---|---|---|---|
|
The ID of the ad extension parent to filter by. |
long |
Yes |
|
The type of ad extension parent to filter by. Valid values are:
|
enum |
Yes |
|
The maximum number of rows to retrieve. This value should not be greater than 300. |
int |
Optional |
|
The ID of the advertiser. |
long |
Optional |
|
The start index or the first element to retrieve. |
int |
Optional |
|
The type of ad extension. |
enum |
Optional |
|
The ad extension status. |
enum |
Optional |
Important
Only one parentId
or advertiserId
parameter is allowed to be passed in as a query parameter for all filtered list of ad extension calls.
Example: Here is an example of a call to get the sitelinks for a specific advertiser:
https://api.gemini.yahoo.com/v3/rest/adextension?advertiserId=925746&type=SITE_LINK&mr=2
The response will be the list of ad extensions based on the given filters:
{
"errors": null,
"response": [
{
"type": "SITE_LINK",
"position": null,
"title": "Sales",
"landingUrl": "www.sitelink1.com",
"parentId": 331095059,
"status": "ACTIVE",
"parentType": "CAMPAIGN",
"id": 103002,
"advertiserId": 925746
},
{
"type": "SITE_LINK",
"position": 1,
"title": "More sales",
"landingUrl": "www.sitelink2.com",
"parentId": 331095059,
"status": "ACTIVE",
"parentType": "CAMPAIGN",
"id": 103003,
"advertiserId": 925746
}
]
}
Update existing ad extensions¶
Call: To update existing ad extensions, make a PUT call with one or more ad extension objects. The response will be the list of updated ad extensions. For example, to update the landing url for a given sitelink extension:
PUT https://api.gemini.yahoo.com/v3/rest/adextension/
Data passed
{
"type": "SITE_LINK",
"landingUrl": "www.sitelink20.com",
"id": 100001
}
Example response
{
"errors": null,
"response": [
{
"type": "SITE_LINK",
"position": 1,
"title": "sitelink111",
"landingUrl": "www.sitelink20.com",
"parentId": 7116640119,
"status": "ACTIVE",
"parentType": "ADGROUP",
"id": 100001,
"advertiserId": 200
}
]
}
Create a new ad extension¶
Call: To create a ad extension, make a POST call to the ad extension endpoint. The response will be the newly created ad extension. Batch create is supported - either a single object or an array can be passed. For example:
POST https://api.gemini.yahoo.com/v3/rest/adextension/
Data passed
{
"type": "CALL",
"status": "ACTIVE",
"advertiserId": "11610",
"parentType": "CAMPAIGN",
"parentId": "332817035",
"phoneNumber": "(888) 442-2862",
"isCallOnly": "FALSE",
"phoneCountry": "US"
}
Example response
{
"errors": null,
"response": [
{
"type": "CALL",
"phoneNumber": "(888) 442-2862",
"phoneCountry": "US",
"isCallOnly": "FALSE",
"id": 335888024,
"status": "ACTIVE",
"advertiserId": 11610,
"parentId": 332817035,
"parentType": "CAMPAIGN"
}
]
}
Delete an ad extension¶
Call: To delete an ad extension, make a PUT call with the ad extension object. Batch delete is supported - either a single object or an array can be passed.
The following parameters are required:
Field |
Description |
---|---|
|
The ID of the ad extension to delete. |
|
The status of the ad extension set to be deleted. |
|
The type of ad extension. |
Note
In v2, the DELETE operation is supported for both single and multiple ids.
For example:
PUT https://api.gemini.yahoo.com/v3/rest/adextension/
DELETE https://api.gemini.yahoo.com/v3/rest/adextension/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/adextension?id=123&id=1234&...
Data passed
{
"id": 338,
"type": "SITE_LINK",
"status": "DELETED"
}
Example response
{
"errors": null,
"response": [
{
"type": "SITE_LINK",
"position": 1,
"title": "NewSitelink",
"landingUrl": "www.newsitelink.com",
"parentId": 7116640119,
"status": "DELETED",
"parentType": "ADGROUP",
"id": 338,
"advertiserId": 200
}
]
}