This topic provides information about changes to the Microsoft adCenter API.
For information about changes to this documentation, see What's New in the SDK for the Microsoft adCenter API.
Breaking Changes
General
New Request and Response Header Format
The Administration, Campaign Management, and Reporting Web services now use a different header format. The header elements are now all strings instead of specific data objects. The following is an example of the new header format.
<s:Header>
<h:ApplicationToken xmlns:h="https://adcenter.microsoft.com/v6">XXXXX</h:ApplicationToken>
<h:CustomerAccountId xmlns:h="https://adcenter.microsoft.com/v6">XXXXX</h:CustomerAccountId>
<h:CustomerId xmlns:h="https://adcenter.microsoft.com/v6"> XXXXX</h:CustomerId>
<h:DeveloperToken xmlns:h="https://adcenter.microsoft.com/v6">XXXXX</h:DeveloperToken>
<h:Password xmlns:h="https://adcenter.microsoft.com/v6">XXXXX</h:Password>
<h:UserName xmlns:h="https://adcenter.microsoft.com/v6">XXXXX</h:UserName>
</s:Header>
Of particular importance are the CustomerAccountId and CustomerId elements. In the past, only the CustomerAccountId element was present in the header. Now, the Campaign Management Web service requires that you pass your account identifier in the CustomerAccountId element and the appropriate customer identifier in the CustomerId element.
The response headers now contain only a TrackingId element, which is a string instead of an ApiCallTrackingData object.
For more information, see SOAP Requests and Responses.
New Error Types
The Administration, Campaign Management, and Reporting Web services now use different fault types. The AdApiFaultDetail object has been added to contain general API errors, such as authentication errors. Faults specific to an API are still contained in an ApiFaultDetail object.
Administration
Service Operations Renamed
The GetQuota service operation has been renamed to GetAssignedQuota.
The GetQuotaBalance service operation has been renamed to GetRemainingQuota.
The function and usage of these service operations is identical to those in version 5.1 of the API, except that neither of the new operations takes parameters.
Reporting
Service Operations Renamed
The QueueReport service operation has been renamed to SubmitGenerateReport.
The GetReportStatus service operation has been renamed to PollGenerateReport.
The function and usage of these service operations is identical to those in version 5.1 of the API.
ProductName Column
The ProductName column has been removed from all affected reports.
Campaign Management
Entity Identifiers
All entity identifiers in the Campaign Management Web service have been changed to long. For example, the ad group identifier is now a long instead of an int.
New Bid Data Object
All elements that specify a bid have been changed to a Bid data object rather than a double. This is necessary to support default ad group bids.
Keyword/Ad Association APIs Removed
All the keyword and ad association APIs, such as GetKeywordAdAssociationsByAdIds, have been removed from the API. You now use the EditorialStatus elements of the Ad and Keyword objects to determine the ad and keyword association status.
Elements Changed to Strings
The following elements have been changed from fixed value sets to strings:
New Metro Area Identifiers
The format and content of the metro area identifiers used to target a specific metropolitan area has changed. For example, in version 5, to target the Calgary, Alberta, Canada metro area, you would set the MetroAreaId element of the MetroAreaTargetBid object to "148315336687484928". In version 6, you set the MetroArea element of the MetroAreaTargetBid object to "Calgary, AB CA". For more information, see Country Codes.
New Administration Features
The Administration Web service has been rewritten by using Windows Communication Foundation (WCF).
New Campaign Management Features
Default Bids for Ad Groups
The BroadMatchBid, ExactMatchBid, PhraseMatchBid, and ContentMatchBid elements have been added to the AdGroup data object. These elements provide default bid amounts for the keywords that belong to the ad group. If the keyword specifies any bid amounts, the keyword bid amounts override the ad group bid amounts.
Targeting
New Location Targeting
In addition to country/region and metro area targeting, you can now target ads to cities, states/regions, geographical locations, or business locations. For more information, see Location Targeting.
User Segment Targeting
Members of the user segment targeting pilot program can target ads to their businesses' users. For more information, see User Segment Targeting.
Advertising Assets
The concept of advertising assets has been added to support adCenter businesses. For more information, see Advertising Creatives.
Negative Site URLs
The AdGroup and Campaign data objects now contain the NegativeSiteUrls element. Negative website URLs are URLs where your ads won't be displayed. For example, if you add "http://www.contoso.com" to the NegativeSiteUrls element of an AdGroup object, the ads that belong to that ad group are not displayed on that URL.
Keyword Quality API
Businesses
The concept of businesses has been added to adCenter. The following service operations have been added to support businesses:
Site Placement Bidding
Support for website placement bidding has been added to the adCenter API. For more information, see the SitePlacement data object.
Behavioral Bidding
Support for behavioral bidding has been added to the adCenter API. For more information, see the BehavioralBid data object.
New Reporting Features
New Report Types
The following report types are now available:
-
Behavioral Performance Report
-
Behavioral Target Report
-
Publisher Usage Performance Report
-
Site Performance Report
New Report Columns
The AccountId column is now available in the following report:
-
Behavioral Performance Report
The AdId column is now available in the following reports:
-
Ad Performance Report
-
Behavioral Performance Report
The AdGroupId column is now available in the following reports:
-
Ad Group Performance Report
-
Ad Performance Report
-
Behavioral Performance Report
-
Behavioral Target Report
The CampaignId column is now available in the following reports:
-
Ad Group Performance Report
-
Behavioral Performance Report
-
Behavioral Target Report
-
Campaign Performance Report