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