Shared Sitelink¶

Abstract¶

The SharedSiteLinkService provides methods for creating, updating, and retrieving shared sitelinks.

Overview¶

Shared SiteLinks are created on the advertiser account level using the shared sitelink endpoint. Once created, you can share and link these to any campaign or ad group. The linking to campaigns or ad groups is handled by the Shared Sitelink Setting endpoint, described in the section below.

Fields¶

Shared SiteLinks include the following fields:

Name	Description	Type	Add	Update
`id`	The ID of the shared sitelink.	long	required	required
`advertiserId`	The ID of the advertiser.	long	required	optional
`status`	The status of the shared sitelink. Valid values: `ACTIVE` `PAUSED` `DELETED` `REJECTED` The `status` field is reserved for mutable entity state and user transitions. Note that the `REJECTED` value here is set by the system editorial review. See the diagram below for an illustration of how this works.	enum	required	optional
`editorialStatus`	The editorial status of the ad. Valid values are: `NOT_REVIEWED` `PENDING_REVIEW` `APPROVED` `REJECTED` The `editorialStatus` field is reserved for read-only system editorial review transitions. Note that this field is read-only for Adds (creates) and Updates.	enum	read-only	read-only
`title`	The title of the shared sitelink.	string	required	optional
`description`	The description of the shared sitelink.	string	optional	optional
`landingUrl`	The landing url of the shared sitelink.	string	required	optional
`imageUrl`	For a carousel card asset, a valid URL for a square image that will be displayed when your ad appears in content streams or in the other eligible native ad positions. The ideal image size is 627x627. The maximum size is 7MB. For a touchpoint asset, a valid URL for a modal image that will be displayed when a touchpoint asset is clicked for this popup image to appear. The ideal image size must have an aspect ratio between 3:4 and 1:1. Minimum width is 612px (which means the height must be between 612px and 816px for an image with 612px width). Maximum width is 1500px (which means the height must be between 1500px and 2000px). The effective minimum dimensions are therefore 612x612 and maximum dimensions are 1500x2000. The maximum size is 7MB.	string	Required for carousel card assets. Ignored for tile assets. Optional for touchpoint assets.	optional
`imageUrlHQ`	For a carousel card asset, a valid URL to a high resolution image that will be used. The ideal image size is 1200x627; smaller images will not be accepted. Larger images with either the same aspect ratio or with a height and width that are off the ideal dimensions by up to a combined 10% will be accepted as well as will be automatically cropped at the center. The maximum file size is 7MB.	string	Required for carousel card assets. Ignored for other assets types.	optional

The Entity Status and Editorial Status

v3 Upgraded URL Attributes¶

Important

For the v3 Yahoo Native API, Upgraded URL attributes are now supported for the Shared Sitelink object type.

The following table describes the supported UU attributes per the Shared Sitelink object type in v3 Yahoo Native API.

Object	Landing Url	Display Url	Final Url	Mobile Final Url	Tracking Template	Custom Parameters	Display Url Path1	Display Url Path2
Shared Sitelink	dp	no	yes	yes	yes	yes	no	no

Note

dp means 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 (UUs) in v3, refer to Upgraded URLs.

Shared Sitelink Statuses¶

Any new sitelink undergoes automatic quality review. If no issues are raised, the sitelink can start running in less than a minute after its creation. A sitelink can be in one of the following statuses:

Status	Description
`ACTIVE`	The sitelink is running.
`PAUSED`	The sitelink is paused and can be re-activated.
`REJECTED`	The sitelink was declined due to policy violations. Further information is available in the Ad Manager UI.
`DELETED`	Set the status of the sitelink to DELETED in order to delete the ad; once this is done, the ad is removed from the system and cannot be reactivated.

Endpoint¶

Resource URI

https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

Example Representations¶

Shared Sitelink

{
 "title": "Sales",
 "landingUrl": "www.yahoo.com",
 "description": "Sales - site link",
 "status": "ACTIVE",
 "id": 103002,
 "advertiserId": 925746
}

Shared Sitelink Array

[
 {
   "title": "Sales",
   "landingUrl": "www.yahoo.com",
   "description":  "Sales - site link",
   "status": "ACTIVE",
   "id": 103002,
   "advertiserId": 925746
 },
 {
   "title": "Awesome",
   "landingUrl": "www.yahoo.com",
   "description": "Awesome - site link",
   "status": "ACTIVE",
   "id": 103003,
   "advertiserId": 925746
 }
]

Shared Sitelink Response

{
"errors": null,
"response": [
   {
       "title": "Sales",
       "landingUrl": "www.yahoo.com",
       "description": "Sales - site link",
       "status": "ACTIVE",
       "id": 103002,
       "advertiserId": 925746
   }
 ]
}

Operations¶

Read

Method: To retrieve data for a specific shared sitelink, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedsitelink/1234

The response will be the shared sitelink associated with the id:

