Release Notes - Yahoo! Search Marketing Enterprise Web Services

About These Release Notes

These release notes summarize the new features in the following EWS versions

6.0.0
5.2.0
5.1.0
5.0.0

Please refer the latest version of the EWS documentation for details.

EWS documentation continues to be enhanced, and is available on the Technology Solutions portal. We encourage you to read it to understand the internal functioning of the Search Marketing APIs.

What's New in Version 6.0.0?

Version 6.0.0 is a major release. Some features are not backward compatible. You will need to recompile your client code for Version 6.0.0.

EWS Version 6.0.0 will be released to the EWS sandbox one month before it is released to production.

You should first experiment with the new version on the EWS sandbox, make any required changes to your client application, and then test your implementation. Move your client application to production only when you are satisfied with the results.

New Features

Network Distribution with Targeting Profile APIs

EWS APIs will allow setting Network Distribution using targeting service. In this release, profile APIs (typed APIs) will be available. Please note that framework APIs to support Network Distribution is already available in EWS v5.2
APIs will provide you with the flexibility to discount lesser yield traffic and add premiums for the traffic with better ROIs.
The Network Distribution feature is currently available in AU market, which includes Australia and New Zealand. It is tentatively scheduled for availability in the U.S. market in early Q1 2010.
For more information about Network Distribution, see TargetingService.

Domain Blocking in Japan(JP) Market

Domain Blocking is now available in JP Market. Up to 250 domains can be blocked at the account level. See AccountService.

Reporting APIs

A new API getBooksClosedTime is introduced that will provide advertisers with the books closed time for a given report.
The APIs used to process report requests have changed. The file format is now specified when adding the report request. The API used to download the report (getReportDownloadUrl) returns more information about the given report ID, such as report status and file output format. See BasicReportService for more details.
All targeting reports will include columns for tracking conversions (by default).

VAT Number Registration

Advertisers and Resellers can now optionally provide a country a VAT (Value Added Tax) number of registration. If this is not provided, then the user’s country of residence is assumed to be the country assigned to the VAT number.

Changes to Services

Removed Services

UpgradeService

New Operations

BasicReportService

Modified Operations

AccountService

Advertisers can optionally provide a country aVAT number registration that is different from country of residence.

VaultService

Resellers can optionally provide a country a VAT number registration that is different from country of residence

Removed Operations

BasicReportService

Deprecated Operations

getKeywordsByAccountID

New Data Objects

Modified Data Objects

TargetingProfile - added a new Data Object (NetworkDistribution).
ParticipationStatus – added new status (AllTacticsOffAtCampaign, AllTacticsOffAtAdGroup, ActiveNewMinBidHeavyDiscount, Inactive).
BasicReportRequest – removed ‘includeConversions’ flag.
Account - Advertisers/Resellers can optionally provide a country a VAT number registration that is different from country of residence.

What's New in Version 5.2.0?

EWS Version 5.2.0 is a minor release. All new features are backward compatible. Adopt Version 5.2.0 to take advantage of the new features

New Features

The new features and changes in EWS Version 5.2.0 are summarized below:

Network Distribution

Network Distribution is a product enhancement, currently available for the Australia (AU) market. It is designed to give advertisers greater control over how they set their bids for different traffic sources.

Using Network Distribution, advertisers in the AU market may set up campaigns targeted to our Premium Network, our Standard Network, or both. See: TargetingService . If advertisers choose to set up a campaign at Entire Network (i.e. both Premium and Standard), they have the ability to fine-tune their bids by providing Discounts/Premiums on the Standard Network.
For example, If an advertiser has a bid of $100 for the Entire Network, the advertiser may choose to bid at 10% discount/premium for the Standard Network. For the Premium Network, the bid amount will remain intact at $100.
Advertisers in the AU market can get research data on how their ads will perform on each of the available networks. See: ForecastService and BidInformationService.
Network Distribution Reports are available in the AU market to show how the ads have performed on the various distribution channels. See BasicReportType.

Note: This feature will be available in Australia(AU) market, which is comprised of Australia and New Zealand.

EWS for Mobile Sponsored Search

