Keyword¶

Abstract¶

The Keyword object specifies the search keyword phrase that you would like to target.

Overview¶

Using this service, you can set and manage keyword match types as well as keyword-level bids. Note that bids that are set at the keyword level override bids that are set at higher levels.

Fields¶

The Keyword object contains the following fields:

Name	Description	Type	Add	Update
`advertiserId`	The ID of the advertiser associated with the keyword. This field cannot be updated.	long	Required	Optional (Read-Only)
`bidSet`	Keywords can carry bids that override any bids set at the ad group level. See the example representation below for an example on how to set a bid at the keyword level. In order to clear a bid for a given keyword, pass in an empty bid value when updating the keyword. Note that this is not applicable for negative keywords (`exclude=TRUE`)	`BidSet[]`	Required	Optional
`exclude`	Specifies whether to exclude (`TRUE`) or include (`FALSE`) for targeting.	enum	Required	Optional
`id`	The ID of the keyword.	long	N/A	Required
`matchType`	The serving matching algorithm. Supported match types: For positive keywords (`exclude=FALSE`): BROAD EXACT PHRASE For negative keywords (`exclude=TRUE`): PHRASE EXACT	enum	Required	Optional. Note that `matchType` is not required when adding a keyword and will default to BROAD if not provided.
`parentId`	The ID of the ad group the keyword belongs to. If it is a negative keyword (`exclude=TRUE`) then the parent can be a campaign.”	long	Required	Required
`parentType`	The type of parent. For a keyword object, this value is typically ADGROUP. It can also be CAMPAIGN for negative keywords (`exclude=TRUE`).	enum	Required	Required
`status`	The status of the keyword. Valid input values are: `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. See also the keyword level statuses table below for more details on this field. Note that `status` is not required when creating any object type and will default to ACTIVE if not provided. For negative keywords (`exclude=TRUE`), status can only be ACTIVE or DELETED. For regular positive keywords (`exclude=FALSE`), ACTIVE, PAUSED, DELETED, REJECTED with existing info applies.	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 is not applicable for negative keywords (`exclude=TRUE`). Note also that this field is read-only for Adds (creates) and Updates	enum	Read-only	Read-only
`value`	The actual keyword. Maximum limit is 255 characters. Please note that value for an existing keyword cannot be updated. In order to update this field, a new keyword must be created. Therefore this field will be ignored if passed when attempting to update a keyword.	string	Required	Optional
`adParamValues`	The values that are substituted at serve time within the Ad “`{param#:<default value>}`” macro for the matched bidded keyword. Refer to Keyword Insertion and Dynamic Text for more information. In order to clear an ad param previously set for a given keyword, pass in an empty value for the param, or an empty array to clear all the params. Note applicable for negative keywords (`exclude=TRUE`).	`AdParamValue[]`	Optional	Optional
`landingUrl`	The landing page URL is the web address that a user is sent to after clicking on the ad triggered by the keyword. A URL set at the keyword level overrides the landing URL set at the ad level. Maximum limit is 2048 characters. Not applicable for negative keywords (`exclude=TRUE`).	`string`	Optional	Optional

The Entity Status and Editorial Status

v3 Upgraded URL Attributes¶

Important

For the v3 Yahoo Native API, Upgraded URL (UU) attributes are now supported for the Keyword object type.

The following table describes the supported UU attributes per the Keyword object type.

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

Note

dp stands for deprecated in the above table.

Note

The landing page url is deprecated only for search. The Final url is 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 in v3, refer to Upgraded URLs.

Keyword level statuses¶

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

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

Endpoint¶

Resource URI

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

Example Representations¶

Keyword

{
  "value": "Your keyword 1",
  "id": 282782226512,
  "status": "ACTIVE",
  "advertiserId": 11610,
      "parentType": "ADGROUP",
      "parentId": 7237162494,
      "landingUrl": "https://www.yahoo.com",
      "exclude": "FALSE",
  "bidSet": {
      "id": null,
      "bids": [
          {
              "priceType": "CPC",
              "value": 2,
              "channel": "SEARCH"
          }
      ]
  },
  "matchType": "EXACT"
  "adParamValues": null
}

Keyword Array

[
  {
      "value": "Your keyword 1",
      "id": 282782226512,
      "status": "ACTIVE",
      "advertiserId": 11610,
              "parentType": "ADGROUP",
              "parentId": 7237162494,
              "landingUrl": "https://www.yahoo.com",
              "exclude": "FALSE",
      "bidSet": {
          "id": null,
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              }
          ]
      },
      "matchType": "EXACT",
      "adParamValues": null
  },
  {
      "value": "Your keyword 2",
      "id": 282782226513,
      "status": "ACTIVE",
      "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": "https://www.yahoo.com",
          "exclude": "FALSE",
      "bidSet": {
          "id": null,
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 1.5,
                  "channel": "SEARCH"
              }
          ]
      },
      "matchType": "EXACT",
      "adParamValues": null
  }
]

