Announcements

Monday July 14th, 2008

Important: Some of Your Keywords to be "Unmapped"

What's Changing

As you may know, we use various matching technologies to link some bidded keywords to other terms that a searcher might use synonymously to look for them. This mapping connects some keywords with related synonyms, such as "car insurance" with "auto insurance."

Recently, advertisers have voiced a need to manage some of these synonyms separately, so that they can use separate bidding and creative strategies, tracking URLs and business goals. To give advertisers more control over their ads, we plan to remove a limited number of keyword mappings on July 29, 2008.

What does this mean for 3rd Party Providers?

Your advertisers may still receive traffic for these terms through the Advanced match type even after these terms are unmapped. For better control, however, we suggest adding these "new" terms to your advertisers' account, along with new tracking URLs, bids and ads.

For a full list of terms that will be unmapped on July 29, 2008 please click here. This file is subject to be removed at any time so please save a copy for your reference.

If you have further questions, please contact your Technical Account Manager or ews-help@yahoo-inc.com.

Posted by William McNeal at 3:30 PM

Wednesday July 2nd, 2008

EWS Version 3.2.0 to Sunset on July 15, 2008

This is an important and last reminder that all support for Enterprise Web Services Version 3.2.0 will be removed on July 15, 2008.

Please ensure that you have migrated to our current version to continue using the APIs without interruption. You can access all relevant documentation here.

If you have further questions, please contact your Technical Account Manager or ews-help@yahoo-inc.com.

Posted by William McNeal at 3:30 PM

Wednesday, April 16, 2008

EWS V.4.0.0 Has Been Released in Production

On April 15, 2008, Yahoo! Search Marketing released EWS Version 4.0.0 in our production environment. Version 4.0.0 is a major version release and includes features that are backward-incompatible. We urge you to complete your development on Version 4.0.0 as soon as possible, as we plan to deprecate EWS Version 3.2.0 on July 15, 2008.

New Features

EWS Version 4.0.0 supports a new variable minimum bids feature, which may significantly impact your bidding strategy. As part of this change, minimum bids are no longer fixed for all keywords--they may be higher or lower than $.10.

EWS Version 4.0.0 is configured to work with this new variable minimum bid system. Thus, if you do not upgrade to EWS Version 4.0.0, you may not be able to manage your account to its full potential.

What Do I Need to Do?

Prior to launching your new code into production, we strongly urge you to start experimenting with Version 4.0.0 in the EWS sandbox to safely make any required changes to your client application and test your implementation. Then, launch your new code into production as soon as possible.

Please note that the EWS documentation, available on the Technology Solutions Portal, explains the new features in more detail.

Questions?

For more information about our versioning process, please read our Versioning FAQs here.

If you have further questions, please contact your Technical Account Manager or ews-help@yahoo-inc.com.

Posted by William McNeal at 3:30 PM

Friday, February 22, 2008

Enterprise Web Services Version 4.0.0 Sandbox Has Launched

In the first half of 2008, Yahoo! Search Marketing is planning to launch a new version of the Enterprise Web Services (EWS) Marketing API. EWS Version 4.0.0 is a major version release and includes features that are backward-incompatible.

We're pleased to announce that EWS Version 4.0.0 has been released to the EWS sandbox, and we encourage you to log in and get familiar with it.

What Do I Need to Do?

We suggest that you first experiment with Version 4.0.0 in the EWS sandbox, make any required changes to your client application, and test your implementation. Then, be ready to switch over to production when the product release is ready later this year.

About this Release

• The Version 4.0.0 production release will occur approximately 30 days after the sandbox release.
• While EWS Version 3.0.0 will continue to be available in production for 90 days after EWS Version 4.0.0 is released, we recommend that you switch to Version 4.0.0 as soon as possible.
• EWS Version 3.0.0 will not be available after the 90-day transition period ends.
• This release is backward-incompatible. To take advantage of the new features, you will need to re-compile your code against Version 4.0.0 WSDLs.

New Features

The new features and changes in EWS Version 4.0.0 are summarized below.

Variable Minimum Bids

In the next several weeks, we plan to change our system so that minimum bids will no longer be fixed for all keywords; they may be higher or lower than $.10. Minimum bids may vary by keyword, ad group and advertiser. EWS Version 4.0.0 is configured to work with variable minimum bids. Thus, if you do not upgrade to EWS Version 4.0.0, you may not have full control over your ads and keywords.

New EWS Service Operations

New operations have been added to the following services with the release of EWS Version 4.0.0:

AdGroupService

• getContentMatchMinBidForAdGroupOptimizationGuidelines: Returns Content Match min bid for ad group optimization guidelines by ad group ID.
• getSponsoredSearchMinBidForAdGroup: Returns Sponsored Search min bid for an ad group by adgroup ID.
• getSponsoredSearchMinBidForAdGroupOptimizationGuidelines: Returns Sponsored Search min bid for ad group optimization guidelines by ad group ID.
• getSponsoredSearchMinBidForAdGroups: Returns Sponsored Search min bid for multiple ad groups by multiple adgroup IDs.

AdService

• getAdsByAdGroupByParticipatesInMarketplace: Returns ads by ad group by marketplace participation.
• getReasonsForAdNotParticipatingInMarketplace: Returns reasons for an ad not participating in a marketplace.

CampaignService

• getMinBidForCampaignOptimizationGuidelines: Returns minBid for Campaign Optimization Guidelines by campaign ID.

KeywordService

