Announcements

Wednesday, July 1st, 2009

Enterprise Web Services Version 4.3.0 to Sunset on 8/31/09

Important notice: EWS v4.3.0 will be deprecated on August 31, 2009. After this date, EWS v4.3.0 requests will not be serviced, so we highly recommend that you migrate your applications to EWS v5.0 prior to August 31.

What’s New in EWS v5.0

EWS v5.0 provides increased targeting options, including enhanced geographical, demographic and dayparting. It also includes enhancements to domain blocking and reporting functions.

What Do I Need to Do?

Prior to launching your new code into production, we strongly urge you to start experimenting with Version 5.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.

For more details on these changes, please review the EWS v5.0 release notes.

Questions?

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

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

Posted by William McNeal at 11:00 AM

Monday, March 16th, 2009

EWS Version 5.0.0 Has Been Released in Production

On March 16, 2009, Yahoo! Search Marketing released EWS Version 5.0.0 in production environment. Version 5.0.0 is a major-version release, and includes features that are backward-incompatible. We urge you to complete your development on Version 5.0.0 as soon as possible, as we plan to deprecate EWS Version 4.x.x 90 days after production launch.

New Features

Take advantage of Yahoo!'s enhanced targeting capabilities in EWS Version 5.0.0:

Geo-targeting Enhancements

• Flexibility to control at the campaign or ad group levels
• Bid adjustment option
• Ability to geo-target at multiple levels within the same campaign/ad group

Demographic Preferences

• Under-age Filtering (age 17 and under)
• Bid adjustment options for specific age and gender audiences

Ad Scheduling (Dayparting)

• Day-of-week and time-of-day filtering based on audience or advertiser time zone
• Bid adjustment options for specific one-hour increments

Improved Forecasting

• Forecasting available per targeting dimension
• Content Match forecasting

What Do I Need to Do?

Prior to launching your new code into production, we strongly urge you to start experimenting with Version 5.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.

The major new features are explained in detail in the release notes available on our Technology Portal.

Questions?

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

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

Posted by William McNeal at 10:00 AM

Wednesday, January 21nd, 2009

Enterprise Web Services Version 5.0.0 Sandbox Has Launched

In the first half of 2009, Yahoo! Search Marketing is planning to launch a new version of the Enterprise Web Services (EWS) Marketing API. EWS Version 5.0.0 is a major version release, and includes features that are backward-incompatible. \ EWS Version 5.0.0 has now been released to the EWS sandbox.

What Do I Need to Do?

We suggest that you first experiment with Version 5.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.

About this Release

• EWS Version 5.0.0 has been released to the EWS sandbox.
• The production release will occur approximately 30 days after the sandbox release.
• While EWS Version 4.x.x will continue to be available in production for 90 days after EWS Version 5.0.0 is released, we recommend that you switch to Version 5.0.0 as soon as possible.
• EWS Version 4.x.x 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 5.0.0 WSDLs.

New Features

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

Enhanced Targeting

• Demographic targeting based on population classifications like gender and age range.
• Dayparting targeting based on the audience time of the day
• Country level targeting is now supported for AU, CA and UK.
• Advertisers can now target varied geographical levels in one campaign/ad group.

More Domain Blocking
The number of domains that can be blocked at the account level has been increased from 250 to 500.

Account And Campaign Spend Caps In addition to campaign spend limits for all markets, advertisers in the US market can specify a tactic based cap on the daily spend limit.

Change in UK Credit Card Support
In the UK market, we've changed support for credit cards from SWITCH to MAESTRO.

More Domain Blocking
The number of domains that can be blocked at the account level has been increased from 250 to 500

Enhanced Documentation

• A wireframe-like UI, increased usability and easy-to-use navigation
• Site search includes suggestion capability
• Java and Perl sample code for selected APIs, which can be downloaded

For detailed release notes please refer to the change log page.

Questions?

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

Monday, October 27nd, 2008

Enterprise Web Services Version 4.3.0 is Live!

On October 24, 2008, Yahoo! Search Marketing EWS Version 4.3.0 went live in our production and sandbox environment. EWS Version 4.3.0 is a minor version release, and all new features are backwards-compatible.

To take advantage of the new features in Version 4.3.0, you will need to recompile your client code for Version 4.0.0, if you have not already done so.

We suggest that you first experiment with the new version in the EWS sandbox, make any required changes to your client application, and then test your implementation. When you are satisfied with the results, you can move your client application to production.

New Features

1) Bulk Command Group
Bulk Service provides the capability to download an account's objects using a file based on the Yahoo! Sponsored Search bulk template.

2) Beta Command Group
With this release we are introducing a new concept: Beta APIs. The goal of Beta APIs is to release early versions of an API, providing the opportunity for EWS users to integrate and test the newest functionality. This concept allows for flexibility in releases, an opportunity to test new features, and a refreshing way to foster innovation, speed and flexibility.

3) New Geo-Targeting Features
In this release we are improving the way you get locations by exposing the WOEIDs (Where On Earth IDs). We are also offering the ability to more precisely target by geographical location by exposing new targeting criteria, including at the country, city and zip levels (only applicable to the U.S. market in this release).

The new geo-targeting APIs can be found in the Beta command group mentioned above.

Questions?

If you have further questions, please contact your Technical Solutions Manager or email us at: ews-help@yahoo-inc.com.

Posted by William McNeal at 3:30 PM

Friday, August 22nd, 2008

Enterprise Web Services Version 5.0 Coming Soon

Yahoo! Search Marketing is planning to launch a new version of the Enterprise Web Services (EWS) Marketing API. EWS Version 5.0 will be a major version release and include features that are backward-incompatible.

About this Release

• EWS Version 5.0 is expected to be released to the EWS sandbox in the fourth quarter of 2008.
• The production release will occur approximately 30 days after the sandbox release.
• While EWS Version 4.x.x will continue to be available in production for 90 days after EWS Version 5.0 is released, we recommend that you switch to Version 5.0 as soon as possible.
• EWS Version 4.x.x 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 5.0 WSDLs.

What Do I Need to Do?

We suggest that you first experiment with Version 5.0 in the EWS sandbox when available, 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. Look for more detailed updates regarding this release soon.

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, August 22nd, 2008

Enterprise Web Services Version 5.0 Coming Soon

Yahoo! Search Marketing is planning to launch a new version of the Enterprise Web Services (EWS) Marketing API. EWS Version 5.0 will be a major version release and include features that are backward-incompatible.

About this Release

• EWS Version 5.0 is expected to be released to the EWS sandbox in the fourth quarter of 2008.
• The production release will occur approximately 30 days after the sandbox release.
• While EWS Version 4.x.x will continue to be available in production for 90 days after EWS Version 5.0 is released, we recommend that you switch to Version 5.0 as soon as possible.
• EWS Version 4.x.x 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 5.0 WSDLs.

What Do I Need to Do?

We suggest that you first experiment with Version 5.0 in the EWS sandbox when available, 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. Look for more detailed updates regarding this release soon.

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

Monday July 28th, 2008

EWS V4.2.0 is Live!

EWS Version 4.2.0 is a minor version release. All new features are backward compatible. To take advantage of the new features in Version 4.2.0 you will need to recompile your client code for Version 4.0.0 if you have not already done so.

EWS Version 4.2.0 will be released to the EWS sandbox as well as to production. We suggest that you first experiment with the new version in the EWS sandbox, make any required changes to your client application, and then test your implementation. When you are satisfied with the results, you can move your client application to production.

New Features

The new features and changes in EWS Version 4.2.0 are summarized here.

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