Keyword Response

{
  "errors": null,
  "response": {
      "value": "Your keyword 1",
      "id": 282782226512,
      "status": "ACTIVE",
      "advertiserId": 11610,
              "parentType": "ADGROUP",
              "parentId": 7237162494,
              "landingUrl": "https://www.yahoo.com",
              "exclude": "FALSE",
      "bidSet": {
          "id": null,
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              }
          ]
      },
      "matchType": "EXACT"
      "adParamValues": null
  }
}

Example Representation of UU¶

The following is a JSON snippet of UU attributes that resides in a Keyword object:

{

...

    "finalUrl": "https://www.mywebsite.com/c/10366",
    "mobileFinalUrl": "https://m.mywebsite.com/c/10366",
    "trackingUrl": "{lpurl}?source=YAHOO&kw={keyword}&mt={matchtype}&camp={campaignid}&p1={_param1}&p2={_param2}&p3={_param3}",
    "customParameters": [
         {
                 "key": "param1",
                 "value": "abc"
         },
         {
                 "key": "param2",
                 "value": "xyz"
         }
    ],
    "displayUrlPath1": "promo",
    "displayUrlPath2": null,
...

}

Operations¶

Read specific keyword data

Method: To retrieve data for a specific keyword, make a GET call with the id parameter.

For example:

https://api.gemini.yahoo.com/v3/rest/keyword/282782226512

Response: The keyword associated with the given ID.

{
  "errors": null,
  "response": {
      "value": "Your keyword 1",
      "id": 282782226512,
          "status": "ACTIVE",
          "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": "https://www.yahoo.com",
          "exclude": "FALSE",
      "bidSet": {
          "id": null,
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              }
          ]
      },
      "matchType": "EXACT",
      "adParamValues": null
  }
}

Example: You can also make a GET call and pass in multiple IDs. Please note that when you pass multiple IDs, all other filters besides id will be ignored:

https://api.gemini.yahoo.com/v3/rest/keyword/?id=282782226512&id=282782226513

Response: The keywords associated with the given IDs:

 {
   "errors": null,
   "response": [
     {
       "value": "Your keyword 1",
       "id": 282782226512,
           "status": "ACTIVE",
           "advertiserId": 11610,
           "parentType": "ADGROUP",
           "parentId": 7237162494,
           "landingUrl": "https://www.yahoo.com",
           "exclude": "FALSE",
       "bidSet": {
           "id": null,
           "bids": [
               {
                 "priceType": "CPC",
                 "value": 2,
                 "channel": "SEARCH"
               }
           ]
       },
       "matchType": "EXACT",
       "adParamValues": null
   },
   {
       "value": "Your keyword 2",
       "id": 282782226513,
       "status": "ACTIVE",
       "advertiserId": 11610,
       "parentType": "ADGROUP",
       "parentId": 7237162494,
       "landingUrl": "https://www.yahoo.com",
       "exclude": "FALSE",
       "bidSet": {
         "id": null,
         "bids": [
           {
              "priceType": "CPC",
              "value": 1.5,
              "channel": "SEARCH"
           }
        ]
     },
     "matchType": "EXACT",
     "adParamValues": null
    }
  }
}

