API Queries - Update Keyword

The update_keyword function allows you to change settings or the status of an existing Keyword. This function requires additional parameters. Although optional parameters are not all required, at least one must be included. Failing to include required parameters or at least one optional will result in an error response.


Additional Parameters

  • keyword - Name of Keyword to update. (Required)
  • traffic_type - The traffic type, either "desktop", "mobile" or "all". (Required)
  • my_bid - Your bid for the keyword. (Optional)
  • daily_limit - Daily spend limit for the keyword. (Optional)
  • negative - Any negative keywords, comma separated. (Optional)
    Note: If this attribute is defined, any previous negative keywords will be replaced with the new ones.
  • target_url - The Target URL, including http:// (Optional)
  • active - To Stop or Activate the keyword, use values 0 or 1, respectively. (Optional)
  • geo_target - The Geo Target, either "all", "us", "uk", "ca", "au", "nz", "in", "br", "de", "fr", "nl", "it", or "es". (Required)
  • freq_cap - Limit on number of visits per unique user in 24 hour period. Choose from "3", "6" or "12". (Optional)
  • bl_subid - Adds subid to blacklist. (Optional)
  • del_bl_subid - Removes blacklisted subid. (Optional)
  • wl_subid - Adds subid to whitelist. (Optional)
    • premium_bid - Premium bid amount for whitelisted subid. (Required)
    • other_subid_traffic - Allow traffic from whitelisted subids plus all other subids associated with this campaign.
      On is 1 and off is 0. Default is 1 (on). (Optional)
  • del_wl_subid - Removes subid from whitelist. (Optional)
  • remarketing_multiple - Set your max bid for the remarketed visit at multiple times the original cpc price. Minimum is "2". "0" means to turn remarketing off. (Optional)

Notes:

  • The traffic_type and geo_target parameters are used to select the correct keyword and will not be changed.
  • Make sure to URL encode all values, most importantly the target_url value.

Example queries and responses:

  • In this example, we will be stopping the keyword "credit cards" with the geo target "all" and the traffic type "mobile".

    Example query:



    https://bid.trellian.com/api.html?username=user&api_key=key&mode=update_keyword&
    keyword=credit%20cards&geo_target=all&traffic_type=mobile&active=0

    Note the URL encoding on the values.

    Response:



    <results>
<result Setting="Active" Success="1" Value="0"/>
</results>

    The result for the setting update will be shown (represented by Success="1", meaning it was successful). The above response means that the Keyword's status is now stopped (represented by Value="0").


  • In this example, we will be updating the keyword "credit cards" with the geo target "all" and traffic type "desktop" to a bid of $5, daily spend of $200, negative keyword "interest free", target URL http://www.trellian.com.

    Example query:



    https://bid.trellian.com/api.html?username=user&api_key=key&mode=update_keyword&
    keyword=credit%20cards&traffic_type=desktop&my_bid=5.00&daily_limit=200.00&negative=interest%20free&
    target_url=http%3A%2F%2Fwww.trellian.com&geo_target=all

    Note the URL encoding on the values.

    Response:



    <results>
<result Setting="NegativeKeywords" Success="1" Value="interest free"/>
<result Setting="MaxBid" Success="1" Value="$5.000"/>
<result Setting="DailySpendLimit" Success="1" Value="$200.00"/>
<result Setting="TargetUrl" Success="1" Value="http://www.Trillion.com"/>
</results>

    The result for each setting update will be shown (represented by Success="1", meaning it was successful). If the setting could not be updated for any reason, the result for that setting will be Success="0". If any of your values were the incorrect format or out of range, an error response will be returned and no settings will be updated.


  • In this example, we will be updating the keyword "credit cards" with the geo target "all" and traffic type "desktop" to a premium bid on the subid 123456 of $20.

    Example query:



    https://bid.trellian.com/api.html?username=user&api_key=key&mode=update_keyword&
    keyword=credit%20cards&traffic_type=desktop&geo_target=all&wl_subid=123456&premium_bid=20

    Note the URL encoding on the values.

    Response:



    <results>
<result Setting="WhiteListSubID" Success="1" Value="123456"/>
</results>

Error Responses:

Possible error responses for this function are:

For a complete list of error responses, see the Error Codes manual page.