- Open Source
- APIs
- Advertising
- Blog
- Events
- Podcasts
- Apps
- Native
- Documentation
- Yahoo Native to Yahoo DSP API Migration Guide
- Sign In
- Language:
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 |
---|---|---|---|---|
|
The ID of the shared sitelink. |
long |
required |
required |
|
The ID of the advertiser. |
long |
required |
optional |
|
The status of the shared sitelink. Valid values:
The |
enum |
required |
optional |
|
The editorial status of the ad. Valid values are:
The |
enum |
read-only |
read-only |
|
The title of the shared sitelink. |
string |
required |
optional |
|
The description of the shared sitelink. |
string |
optional |
optional |
|
The landing url of the shared sitelink. |
string |
required |
optional |
|
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 |
|
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 |
---|---|
|
The sitelink is running. |
|
The sitelink is paused and can be re-activated. |
|
The sitelink was declined due to policy violations. Further information is available in the Ad Manager UI. |
|
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 |
---|---|---|
|
The maximum number of rows to retrieve. |
int |
|
The start index or the first element to retrieve. |
int |
|
The ID of the advertiser to filter the shared sitelinks by. |
long |
|
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"
}
}