Read data for filtered list of keywords

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

Name	Description	Type	Required?
`exclude`	The exclude flag. This is either true for negative keywords or false for positive keywords.	boolean	Optional
`mr`	The maximum number of rows to retrieve.	int	Optional
`parentId`	The ID of the parent to filter the keywords by.	long	Yes
`parentType`	The type of parent to filter by. Valid values are: CAMPAIGN ADGROUP	enum	Yes
`si`	The start index or the first element to retrieve.	int	Optional
`value`	The keyword value.	enum	Optional
`status`	The status of the filtered list of keywords.	enum
`advertiserId`	The ID of the advertiser associated with the keyword. This field cannot be updated.	long	Required

Important

Only one parentId or advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists keyword calls.

Example: GET call to fetch negative keywords for a given ad group:

https://api.gemini.yahoo.com/v3/rest/keyword/?parentId=46756&parentType=ADGROUP&exclude=true

Response: The response will be the list of keywords that match the given filter:

{
  "errors": null,
  "response": {
          "value": "Negative keyword",
          "id": 282782,
          "status": "ACTIVE",
          "advertiserId": 11610,
              "parentType": "ADGROUP",
              "parentId": 46756,
              "landingUrl": "https://www.yahoo.com",
              "exclude": "TRUE",
              "bidSet": null,
              "matchType": "EXACT",
              "adParamValues": null
  }
}

Example: You can also make a GET call to fetch keywords filtered by multiple ad group IDs:

https://api.gemini.yahoo.com/v3/rest/keyword/parentType=ADGROUP&parentId=1&parentId=2

Response: The list of keywords that match the given filter:

{
  "errors": null,
  "response": [
      {
                "value": "Keyword from one ad group",
                "id": 282782226512,
                "status": "ACTIVE",
                "advertiserId": 11610,
                "parentType": "ADGROUP",
                "parentId": 1,
                "landingUrl": "https://www.yahoo.com",
                "exclude": "FALSE",
                "bidSet": {
                   "id": null,
                   "bids": [
                      {
                         "priceType": "CPC",
                         "value": 2,
                         "channel": "SEARCH"
                       }
                      ]
                  },
                  "matchType": "EXACT",
                  "adParamValues": null
                },
                {
                  value": "Another keyword from the ad group",
                  "id": 282782226513,
                  "status": "ACTIVE",
                  "advertiserId": 11610,
                  "parentType": "ADGROUP",
                  "parentId": 1,
                  "landingUrl": "https://www.yahoo.com",
                  "exclude": "FALSE",
                  "bidSet": {
                      "id": null,
                      "bids": [
                         {
                            "priceType": "CPC",
                            "value": 1.5,
                            "channel": "SEARCH"
                          }
                       ]
                   },
                   "matchType": "EXACT",
                       "adParamValues": null
                              },
                              {
                                  "value": "Keyword from the other ad group",
                                  "id": 282782226514,
                                  "status": "ACTIVE",
                                  "advertiserId": 11610,
                                  "parentType": "ADGROUP",
                                  "parentId": 2,
                                  "landingUrl": null,
                                  "exclude": "FALSE",
                                  "bidSet": null,
                                  "matchType": "BROAD",
                                  "adParamValues": null
                              }
                          ]
                      }

Update existing keywords

Method: To update existing keywords, make a PUT call with one or more keyword objects. The result will be the list of updated keywords. For example, to update a bid for multiple keywords:

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

Data passed

[
  {
      "id": 282782226512,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2,
                  "channel": "SEARCH"
              }
          ]
      }
  },
  {
      "id": 282782226513,
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 1.5,
                  "channel": "SEARCH"
              }
          ]
      }
  }
]

Example response

