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
`advertiserId`	The ID of the advertiser associated with the call extension. This field cannot be updated.	long	Required	Optional (Read-Only)
`id`	The ID of the call extension. IDs are unique across all ad extensions.	long	N/A	Required
`parentId`	The ID of the parent.	long	Required	Optional
`parentType`	The type of parent. This value needs to be set to CAMPAIGN	enum	Required	Optional
`status`	Valid values: ACTIVE DELETED PAUSED	enum	Required	Optional
`type`	The type of ad extension. For call extensions, the type should be set to CALL.	enum	Required	Optional
`phoneNumber`	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
`phoneCountry`	The country code - for example US or CA.	string	Required	Optional
`isCallOnly`	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
`parentId`	The ID of the ad extension parent to filter by.	long	Yes
`parentType`	The type of ad extension parent to filter by. Valid values are: CAMPAIGN ADGROUP	enum	Yes
`mr`	The maximum number of rows to retrieve. This value should not be greater than 300.	int	Optional
`advertiserId`	The ID of the advertiser.	long	Optional
`si`	The start index or the first element to retrieve.	int	Optional
`type`	The type of ad extension.	enum	Optional
`status`	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
`id`	The ID of the ad extension to delete.
`status`	The status of the ad extension set to be deleted.
`type`	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
     }
 ]
}