In version 5.2.0, EWS APIs will include functionality specific to Mobile Sponsored Search. This functionality will include historical and real time forecasting, bid information, and performance reporting for Mobile Sponsored Search accounts.
With EWS 5.2.0, Mobile Sponsored Search EWS APIs are available for the US, UK, JP, and DE markets only.

A new dictionary service is provided so that you can determine the markets that support Mobile Sponsored Search advertising, as well as the supported mobile carriers for each of those markets. See MobileDictionaryService.
Advertisers can now create accounts to use for Mobile Sponsored Search advertising. See AccountService.
Resellers can enroll new customers for Mobile Sponsored Search advertising. See VaultService.
Research data for mobile advertising is available. For instance, an advertiser can forecast how an ad moght perform on the AT&T carrier in the US market. See: ForecastService and BidInformationService.
A limited set of reports is available for Mobile Sponsored Search. See Report Details

Note: Advertisers need to use the Mobile Sponsored Search User Interface to manage campaigns and ad groups for Mobile Sponsored Search advertising, as EWS APIs for managing Mobile Sponsored Search campaigns and ad groups are not supported.

Enhanced Targeting APIs

New APIs are available in TargetingService to facilitate deletion and updating of existing targets, using TargetingAttributeDescriptor objects.

Variable Minimum Bids

In the Australian market, EWS Version 5.2.0 will also include a new variable minimum bids feature (which was released in the US in EWS Version 4.0.0), and may significantly impact your bidding strategy. 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 $0.10. With the current system, if your bid is below the minimum allowable bid for a keyword, the system will not accept your bid. With the new system, your bid will be accepted but then you will be notified that the keyword is inactive.

EWS Version 5.2.0 is configured to work with variable minimum bids. If you do not upgrade to EWS Version 5.2.0, you may not be able to manage your account to its potential.

Ad Delivery Report

The new Ad Delivery Report provides the user visibility into sites and domains where your ads are being displayed and how they are performing. The Ad Delivery Report is available in most markets where domain blocking is also enabled. You may use information in this report to guide your decisions about blocking certain domains.

Conversions Metrics for Targeting Reports

Targeting reports (Geographic, Demographic, Day Parting) now include additional columns for conversion metrics. These will be included in your report only if you specify it in your report request. See BasicReportService.

Optional Account ID for Research Services

All research services (ForecastService, BidInformationService, KeywordResearchService) no longer require that the account ID should be sent in the request. However, if ad group ID is sent, then account ID is required.

Keyword Participation Status

KeywordService provides a new API, getKeywordParticipationStatusByAdGroupId that can be used to get rich information about the participation status of all the keywords within an AdGroup.

New Services

MobileDictionaryService

New Operations

AccountService

BidInformationService

KeywordService

getKeywordParticipationStatusByAdGroupId

MasterAccountService

isMobileMasterAccount

TargetingConverterService

TargetingDictionaryService

getNetworksByTacticType

TargetingService

VaultService

addNewMobileCustomer

Modified Operations

BasicReportService

Targeting reports (geographic, demographic, and day parting) now include additional columns for conversion metrics. These will be included in your report if you set the optional flag "includeConversion" to true in the request object.

ForecastService

Using the Network in the Targeting Attribute Descriptor of the request object will provide forecast for the specified Network (AU market)
Using the Carrier in the request object will provide forecast mobile advertising on the specified carrier.

TargetingService

Using 'Network' as the new TargetingType in TargetingAttributeDescriptor of the request object, target or delete Network Distribution(AU Market).

Deprecated Operations

KeywordService

Instead use getKeywordParticipationStatusByAdGroupId

New Data Objects

MobileDictionaryService

Carrier

BidInformationService

TargetingDictionaryService

Network

Modified Data Objects

BasicReportService

BasicReportRequest - includes the optional "includeConversion" flag
BasicReportType - new Report Types for Network Distribution (AU market only)

ForecastService

Using the Network in the Targeting Attribute Descriptor of the request object, will provide forecast for the specified Network (only AU market)
Using the Carrier in the request object will provide forecast mobile advertising on the specified carrier.

What's New in Version 5.1.0?