{
  "errors": null,
  "response": [
      {
          "value": "Your keyword 1",
          "id": 282782226512,
          "status": "ACTIVE",
          "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": "https://www.yahoo.com",
          "exclude": "FALSE",
          "bidSet": {
              "id": null,
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2,
                      "channel": "SEARCH"
                  }
              ]
          },
          "matchType": "EXACT",
          "adParamValues": null
      },
      {
          "value": "Your keyword 2",
          "id": 282782226513,
          "status": "ACTIVE",
          "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": "https://www.yahoo.com",
          "exclude": "FALSE",
          "bidSet": {
              "id": null,
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 1.5,
                      "channel": "SEARCH"
                  }
              ]
          },
          "matchType": "EXACT",
          "adParamValues": null
      }
   ]
}

Create a new keyword

Method: To create new keywords, make a POST call with one or more keyword objects. The response will be the newly created keywords.

For example:

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

Data passed

[
  {
      "advertiserId": 11610,
      "parentType": "ADGROUP",
      "parentId": 7237162494,
      "value": "newkeyword1",
      "matchType": "EXACT",
      "exclude": "FALSE",
      "status": "ACTIVE",
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 3,
                  "channel": "SEARCH"
              }
          ]
      }
  },
  {
      "advertiserId": 11610,
      "parentType": "ADGROUP",
      "parentId": 7237162494,
      "value": "newkeyword2",
      "matchType": "EXACT",
      "exclude": "FALSE",
      "status": "ACTIVE",
      "bidSet": {
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 2.5,
                  "channel": "SEARCH"
              }
          ]
      }
  }
]

Example response

{
  "errors": null,
  "response": [
      {
          "value": "newkeyword1",
          "id": 289344782063,
          "status": "ACTIVE",
          "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": null,
          "exclude": "FALSE",
          "bidSet": {
              "id": null,
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 3,
                      "channel": "SEARCH"
                  }
              ]
          },
          "matchType": "EXACT",
          "adParamValues": null
      },
      {
          "value": "newkeyword2",
          "id": 289344782064,
          "status": "ACTIVE",
          "advertiserId": 11610,
          "parentType": "ADGROUP",
          "parentId": 7237162494,
          "landingUrl": null,
          "exclude": "FALSE",
          "bidSet": {
              "id": null,
              "bids": [
                  {
                      "priceType": "CPC",
                      "value": 2.5,
                      "channel": "SEARCH"
                  }
              ]
          },
          "matchType": "EXACT",
          "adParamValues": null
      }
   ]
}

Create a new negative keyword

Method: To create a new keyword, make a POST call with the keyword object and set exclude=TRUE. Supported match types for negative keywords are either EXACT or PHRASE. You can set negative keywords at both the ad group and the campaign levels. Indicate the level at which the negative keyword should be set using the parentType attribute:

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

Data passed

{
  "advertiserId": 11610,
  "parentType": "CAMPAIGN",
  "parentId": 334418145,
  "value": "negativekeywordCampaign",
  "matchType": "EXACT",
  "exclude": "TRUE",
  "status": "ACTIVE"
}

Example response

{
  "errors": null,
  "response": {
      "value": "negativekeywordCampaign",
      "id": 289344787160,
      "status": "ACTIVE",
      "advertiserId": 11610,
      "parentType": "CAMPAIGN",
      "parentId": 334418145,
      "landingUrl": null,
      "exclude": "TRUE",
      "bidSet": null,
      "matchType": "EXACT",
      "adParamValues": null
  }
}

Delete a keyword

Method: To delete a keyword, make a PUT call with the keyword object. The following parameters are required:

Field	Description
`id`	The ID of the keyword to delete.
`status`	The status of the keyword set to `DELETED` to delete the keyword.

Note

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

For example:

PUT https://api.gemini.yahoo.com/v3/rest/keyword/
DELETE https://api.gemini.yahoo.com/v3/rest/keyword/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/keyword?id=123&id=1234&...

