Microsoft adCenter API Release Notes

Microsoft adCenter API Release Note...

Switch on low bandwidth view

Collapse All

Language Filter

Microsoft Advertising APIs

Microsoft adCenter API Release Notes

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:

The TimeZone element of the Campaign object
The Currency element of the GetKeywordEstimatesByBidsRequest object
The CountryAndRegion element of the CountryTargetBid object
The LanguageAndRegion element of the AdGroup object

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

You can now apply ad targeting to campaigns as well as ad groups. For more information, see Targeting Campaigns and Ad Groups.

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 Assets.

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

The GetKeywordQualityScoresByIds service operation has been added to enable you to obtain keyword quality score information.

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