Microsoft adCenter API Version 5 Release Notes

Windows Live

Microsoft adCenter API Version 5 Release Notes

Microsoft adCenter API version 5 (V5) contains the following new features:

Reporting improvements, including the ability to generate reports that contain data for multiple accounts, campaigns, and/or ad groups.
Industry terms used in the adCenter API object model. For example, when referencing a set of ads, V5 uses the AdGroup class; V4 used the AdCenterOrder class.
Retrieval of campaign objects, such as campaigns, ads, ad groups, and keywords, by object ID.
Ability to update campaigns, ads, ad groups, and keywords without requiring values for the properties that are not being changed. For example, you can specify new bid amounts for a keyword, but leave the Param1, Param2, Param3, Status, Text, and NegativeKeywords properties set to null when calling the UpdateKeywords method. Only the bid amounts will be changed. The keyword properties that are set to null will remain unchanged.
Improved error handling.
Negative keywords are supported at the ad group level.
Conversion tracking is supported at the campaign level.

Microsoft adCenter API V5 is a major update to the adCenter API. When planning your migration to V5, approach the project as new application development rather than minor maintenance to an existing application.

The following sections provide details about adCenter API V5:

New versions of the WSDL documents.
Breaking changes between the V4 and V5 Web services.
CampaignManagement now supports retrieving objects by identifier.
Properties can be null if they are not being updated.
Target objects are associated with ad groups by the AddTarget method.
Negative keywords are supported at the ad group level.
Conversion tracking is supported at the campaign level.
Reporting API changes.
Error reporting.

New Version of WSDL Documents

The following are the V5 production Web Services Description Language (WSDL) documents:

Administration – https://adcenterapi.microsoft.com/Api/Advertiser/v5/Administration/Administration.asmx?wsdl
CampaignManagement – https://adcenterapi.microsoft.com/Api/Advertiser/V5/CampaignManagement/CampaignManagementService.svc?wsdl
CustomerManagement – https://adcenterapi.microsoft.com/Api/Advertiser/v5/CustomerManagement/CustomerManagement.asmx?wsdl
NotificationManagement – https://adcenterapi.microsoft.com/Api/Advertiser/v5/NotificationManagement/NotificationManagement.asmx?wsdl
Reporting – https://adcenterapi.microsoft.com/Api/Advertiser/V5/Reporting/ReportingService.svc?wsdl

The following are the V5 sandbox WSDL documents:

Administration – https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v5/Administration/Administration.asmx?wsdl
CampaignManagement – https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/V5/CampaignManagement/CampaignManagementService.svc?wsdl
CustomerManagement – https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v5/CustomerManagement/CustomerManagement.asmx?wsdl
NotificationManagement – https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v5/NotificationManagement/NotificationManagement.asmx?wsdl
Reporting – https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/V5/Reporting/ReportingService.svc?wsdl

Breaking Changes Between the V4 and V5 Web Services

Microsoft adCenter API V5 is a major release of the adCenter API. When planning your migration to V5, plan the project like you would for new application development rather than minor maintenance to an existing application. Although there are some classes and methods that use the same name in V4 and V5, the underlying class properties, method parameters, and method return values may differ.

Take the following issues into consideration when you migrate to the V5 WSDLs.

Breaking Changes Common to the V5 CampaignManagement and Reporting Web Services

The following changes apply to the V5 CampaignManagement and Reporting Web services:

APIFlags parameter is not used in V5
The first parameter of all adCenter API V4 Web service methods was APIFlags, which was required to be set to zero. This parameter does not exist in the V5 CampaignManagement and Reporting Web service methods.

Changes to ApiUserAuthHeader
The ApiUserAuthHeader class is not used in V5 by the CampaignManagement and Reporting Web services. The following table shows which V5 CampaignManagement and Reporting properties replace the V4 ApiUserAuthHeader properties.