{
  "errors": null,
  "response": [
     {
         "title": "Sales",
         "landingUrl": "www.yahoo.com",
         "description": "Sales - site link",
         "status": "ACTIVE",
         "id": 1234,
         "advertiserId": 925746
     }
  ]
}

Method: To retrieve data for a shared sitelink with multiple IDs, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/sharedsitelink?id=1234&id=5678

    The response will be the shared sitelinks associated with multiple ids:

    {
      "errors": null,
      "response": [
         {
             "title": "Sales",
             "landingUrl": "www.yahoo.com",
             "description": "Sales - site link",
             "status": "ACTIVE",
             "id": 1234,
             "advertiserId": 925746
         },
         {
             "title": "Sports",
             "landingUrl": "www.yahoo.com",
             "description": "Sports - site link",
             "status": "ACTIVE",
             "id": 5678,
             "advertiserId": 925746
         }
      ]
    }

Read data for a filtered list of shared sitelinks

Method: To retrieve data for a filtered list of shared sitelinks, make a GET call with the following parameters:

Name	Description	Type
`mr`	The maximum number of rows to retrieve.	int
`si`	The start index or the first element to retrieve.	int
`advertiserId`	The ID of the advertiser to filter the shared sitelinks by.	long
`status`	The shared sitelink status to filter by.	enum

Important

Only one advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists of shared sitelink calls.

Endpoint¶

Resource URI

https://api.gemini.yahoo.com/v3/rest/sharedsitelink?advertiserId=1111

Create a new shared sitelink

Method: To create a new shared set, make a POST call. The response will be the newly created shared sitelink.

For example:

POST https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

Update existing shared sitelink

Method: To update existing shared sitelink, make a PUT call. The result will be the list of updated shared sitelink.

PUT  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

Delete a shared sitelink

Method: To delete a shared sitelink, make a PUT call.

Note

In v2, the DELETE operation is supported for both single and multiple ids.

For example:

DELETE  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/1234
DELETE  https://api.gemini.yahoo.com/v3/rest/sharedsitelink?id=1234&id=5678

PUT https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

{
  "status": "DELETED",
  "id": 103002
}

Read data for shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

Method: To retrieve data for a shared sitelink with carousel card assets, make a GET call:

GET  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

{
  "errors": null,
  "timestamp": "2021-03-23 2:00:40",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1615224905618,
      "createdDate": 1615221566639,
      "imageUrlHQ": null,
      "imageUrl": null,
      "editorialStatus": "PENDING_REVIEW"
   }
 }

Update existing shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

Method: To update an existing shared sitelink for carousel card assets, make a PUT call:

PUT  https://api.gemini.yahoo.com/v3/rest/sharedsitelink/

{
  "description": "Sales - site link",
  "landingUrl": "http://www.yahoo.com",
  "customParameters": null,
  "trackingUrl": null,
  "finalUrl": null,
  "title": "Sales",
  "mobileFinalUrl": null,
  "status": "ACTIVE",
  "advertiserId": 280,
  "id": 100010,
  "imageUrlHQ": "https://s.yimg.com/av/ads/1614745956105-8787.jpg",
  "imageUrl": "https://s.yimg.com/av/ads/1614745955282-1136.jpg"
}

Response

{
  "errors": null,
  "timestamp": "2021-03-23 2:02:36",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1616464956197,
      "createdDate": 1615221566639,
      "imageUrlHQ": "https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE_AND_CROP/1200x627/8603962bcba3b24c720ee73f9653ab5f.jpeg",
      "imageUrl": "https://s3.us-west-1.amazonaws.com/gemini-dev-public/curveball/ads/gi/RESIZE/627x627/405a14ab2a5f75a2ae989781a219bd04.jpeg",
      "editorialStatus": "PENDING_REVIEW"
  }
}

Delete existing shared sitelink for carousel card assets (imageUrlHQ or imageUrl)

To delete imageUrlHQ or imageUrl, you can pass the empty string “” in the PUT payload like this:

{
  "description": "Sales - site link",
  "landingUrl": "http://www.yahoo.com",
  "customParameters": null,
  "trackingUrl": null,
  "finalUrl": null,
  "title": "Sales",
  "mobileFinalUrl": null,
  "status": "ACTIVE",
  "advertiserId": 280,
  "id": 100010,
  "imageUrlHQ": "",
  "imageUrl": ""
}

Response should be:

{
  "errors": null,
  "timestamp": "2021-03-23 2:04:59",
  "response": {
      "description": "Sales - site link",
      "landingUrl": "http://www.yahoo.com",
      "customParameters": null,
      "trackingUrl": null,
      "finalUrl": null,
      "title": "Sales",
      "mobileFinalUrl": null,
      "status": "ACTIVE",
      "advertiserId": 280,
      "id": 100010,
      "lastUpdateDate": 1616465099168,
      "createdDate": 1615221566639,
      "imageUrlHQ": null,
      "imageUrl": null,
      "editorialStatus": "PENDING_REVIEW"
  }
}