• getKeywordsByAdGroupByParticipatesInMarketplace: Returns keywords by ad group by marketplace participation.
• getKeywordsByAdGroupBySponsoredSearchBidStatus: Returns keywords by ad group by Sponsored Search bid status.
• getReasonsForKeywordNotParticipatingInMarketplace: Returns reasons for a keyword not participating in a marketplace.
• getSponsoredSearchMinBidForKeywordOptimizationGuidelines: Returns Sponsored Search min bid for keyword optimization guidelines.
• getSponsoredSearchMinBidForKeywordString: Returns Sponsored Search min bid by keyword.
• getSponsoredSearchMinBidForKeywordStrings: Returns Sponsored Search min bids for multiple keywords.
• getSponsoredSearchMinBidUpdatesByAdGroupId: Returns the updates to Sponsored Search min bids by ad group.

New EWS Data Objects

The following new data objects have been added with the release of EWS Version 4.0.0:

• BidStatus
• BidUpdateInfo
• NotParticipatingInMarketplaceReason
• SponsoredSearchMinBidRequest
• Warning

New EWS Data Object Elements

New elements have been added to the following data objects with the release of EWS Version 4.0.0:

• Ad
• AdGroup
• Keyword
• All response objects (AdGroupResponse, AdResponse, BasicResponse, and so on)

Deprecated Features

The Bid InformationService getMinBidForKeywordString operation has been deprecated in EWS Version 4.0.0 (refer to the new KeywordService getSponsoredSearchMinBidForKeywordString operation).

Questions?

For more information about our versioning process, please read our Versioning FAQs here.

If you have further questions, please contact your Technical Account Manager or ews-help@yahoo-inc.com.

Sincerely,

Your Partners at Yahoo! Search Marketing

Posted by William McNeal at 3:30 PM

Monday, December 03, 2007

Using the Current WSDLs

The WSDLs linked to in the Getting Started Guide portion of the documentation are for reference only. We suggest you use the WSDLs served by the web services themselves, which can be accessed by appending "?wsdl" to the service endpoint.

Example:

CampaignService WSDL:

Sandbox: https://sandbox.marketing.ews.yahooapis.com/services/V3/CampaignService?wsdl

Production: https://global.marketing.ews.yahooapis.com/services/V3/CampaignService?wsdl

Please use this going forward.

Posted by William McNeal at 2:52 PM

Wednesday, November 28, 2007

EWS V3.1.0 is Live!

Yahoo! Search Marketing has launched a new version of the Enterprise Web Services (EWS) Marketing API into production. EWS Version 3.1.0 is a minor version release and is backward-compatible.

New Features

This minor version upgrade provides optional headers for "on-behalf-of" authorizations, which are contained in the new WSDLs. This means that you no longer need to modify a WSDL to include the optional headers. This upgrade only impacts users who perform work on behalf of others, but we understand that this is a much requested enhancement for these users and we are excited to make this available to you.

EWS V2.2.0 will be supported in our production system into January 2008, at which time it will be deprecated. We therefore recommend you switch to EWS V3.1.0 at your earliest convenience. EWS V3.1.0 is also live in the sandbox environment.

Sincerely,

Your Partners at Yahoo! Search Marketing

Posted by William McNeal at 3:30 PM

Friday, May 11, 2007

Keeping Your System Synchronized With Ours

Clients that maintain a local view of their Search Marketing accounts can, over time, see a divergence in their view of the data from the actual underlying information. This happens because changes to the account may initiate from many places: the advertiser UI, the API, or from within Yahoo! itself. If you are finding yourself in such a situation, and need to keep your system in sync with ours, we recommend following these steps:

1. Use the getCampaignsByAccountID command to get a list of all campaigns in your account.
2. For each campaign, use the getAdGroupsByCampaignID command to get a list of ad groups.
3. For each ad group, use the getKeywordsByAdGroupID and getAdsByAdGroupID commands to sync up keywords and ad accordingly.
4. At this point, you now have a basic representation of your account structure. Note that you may need to also fetch excluded keywords, optimization settings, geo-targeting settings, etc if you use them.

For clients that focus on keyword-level tracking URLs:

1. Use the getKeywordsByAccountID command in the KeywordService to get a clean list of which keywords actually exist in the account.
2. As you encounter keywords that are not in your own system, add them, creating your internal reference, or ID.
3. Use the updateKeywords command to update the URL to include your new internal reference or ID.

Posted by William McNeal at 10:30 AM

Thursday, September 14, 2006

Frequency Limits

Definitions and Details

To prevent abuse of our systems, there are frequency limits in place that you should be aware of. These limits are not a feature of your license key and are not a matter of quota. Two limit measurements exist:

• Per IP address: 400 requests per second (rps), for a sustained period (sliding window) of 3 minutes.
• Per license key: 400 rps for a sustained period of 3 minutes.

The penalty for exceeding these limits is a 5 minute "cooling off" period. Should you run into this penalty period, you will experience the following behavior:

• Per IP limit: Client will see "connection closed" immediately. The TCP connection is simply terminated.
• Per license limit: Client will receive a SOAP fault with relevant error message.

It is important to note the distinction between how requests are counted for these two measurements.

• Per IP limit: The request, regardless of size or number of components is counted as 1 request.
• Per license limit: 'Get' operations are 1 request total. 'Set' operations (add/update) are counted as 1 request per incoming object.

Our sliding window is defined as a look-back period of n minutes (as specified above) where our system can measure the rate of incoming requests. Being a sustained rate means that rate of requests must remain above the set threshold to invoke a penalty.

None of this information should be confused with connection timeouts; the above scenarios do not result in a timeout. Our servers are currently set to timeout requests after 10 minutes. Each client, however, can control their own timeout threshold. We suggest tuning this timeout based on your own needs; as a default, try something longer than 10 minutes and allow our servers to initiate the timeout.

Posted by Matt Plummer at 11:34 PM