V4 Property for CampaignManagement and Reporting Web Services	V5 Property or Class for CampaignManagement and Reporting Web Services
`ApiUserAuthHeader.Password`	`UserCredentials.Password` property
`ApiUserAuthHeader.UserAccessKey`	`DeveloperToken` class
`ApiUserAuthHeader.UserName`	`UserCredentials.Username` property

Additionally, the ApplicationToken class, has been added to V5. This value is reserved for future use. You can leave the ApplicationToken property unassigned when making calls to the CampaignManagement and Reporting Web services.
The ApiUserAuthHeader class functions the same in V4 and V5 for the Administration, CustomerManagement and NotificationManagement Web services.

SOAP header changes
In addition to the ApiUserAuthHeader changes, each SOAP header request (ApiRequestHeader) will contain an AccountId property. This property is not used by most customers. However, it is being implemented to support customer aggregators. If you are not a customer aggregator, set this property to null. If you are a customer aggregator, set this property to the customer's account ID.
Each SOAP header response (ApiResponseHeader) for successful Web service method calls will contain a TrackingId property. The TrackingId property helps the Microsoft adCenter API Support Team diagnose issues. If a Web service method call fails, the tracking ID is returned in the ApiFaultDetail.TrackingId property.

Breaking Changes in the CampaignManagement Web Service

The V5 CampaignManagement classes and methods use straightforward names that are aligned with the industry and are easier to understand than some of the names used in V4. For example, V4 used the term order, which was encapsulated in the AdCenterOrder class. In V5, the corresponding term is ad group, which is encapsulated in the AdGroup class. Another terminology change from V4 is the term order item (encapsulated in the AdCenterOrderItem class), which in V5 is keyword (encapsulated in the Keyword class).

The following table shows the V4 CampaignManagement classes and the V5 classes that replace them.

V4 CampaignManagement Class	V5 CampaignManagement Class
`AdCenterAdvertisement`	`TextAd` V5 also introduces the abstract class named `Ad`, which is the base for `TextAd`.
`AdCenterCampaign`	`Campaign`
`AdCenterCampaignPauseResume`	Not in V5. In V5, use the `CampaignManagement.PauseCampaigns` method to pause campaigns. Use the `CampaignManagement.ResumeCampaigns` method to resume campaigns.
`AdCenterKeywordAdAssociation`	`KeywordAdAssociation`
`AdCenterKeywordPrice`	`KeywordBid`
`AdCenterOrder`	`AdGroup`
`AdCenterOrderItem`	`Keyword`
`AdCenterOrderItemBid`	Not in V5. When updating only the bid amounts for keywords in V5, call the `UpdateKeywords` method. Specify null values for the `Keyword` properties that are not related to bid amounts.
`AdCenterOrderItemPauseResume`	Not in V5. In V5, use the `CampaignManagement.PauseKeywords` method to pause keywords. Use the `CampaignManagement.ResumeKeywords` method to resume keywords.
`AdCenterOrderPauseResume`	Not in V5. In V5, use the `CampaignManagement.PauseAdGroups` method to pause ad groups. Use the `CampaignManagement.ResumeAdGroups` method to resume ad groups.
`AdCenterPositionEstimateResult`	`KeywordEstimate`
`AdCenterPositionEstimateType`	`MatchTypeEstimate`
`AgeTarget`	`AgeTarget`
`CountryTarget`	`CountryTarget`
`DayTarget`	`DayTarget`
`GenderTarget`	`GenderTarget`
`HourTarget`	`HourTarget`
`LocationTarget`	`LocationTarget`
`MetroAreaTarget`	`MetroAreaTarget`
`Target`	`Target`
`TargetDetailsForACountry`	`CountryTargetBid`
`TargetDetailsForADay`	`DayTargetBid`
`TargetDetailsForAGender`	`GenderTargetBid`
`TargetDetailsForAHourRange`	`HourTargetBid`
`TargetDetailsForAMetroArea`	`MetroAreaTargetBid`
`TargetDetailsForAnAgeGroup`	`AgeTargetBid`