EWS Version 5.1.0 is a minor release. All new features are backward compatible. To take advantage of the new features in Version 5.1.0, recompile your client code for Version 5.1.0.

New Features

The new features and changes in EWS Version 5.1.0 are summarized below:

New Operations

The following operations have been added to services in EWS Version 5.1.0:

BulkService

New Data Objects

The following new data objects are included in EWS Version 5.1.0:

What's New in Version 5.0.0?

EWS Version 5.0.0 is a major release. Some features are not backward compatible. You will need to recompile your client code for Version 5.0.0.

EWS Version 5.0.0 will be released to the EWS sandbox one month before it is released to production. First experiment with the new version on the EWS sandbox, make any required changes to your client application, and then test your implementation. Move your client application to production only when you are satisfied with the results.

New Features

Enhanced Targeting
Demographic targeting functionality is available in EWS 5.0.0. Demographic targeting is a type of audience targeting that's based on population classifications like gender and age range.

Heterogenous geographical targeting is available in EWS 5.0.0 (for the US market only). This allows advertisers to target varied g eographical levels in one campaing/ad group.

Day parting is available in EWS 5.0.0. A day parting allows you to specify when you want your ads to display to prospective custome rs. You can also use a day-part to specify a bid premium for specific time periods.

Please note that geographical targeting is the only targeting dimension that is available in all the markets. Heterogenous geograph ical targeting and other targeting dimensions are available in the US market only.

AdGroup level targeting has been introduced in the US market only.

For more information, see TargetingService Overview. Click here for the list of targeting types that are allowed in each market.

Limiting Spend
The feature to update the spend limit is available in all markets. The additional feature to specify/update a tactic based cap on the spend is available in the US market only. For more information, see BudgetingService Overview.

Change in Credit Card
In the UK market, we have included support for credit card type MAESTRO and removed support for SWITCH. See market-specific values for United Kingdom for the supported list of credit cards.

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

Changes to Services

The changes to services in EWS Version 5.0.0 are summarized below.

New Services

New services and related operations introduced in EWS 5.0.0 include:

TargetingConverterService

TargetingDictionaryService

TargetingService

Renamed Services

Services renamed in EWS Version 5.0.0 include:

GeographicalTargetingService. This service has been renamed GeographicalDictionaryService. The API signatures have changed. The operations that were in the Beta command group are now part of the Marketing command group. See Command Groups for more information.

New Operations

New operations added to services in EWS Version 5.0.0 include:

AdGroupService

splitAdGroupBasedOnTactic

BasicReportService

Removed Operations

Operations removed from EWS Version 5.0.0 include:

CampaignService

deleteGeographicLocationFromCampaign
getGeographicLocationForCampaign
setGeographicLocationForCampaign
getTargetingForCampaign
setTargetingForCampaign

Modified Operations

Modified operations in EWS Version 5.0.0 include:

BudgetingService

updateAccountDailySpendLimit — used to take accountId and limit (double), but now takes accountId and SpendLimit object.
updateCampaignDailySpendLimit — used to take campaignId and limit (double), but now takes campaignId and SpendLimit object.
getAccountDailySpendLimit — used to return limit (double), but now returns SpendLimit object.
getCampaignDailySpendLimit — used to return limit (double), but now returns SpendLimit object.

VaultService

addNewCustomer — used to return MasterAccount object, but now returns AccountAggregate object. The ContentMatch, AdvancedMatch, SponsoredSearch fields are, by default, set to true. For MX, SG, and IN markets, by default, AdvancedMatch is set to false. For AT, CH, DE, DK, ES, FI, FR, IT, NL, NO, SE, and UK markets, by default, ContentMatch is set to false. To change these default values, use the updateAccount operation in AccountService.

ForecastService

getForecastForKeyword — ForecastRequestData has been changed to KeywordForecastRequestData.
getForecastForKeywordBatch — ForecastRequestData has been changed to KeywordForecastRequestData and the limit on the number of keywords has been reduced to 100 from 250
getForecastByAdGroup and getForecastForKeywords — ForecastRequestData has been changed to AdGroupForecastRequestData.
getHistoricalDataForKeywords — HistoricalRequestData has been modified to include targeting information.

