Ad Extensions

Overview

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.

There are two specific types of ad extensions:

  • sitelinks, which let you provide links to pages beyond the ad destination landing page
  • call extensions, referred to as Click-to-Call, which let you display an advertiser-provided phone number in Call button format for text ads on smartphones

You use standard GET, PUT and POST calls to read, update, create and delete ad extensions using the ad extensions endpoint.

Fields

Sitelinks contain the following fields:

Name Description Type Add Update
advertiserId The ID of the advertiser associated with the sitelink. This field cannot be updated. long Required Optional (Read-Only)
id The ID of the sitelink. 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 - can be:

  • CAMPAIGN
  • ADGROUP
enum Required Optional
status

Valid values:

  • ACTIVE
  • DELETED
  • PAUSED
enum Required Optional
type The type of ad extension. For sitelinks the type should be set to SITE_LINK. enum Required Required
position When displaying an ad, Gemini will factor in this attribute in order to determine which links to show and which order to show them in. This should be a priority number between 1 and 10. int Required Optional
title This is the title that is displayed. The limit is 50 characters. string Required Optional
landingUrl The landing URL for the sitelink. The limit is 2048 characters. string Required Optional

Example Representations

Sitelink

{
    "type": "SITE_LINK",
    "position": null,
    "title": "Sales",
    "landingUrl": "www.yahoo.com",
    "parentId": 331095059,
    "status": "ACTIVE",
    "parentType": "CAMPAIGN",
    "id": 103002,
    "advertiserId": 925746
}

Sitelink Array

[
 {
     "type": "SITE_LINK",
     "position": null,
     "title": "Sales",
     "landingUrl": "www.yahoo.com",
     "parentId": 331095059,
     "status": "ACTIVE",
     "parentType": "CAMPAIGN",
     "id": 103002,
     "advertiserId": 925746
 },
 {
     "type": "SITE_LINK",
     "position": 1,
     "title": "Doofus",
     "landingUrl": "www.yahoo.com",
     "parentId": 331095059,
     "status": "ACTIVE",
     "parentType": "CAMPAIGN",
     "id": 103003,
     "advertiserId": 925746
 }
]

Sitelink Response

{
  "errors": null,
  "response": [
     {
         "type": "SITE_LINK",
         "position": null,
         "title": "Sales",
         "landingUrl": "www.yahoo.com",
         "parentId": 331095059,
         "status": "ACTIVE",
         "parentType": "CAMPAIGN",
         "id": 103002,
         "advertiserId": 925746
     }
  ]
}

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.admanager.yahoo.com/v1/rest/adextension/

Read

Call: To retrieve ad extensions grouped by type for a specific parent, 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

Example: Here is an example of a call to get the sitelinks for a specific advertiser:

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

For example:

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

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