The following table shows the V4 CampaignManagement methods and the V5 methods that replace them.

V4 CampaignManagement Method	V5 CampaignManagement Method
`AddAds`	`AddAds`
`AddCampaigns`	`AddCampaigns`
`AddOrderItems`	`AddKeywords`
`AddOrders`	`AddAdGroups`
`DeleteAds`	`DeleteAds`
`DeleteCampaigns`	`DeleteCampaigns`
`DeleteOrderItems`	`DeleteKeywords`
`DeleteOrders`	`DeleteAdGroups`
`GetAds`	`GetAdsByAdGroupId` Additionally, you can now retrieve ads by ID by using the `GetAdsByIds` method that was introduced in V5.
`GetCampaigns`	`GetCampaignsByAccountId` Additionally, you can now retrieve campaigns by ID by using the `GetCampaignsByIds` method that was introduced in V5.
`GetKeywordAdAssociationByAd`	`GetKeywordAdAssociationsByAdIds`
`GetKeywordAdAssociationByOrderItem`	`GetKeywordAdAssociationsByKeywordIds`
`GetKeywordAdAssociationByStatus`	`GetKeywordAdAssociationsByStatus`
`GetKeywordPositionEstimate`	`GetKeywordEstimatesByBids`
`GetLocationTargetInformation`	Not in V5. When targeting an ad group toward countries/regions, set the CountryTargetBid.Country property to one of the values from the CountryType enumeration list. When targeting an ad group toward metropolitan areas, set the MetroAreaTargetBid.MetroAreaID property to one of the metropolitan area IDs that are documented in Microsoft adCenter API Country/Region IDs.
`GetOrderItems`	`GetKeywordsByAdGroupId` Additionally, you can now retrieve keywords by ID by using the `GetKeywordsByIds` method introduced in V5.
`GetOrders`	`GetAdGroupsByCampaignId` Additionally, you can now retrieve ad groups by ID by using the `GetAdGroupsByIds` method introduced in V5.
`PauseResumeCampaigns`	Use `PauseCampaigns` when pausing a campaign. Use `ResumeCampaigns` when resuming a campaign.
`PauseResumeOrder`	Use `PauseAdGroups` when pausing an ad group. Use `ResumeAdGroups` when resuming an ad group.
`PauseResumeOrderItems`	Use `PauseKeywords` when pausing a keyword. Use `ResumeKeywords` when resuming a keyword.
`SubmitOrderForApproval`	`SubmitAdGroupForApproval`
`UpdateAds`	`UpdateAds`
`UpdateCampaigns`	`UpdateCampaigns`
`UpdateOrderItemBids`	Not in V5. When updating only the bid amounts for keywords, call the `UpdateKeywords` method. Specify null values for the `Keyword` properties that you do not want to change. For example, specify the new bid amounts, and set null for the other `Keyword` properties.
`UpdateOrderItems`	`UpdateKeywords`
`UpdateOrders`	`UpdateAdGroups`

Note:
Even in cases where a class or Web service method has the same name in both V4 and V5, the names and data types of the class properties, method parameters, and method return values may be different. Take this into account when you migrate your V4 applications to V5.

Breaking Changes in the Reporting Web Service

The following table shows the V4 Reporting methods and the V5 methods that replace them.

V4 Reporting Method	V5 Reporting Method
`GetAPIReportStatus`	`GetReportStatus`
`RequestBIReport`	`QueueReport`

The following table shows the V4 report request classes that have been renamed in V5.

V4 Reporting Class Name	V5 Reporting Class Name
`AdParameterReportRequest`	`AdDynamicTextPerformanceReportRequest`
`OrderPerformanceReportRequest`	`AdGroupPerformanceReportRequest`

Note:
Even in cases where a class or Web service method has the same name in both V4 and V5, the names and data types of the class properties, method parameters, and method return values might all be different. Take this into account when you migrate your V4 applications to V5.