Changes to Data Objects

The changes to data objects in EWS Version 5.0.0 are summarized below.

New Data Objects

New data objects introduced in EWS Version 5.0.0 include:

Changed Data Objects

Data objects modified in EWS Version 5.0.0 include:

GeographicalTargetingService

TargetingAttributeValue is now GeoLocation
TargetingAttributeType is now TargetingType
GeoTargetProbability is now GeoLocationProbability
GeoTargetProbabilitySet is now GeoLocationProbabilitySet

ForecastService

ForecastRequestData is now KeywordForecastRequestData and AdGroupForecastRequestData.
HistoricalKeyword and HistoricalRequestData allow only one matchType per request.
HistoricalRequestData has new elements to send targeting information.
HistoricalKeywordResponse has new elements to hold the response data.

Data object elements modified in EWS Version 5.0.0 include:

ForecastResponseData

clicks is now ForecastClickData data object
impressions is now ForecastImpressionData data object

HistoricalKeywordResponse

avgSearches represents the average searches for the month

TargetingAttributeDescriptor

ID (long) is now targetingAttributeID (string)
type is now targetingType

TargetingAttribute

targets is now targetingAttributeDescriptor

TargetingAttributeValue (now GeoLocation)

ID is now woeid
type is now placeType

New elements added to data objects in EWS Version 5.0.0 include:

TargetingAttribute

premium

BulkDownloadStatus

TimedOut

BulkDownloadStatusResponse

locale

CreditCardInfo

Changes to Reports

The changes to reports in EWS 5.0.0 are summarized below.

New Reports

The new reports available in EWS Version 5.0.0 include:

ClickFilterAccountSummary
ClickFilterAccountSummaryByDay
ClickFilterCampaignSummary
ClickFilterCampaignSummaryByDay
DayPartingAdGroupSummary
DayPartingAdGroupSummaryByDay
DayPartingCampaignSummary
DayPartingCampaignSummaryByDay
DemoAgeAdGroupSummary
DemoAgeAdGroupSummaryByDay
DemoAgeCampaignSummary
DemoAgeCampaignSummaryByDay
DemoGenderAdGroupSummary
DemoGenderAdGroupSummaryByDay
DemoGenderCampaignSummary
DemoGenderCampaignSummaryByDay
GeoLocationAdGroupSummary
GeoLocationAdGroupSummaryByDay

More Reports
In EWS Version 5.0.0, the maximum number of saved reports has been increased from 5 to 50 and the reports are available for up to 2 days only. Please note that this is a backward incompatible change.

Changes to Documentation

The changes to EWS 5.0.0 documentation are summarized below.

A wireframe like UI, similar to the YDN YSM page, including an expandible and collapsable listing of services, data, and other reference pages in the LHS navigation bar.
Enhanced navigation - context sensitive RHS navigation bar in service API pages with links to related data objects, links, feeds (from YSM blog and YSM Y! Group), etc.
Site Search enhancements include:
- Suggestions for data objects, services, capabilities, and command groups with links to corresponding pages.
- Search results that can be restricted to searchmarketing.yahoo.com and ysmblog.com (if the suggestions are ignored or are not available).
Sample code restructuring and enhancements include:
- Java and Perl sample code for selective APIs. For example, see the CampaignService addCampaign operation.
- Two sets of sample codes for Java - API specific samples and use cases. The Java sample code is available as a "Quick Start" SDK that contains all the sample code, WSDL stubs, dependency libs, and an Ant build file.
- Perl code is restructured into API specific samples and use cases.
- Source code download is available in these formats: .jar, .zip, tar.gz, tar.bz2.
- Sample code viewer for displaying formatted sample code files. For example, see sample code for DownloadBulkTemplate in the sample code viewer.
Note: All the samples are distributed under BSD license.

Support

If you face problems with the Search Marketing APIs on the EWS sandbox or on production, or, if you have questions about product behavior that are not answered by the EWS documentation, please contact your Technical Account Management team at ews-help@yahoo-inc.com or, send us a message through the online Support Form.