|
|
Enterprise Web Services: Release Notes
This release of Enterprise Web Services (EWS) Marketing API includes changes and additions to the services currently available.
About These Release Notes
These release notes summarize the new features in the following EWS versions
- 6.1.0
- 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.1.0?
EWS Version 6.1.0 is a minor release. All new features are backward compatible. Adopt Version 6.1.0 to take advantage of the new features.
New Features
The new features in EWS Version 6.1.0 are summarized below:
Network Distribution is now available for the North America market
Network Distribution enables you to set up campaigns or ad groups to specifically receive traffic from Yahoo! Search, Yahoo! Partners, or both. If you choose to set up a campaign or an ad group to receive traffic from the Entire Network (i.e., both Yahoo! Search and Yahoo! Partners), you will have the ability to fine tune your bids by applying discounts or premiums on the Yahoo! Partner traffic. With this release, Network Distribution is now available in US and AU markets. More information about Network Distribution can be found in our documentation here.
Import Campaigns
This new feature is designed to help you easily and efficiently convert your campaign data from Google AdWords into Yahoo! Search Marketing formats. The APIs for this feature can be found in the new ConverterService. Please refer to the New Services section below for further details.
Increase in the number of excluded keywords supported
The number of excluded keywords supported on account and ad group level have been increased from 250 to 500.
New Service
ConverterService
New Data Objects
ConverterService
- DownloadFile
- DuplicateCampaignOption
- FileFormat
- OutputFile
- Preferences
- ProcessStatus
- Response
- Status
- Summary
- Token
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
- addReportRequestForAccountID
- addReportRequestWithAccountAggregation
- getReportOutputUrl
- getReportOutputUrls
Deprecated Operations
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
MasterAccountService
TargetingConverterService
TargetingDictionaryService
TargetingService
- deleteTargetingByTargetingAttributeDescriptorsForAdGroup
- deleteTargetingByTargetingAttributeDescriptorsForCampaign
- updatePremiumByTargetingAttributesForAdGroup
- updatePremiumByTargetingAttributesForCampaign
- updatePremiumByTargetingProfileForAdGroup
- updatePremiumByTargetingProfileForCampaign
VaultService
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
- getForecastByAdGroup
- getForecastForKeyword
- getForecastForKeywordBatch
- getForecastForKeywords
- getHistoricalDataForKeywords
- 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
- addTargetingAttributesForAdGroup
- addTargetingAttributesForCampaign
- deleteTargetingAttributesForAdGroup
- deleteTargetingAttributesForCampaign
- deleteTargetingByTypesForAdGroup
- deleteTargetingByTypesForCampaign
- getTargetingAttributesForAdGroup
- getTargetingAttributesForCampaign
Using 'Network' as the new TargetingType in TargetingAttributeDescriptor of the request object, target or delete Network Distribution(AU Market).
Deprecated Operations
KeywordService
Instead use getKeywordParticipationStatusByAdGroupIdNew Data Objects
MobileDictionaryService
BidInformationService
TargetingDictionaryService
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
- getAgeRangeByTargetingAttributeDescriptor
- getDayPartingTargetingByTargetingAttributeDescriptor
- getGenderByTargetingAttributeDescriptor
- getGeoLocationByTargetingAttributeDescriptor
- getTargetingAttributeDescriptorByAgeRange
- getTargetingAttributeDescriptorByDayPartingTargeting
- getTargetingAttributeDescriptorByGender
- getTargetingAttributeDescriptorByGeoLocation
- getTargetingAttributeDescriptorByUnderAgeFilter
- getUnderAgeFilterByTargetingAttributeDescriptor
TargetingDictionaryService
- getAdGroupSupportedTargetingTypesByTacticType
- getAgeRanges
- getCampaignSupportedTargetingTypesByTacticType
TargetingService
- addTargetingAttributesForAdGroup
- addTargetingAttributesForCampaign
- deleteTargetingAttributesForAdGroup
- deleteTargetingAttributesForCampaign
- deleteTargetingByTypesForAdGroup
- deleteTargetingByTypesForCampaign
- deleteTargetingForAdGroup
- deleteTargetingForCampaign
- getTargetableLevelForCampaign
- getTargetingAttributesForAdGroup
- getTargetingAttributesForCampaign
- getTargetingProfileForAdGroup
- getTargetingProfileForCampaign
- setTargetableLevelAsAdGroup
- setTargetableLevelAsCampaign
- updateTargetingProfileForAdGroup
- updateTargetingProfileForCampaign
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
BasicReportService
- setOptInReportingForAdGroups
- setOptInReportingForCampaigns
- getOptInReportingForAdGroups
- getOptInReportingForCampaigns
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:
- AccountAggregate
- AdGroupForecastMatchType
- AdGroupForecastRequestData
- AgeRange
- AgeTarget
- DayOfTheWeek
- DayPart
- DayPartingTarget
- DayPartingTargeting
- DemographicTargeting
- ForecastClickData
- ForecastCreative
- ForecastImpressionData
- Gender
- GenderTarget
- GeoLocation
- GeoLocationProbability
- GeoLocationProbabilitySet
- GeoTarget
- KeywordForecastMatchType
- KeywordForecastRequestData
- OptInAdGroupResponse
- OptInCampaignResponse
- OptInReporting
- OptInStatus
- SpendCapTactic
- SpendCapType
- SpendLimit
- TacticSpendCap
- TacticType
- TargetableLevel
- TargetingPremium
- TargetingPremiumType
- TargetingProfile
- UnderAgeFilter
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)
New elements added to data objects in EWS Version 5.0.0 include:
TargetingAttribute
BulkDownloadStatus
BulkDownloadStatusResponse
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.
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.