The report column labels and schema for XML reports have changed significantly from V4. For more information about the report column headers and schema, see the topics under Reports.

For a list of other significant Reporting Web service changes in V5, see the following Reporting API changes section.

Breaking Changes in the Administration, CustomerManagement, and NotificationManagement Web Services

Other than using V5 in the URLs for the WSDLs, no changes were made to the Administration, CustomerManagement, and NotificationManagement Web services.

CampaignManagement now Supports Retrieving Objects by ID

The CampaignManagement Web service in V5 provides the ability to retrieve entities by ID. This is a performance improvement in the API as compared with the methods used in V4, which returned an array of objects for all entities requested but did not allow you to retrieve an object based on its ID. The following methods, which have no corresponding equivalent in V4, are introduced in V5 to allow you to retrieve CampaignManagement objects by ID:

GetAdGroupsByIds
GetAdsByIds
GetCampaignsByIds
GetKeywordsByIds

Properties can be Null if They are Not Being Updated

When updating existing objects, set new values for the properties that you want to change, and specify null values for the properties that you do not want to change. This is a performance and efficiency improvement over the V4 functionality, which required you to specify values for the properties even when they were not changing.

For example, if you want to change only the bid amount for a keyword, use the following technique.

Keyword kw;
// Specify the ID of the keyword that you want to change.
kw.Id = 123;

// Specify the new bid amounts.
// If you do not want to change all the bid amounts,
// set the bid amounts to null for the bids that 
// are not being changed.
kw.ExactMatchBid = 1.50;
kw.PhraseMatchBid = 1.50;
kw.BroadMatchBid = 1.50;
kw.ContentMatchBid = 1.50;

// Set to null the properties that you are not changing.
kw.Status = null;
kw.Param1 = null;
kw.Param2 = null;
kw.Param3 = null;
kw.Text = null;
kw.NegativeKeywords = null;

// The kw variable has now been initialized to use the new values
// when the keyword is updated. Pass the kw variable as an array element
// in the second parameter when you call the UpdateKeywords method.

The technique of using null for properties that you do not want to change applies to the following methods and classes:

UpdateAds method and classes derived from the Ad class
UpdateAdGroups method and the AdGroup class
UpdateCampaigns method and the Campaign class
UpdateKeywords method and the Keyword class

Note that for string types, null is not the same as an empty string. Ensure that you are passing in null and not "" (an empty string) when you want to indicate that a string value is not being changed as part of the update. If you pass in an empty string, the existing string value will be modified to the empty string; in effect, the existing string text will be deleted.

Note:
In the .NET Framework version 1.1, you must set a property's `Specified` value to false when you want to indicate null for a property. Each nullable primitive type in the .NET Framework 1.1 contains a Boolean property in the form PropertyName`Specified`. For example, if the `Keyword.Param3` property is the property that you want to set to null to indicate that its value is not changing, set `Param3Specified` to false, as shown in the following example. `kw.Param3Specified = false;` This issue does not apply to the.NET Framework 2.x and the .NET Framework 3.x; you do not need to set a property's `Specified` value to false when you want to indicate null in the .NET Framework 2.x or the .NET Framework 3.x.

Note:

In the .NET Framework version 1.1, you must set a property's Specified value to false when you want to indicate null for a property. Each nullable primitive type in the .NET Framework 1.1 contains a Boolean property in the form PropertyNameSpecified. For example, if the Keyword.Param3 property is the property that you want to set to null to indicate that its value is not changing, set Param3Specified to false, as shown in the following example.
kw.Param3Specified = false;
This issue does not apply to the.NET Framework 2.x and the .NET Framework 3.x; you do not need to set a property's Specified value to false when you want to indicate null in the .NET Framework 2.x or the .NET Framework 3.x.

Target Objects are Associated to Ad Groups by the AddTarget Method