Data passed

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

Example response

{
  "errors": null,
  "response": {
      "value": "negativekeywordCampaign",
      "id": 289344787160,
      "status": "DELETED",
      "advertiserId": 11610,
      "parentType": "CAMPAIGN",
      "parentId": 334418145,
      "landingUrl": null,
      "exclude": "TRUE",
      "bidSet": null,
      "matchType": "EXACT",
      "adParamValues": null
  }
}

AdParamValue Object

The following parameters are supported.

Parameter	Description	Required?
`paramIndex`	The index for params (1, 2, and 3), which identifies which placeholder must use which replacement text. Valid values are 1, 2, and 3.	Yes
`insertionText`	The substitution text to display on the ad. The character limit for the insertionText of paramIndex=1 is 1022. The character limit for the insertionText of paramIndex=2 and paramIndex=3 is 70 each.	Yes

Example

This example shows how to set adParam1 and adParam2 when updating a keyword:

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

Data passed

{
  "id": 289344782063,
  "adParamValues": [
      {
          "paramIndex": 1,
          "insertionText": "dynamic text for param1"
      },
      {
          "paramIndex": 2,
          "insertionText": "dynamic text for param2"
      }
  ]
}

Example response

{
  "errors": null,
  "response": {
      "value": "newkeyword1",
      "id": 289344782063,
      "status": "ACTIVE",
      "advertiserId": 11610,
      "parentType": "ADGROUP",
      "parentId": 7237162494,
      "landingUrl": null,
      "exclude": "FALSE",
      "bidSet": {
          "id": null,
          "bids": [
              {
                  "priceType": "CPC",
                  "value": 3,
                  "channel": "SEARCH"
              }
          ]
      },
      "matchType": "EXACT",
      "adParamValues": [
          {
              "paramIndex": 2,
              "insertionText": "dynamic text for param2"
          },
          {
              "paramIndex": 1,
              "insertionText": "dynamic text for param1"
          }
      ]
  }
}

bidSet object¶

The bidSet object is used to specify bids.

Both the ad group and the keyword objects can carry bids. As a rule, the lower level bid (keyword is the lowest level) overrides bids set at a higher level. Ad groups that run on mobile search, for example, will carry a bid with a channel value of SEARCH and a priceType of CPC.

Please note that in order to have your ads serve on a given channel, you need to set a bid for the channel. For native ads, a bid for channel=NATIVE needs to be set at the ad group level. For mobile search ads, either a default bid for channel=SEARCH at the ad group level or keyword level bids need to be set.

Refer to Ad Groups - bidSet object for more information on ad groups for carrying bids.

Example

Please see below for more information on how to set bids.

"bids": [
             {
           "priceType": "CPC",
           "value": 1.5,
           "channel": "NATIVE"},
             {
           "priceType": "CPC",
           "value": 2.5,
           "channel": "SEARCH"}
     ]

bids Fields

Parameter	Description	Required?
`channel`	The supply channel where the ads will run. Value can be: `SEARCH` - for mobile search ads. `NATIVE` - for native ads in native content streams.	Yes
`priceType`	The pricing type. Supported types are: `CPC` - only if campaign objective is INSTALL_WEB `CPM` - only if campaign objective is PROMOTE_BRAND `CPV` - only for video ads in either PROMOTE_BRAND or INSTALL_APP campaigns	Yes
`value`	The bid amount. Refer to Data Dictionary to look up currency by type.	Yes

Parameter

Description

Required?

channel

The supply channel where the ads will run. Value can be:

SEARCH - for mobile search ads.
NATIVE - for native ads in native content streams.

Yes

priceType

The pricing type. Supported types are:

CPC - only if campaign objective is INSTALL_WEB
CPM - only if campaign objective is PROMOTE_BRAND
CPV - only for video ads in either PROMOTE_BRAND or INSTALL_APP campaigns

Yes

value

The bid amount. Refer to Data Dictionary to look up currency by type.

Yes