In V4, a target object was a property of an ad group object. For example, the association of a target with an ad group was made through the AdCenterOrder.orderTarget property. In V5, a target object is associated with an ad group through a call to the CampaignManagement.AddTarget method.

V5 introduces the following methods that are related to target objects. Each method uses a parameter, AdGroupId, that specifies the ad group associated with the target:

AddTarget
DeleteTarget
GetTargetByAdGroupId
UpdateTarget

Negative Keywords Supported at the Ad Group Level

In V4, negative keywords were supported at the campaign level through the AdCenterCampaign.NotKeywords property and at the keyword level AdCenterOrderItem.NotKeywords property. In V5, negative keywords remain supported at the campaign level and keyword level. Negative keywords are also supported at the ad group level.

The following table shows the properties and the levels that are supported for negative keywords in V5.

Property	Description
`Campaign.NegativeKeywords`	Supports negative keywords at the campaign level.
`AdGroup.NegativeKeywords`	Supports negative keywords at the ad group level.
`Keyword.NegativeKeywords`	Supports negative keywords at the keyword level.

Conversion Tracking Supported at the Campaign Level

Conversion tracking is supported at the campaign level in V5. The Campaign.ConversionTrackingEnabled property indicates whether conversion tracking is enabled for a campaign. The Campaign.ConversionTrackingScript property contains the script that is used to track the conversions for the campaign if the ConversionTrackingEnabled property is set to true.

Reporting API Changes

In adCenter API V5, the entire reporting API has been redesigned. The following are the key elements of the new API.

New Reporting Methods

In V5, a report is requested by using the ReportingServiceClient.QueueReport service operation. Because reports can take a long time to generate, QueueReport is an asynchronous call. You obtain the status of a report request by using the ReportingServiceClient.GetReportStatus service operation. For more information about how to use these methods, see How to Request and Download a Report.

New and Renamed Report Types

Version 5 adds the destination URL performance report. This report is requested by using the DestinationUrlPerformanceReportRequest class.

The ad parameter report is now known as the ad dynamic text performance report. The AdDynamicTextPerformanceReportRequest class is used to request this report.

The order performance report is now known as the ad group performance report. The AdGroupPerformanceReportRequest class is used to request this report.

Report Columns and Measures

You must now specify all the report data columns that you want in a report. All the columns and measures are specified by using the same property. Each of the report request classes has a Columns property that is an array of enumeration values that specifies the requested data. Even though these columns appear to be optional, the array requires some of the columns. Each Columns property will identify which columns are required. For example, in the keyword performance report request, the KeywordPerformanceReportRequest.Columns property must contain the following columns:

KeywordPerformanceReportColumn.AccountName
KeywordPerformanceReportColumn.CampaignName
KeywordPerformanceReportColumn.Keyword
KeywordPerformanceReportColumn.TimePeriod

This property must also contain at least one of the following values:

KeywordPerformanceReportColumn.AverageCpc
KeywordPerformanceReportColumn.AveragePosition
KeywordPerformanceReportColumn.Clicks
KeywordPerformanceReportColumn.Ctr
KeywordPerformanceReportColumn.Impressions
KeywordPerformanceReportColumn.Spend

The order that the columns are contained in the array determines the order that the columns will appear in the report.

Report Aggregation

Report aggregation works the same way that it does in V4. Each report request class has an Aggregation property that is set to an enumeration value. It specifies the time period to aggregate for the report. There are two types of report aggregation values—ReportAggregation and NonHourlyReportAggregation, depending on whether hourly aggregation is supported for the report type.

Report Filters

You can use filters to target a report to a reduced set of items. The items can be filtered according to the report type. Each report request type has an associated report request filter class that is contained in the request's Filter property. Only the items that fit all the filter criteria are included in the report.

For example, the KeywordPerformanceReportRequest.Filter property contains a KeywordPerformanceReportFilter object that specifies the filters for the report. You can filter a keyword performance report to a specific set of keywords by adding the keywords you want to include in the report to the KeywordPerformanceReportFilter.Keywords array. Similarly, you can limit the report results to those keywords that are displayed in a particular language and country/region by setting the KeywordPerformanceReportFilter.LanguageAndRegion property to the desired language and country/region. If both properties are set, only those keywords in the array that are displayed in the specified language and country/region will be included in the report.

Report Scope

You can now specify the scope of a report to a set of accounts, campaigns, and/or ad groups. The scope can be as narrow or as broad as you need it to be. You can even generate reports that contain data for multiple accounts, campaigns, and/or ad groups.

Each report request type has a Scope property that contains a report scope class object that defines the scope of the report. The following table lists the available scope classes.

Scope Class	Description
AccountReportScope	Used for reports that can be applied only to accounts. The account performance report is an example of this type of report.
AccountThroughCampaignReportScope	Used for reports that can be applied only to accounts and/or campaigns. The campaign performance report is an example of this type of report.
AccountThroughAdGroupReportScope	Used for reports that can be applied only to accounts, campaigns, and/or ad groups. The keyword performance report is an example of this type of report.

Report Time

The time frame of the report is specified in the Time property of the report request. All the report request types use the ReportTime class for this property except for the BudgetSummaryReportRequest.Time property, which uses the BudgetSummaryReportTime class. Both of the report time classes have the PredefinedTime, CustomDates, CustomDateRangeStart, and CustomDateRangeEnd properties. The CustomDateRangeStart and CustomDateRangeEnd properties are treated as a set to specify the range of dates and times that the report covers. Each of these properties or property sets is mutually exclusive; that is, if one property is specified, all the others must be null. For example, if the ReportTime.PredefinedTime property is not null, all the other properties must be null. If a range of dates is being specified, both the CustomDateRangeStart and CustomDateRangeEnd properties must not be null, and the PredefinedTime and CustomDates properties must be null. An error will occur if these conditions are not met.

Report Column Labels

The report column labels are now the same, no matter which type of report, XML, CSV, or TSV is requested.

Error Reporting

In the adCenter API version 5, the entire error object model has been redesigned.

The Microsoft adCenter API version 5 throws a FaultException exception for all errors, including transaction-level errors. The adCenter API does not support partial success for service operations that affect multiple entities. If one element in a batch causes an error, the entire batch fails.

The adCenter API defines the ApiFaultDetail class, which contains error information. The ApiFaultDetail object is obtained as shown in the following code example.

Any service operation that causes an ad or keyword to go through editorial validation will throw an exception that contains an instance of the EditorialApiFaultDetail class if an error occurs. The EditorialApiFaultDetail class is derived from the ApiFaultDetail class. In addition to the properties of the base class, the EditorialApiFaultDetail class contains the EditorialErrors property. This property is an array of EditorialError objects that contains information about the specific editorial validation failures. The following service operations can throw an exception that contains the EditorialApiFaultDetail class:

The following table shows the classes that are used in the error object model in V5.

Class	Description
ApiFaultDetail	Contains exception information for an error that occurs in an adCenter service operation.
BatchError	Contains information for a specific batch item that caused an error in an adCenter service operation. Batch errors are returned in the ApiFaultDetail.BatchErrors property.
EditorialApiFaultDetail	Contains information for one or more ads that did not pass editorial validation.
EditorialError	Contains information for an ad that failed editorial validation.
OperationError	Contains information for an error that has occurred in an adCenter service operation. Operation errors are returned in the ApiFaultDetail.OperationErrors property.

The V4 error codes are not included in V5. For a list of error codes that are in V5, see Microsoft adCenter API Error Codes (V5.1).

For more information about the new error reporting, see Microsoft adCenter API Error Handling.

Concepts

Microsoft adCenter API Programming Reference (V5.1)
Microsoft adCenter API Version 5.1 Examples
Microsoft adCenter API Release Notes
Microsoft adCenter API Versioning

Manage Your Profile | Legal | Contact Us | MSDN Flash Newsletter

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads