adCenter API Blog for Developers

Reminder: Upgrade to Adintelligence v.8 Before the End of May

Tina Kelleher - MSFT — Wed, 16 May 2012 18:10:06 GMT

If you didn't see last month's post on enhancements to AdIntellignece for API users, there was some info in there about an action you'll need to take before this month is out. As we've hit the half-way mark in May, now is probably a good time to post this quick reminder:

KSP 5.5 and 6.0 API Deprecation

Please note that KSP 5.5 and 6.0 are being deprecated and API users need to move to AdIntelligence v8.
As an adCenter API user, to continue to take advantage of Ad Intelligence make sure you code to API V8 as applications coded to earlier KSP API versions will not function after May 30^th
How to Move to V8

Feel free to leave a comment with any questions!

Interested in Accessing the adCenter API? Here’s How to Get Started

Janet Micka - MSFT — Mon, 14 May 2012 20:14:00 GMT

Before you can begin to use the adCenter API, you will need a developer token and a user account that has the API user role.

The following flow chart walks you through the the basic steps needed to get an account and the credentials you will need to access the adCenter API.

1. Set up account.

2. Request credentials.

For more detailed information about the onboarding process , see Getting Started with the adCenter API.

If you have any questions or comments, please visit the adCenter Forum.

Mandatory Code Changes Required by adCenter API Users in Preparation for URL by Match Type Updates

Pruitt - MSFT — Thu, 03 May 2012 18:43:00 GMT

We’re fast approaching our next milestone in releasing URL by Match Type. In March, we announced the ramped release of URL by Match Type and have been steadily enabling advertisers ever since. Our focus has now turned to our API customers.

With adCenter’s URL by Match Type feature, you will have more control and precision for managing each bidded keyword match type within the same ad group by assigning a unique destination URL. This will enable you to manage each URL and match type more independently to optimize and improve your campaign performance while making cross platform changes with more accuracy and ease. This feature also improves your ability to measure and track keyword performance by match type to more effectively optimize your campaigns.

Timing and Impact

We will be rolling this feature out over many months, and the first wave of customers to be enabled for URL by Match Type will be advertisers with a customer-level market country setting of US, DE, AT, CH.

adCenter API users who have their customer level Market setting set to the U.S., must prepare their account by making updates to their adCenter API code by July 1 to ensure the continued ability to manage campaigns with adCenter API. adCenter API users (or Agencies/SEMs who manage advertisers) who have a customer level market setting of the Germany, Switzerland, and Austria, must update their adCenter API code by June 1.

Timeframe of enablement of customers belonging to other markets (UK, France, India, Canada and Singapore) is forthcoming and we will keep you informed as we update our release plan. (To determine your customer level Market setting, API users can pull this information from the v7 Customer data object or the v8 Customer data object.)

Details on code changes are provided below, but you can also refer to our MSDN documentationwhich contains this same information.

Mandatory adCenter API Code changes required

There are a few code updates API customers will need to make in order to leverage the functionality of URL by Match Type and ensure continued management of their adCenter accounts with adCenter API:

Current Rules	New Rules
The Keyword (KW) data object can have up to four different bids against (ExactMatchBid, PhraseMatchBid, BroadMatchBid, ContentMatchBid). Any match bid value on the KW object that is unused defaults (and is persisted in adCenter) as null. Note: Although content match is shown as an option, there is no contextual network within EMEA.	Keyword Object will only accept a bid for one of the four match types.
adCenter only allows a single instance of a keyword literal within the same ad group (e.g., you are unable to have two keyword objects that represent the bidded keyword “car”).	Business rule relaxed to allow multiple instances of the keyword in an ad group so long as there is no conflict/existing match type bid on the same keyword in the same ad group.
· Keyword Object and non-zero values: · Missing Bid: implies inheritance of bid from the ad group · Setting a bid explicitly to null: implies inheritance of bid from the ad group · Setting Bid to zero: Equivalent of deleting the match type for the Keyword	· Keyword Object and non-zero values: · As each Keyword Object instance can only have one match type bid, the remaining match type bids will need to be empty (different from null); Note that empty values will not default bids from the ad group. · Setting a bid explicitly to null: inherit the ad group bid for that match type (No change to this behavior) · Setting a bid to zero: not allowed (to delete a match type; advertisers need to call DeleteKeywords)
Content bids use the URL in the keyword object.	Keyword IDs can be created individually for content.

For Existing Keywords:

All existing Keywords will be converted so that the new “After Enablement” rules for the keyword object are not violated. See image below:

adCenter will determine what new Keyword Match Types to generate based on the number of clicks per match type over the last 30 days. The best performing match type will remain unchanged, and the remaining bidded match types will be moved to new KW instances that will have the same KW string, editorial status, URL and bid. There are some additional caveats API customers should be aware of:

If a KW has fewer than 1000 impressions, the KW ID retained will be based on the most restrictive MT. (Exact is the most restrictive with Broad being the least restrictive.)
If two MTs are tied for performance, the most restrictive MT remains unchanged and remaining MTs will be represented as new KWs moving forward.
Hybrid ad groups (ad groups that surface ads in Search & Content Networks): New KW ids will be created to represent content bids, regardless if the content MT bid is being inherited from the ad group.
Content-Only ad groups, exact, phrase, broad match types will get new IDs; existing IDs will always be retained with the content match type.
Ad groups will retain the 10,000 keyword object limit. If the limit is exceeded during migration, the migration itself will not fail, however no new KWs can be added until the KW count is under 10K.

New KWs will retain the editorial status of the original KW, but quality scores will be re-calculated.
To determine the migration status of an account, adCenter is exposing a new service operation called GetAccountMigrationStatuses.

Content Match Types When surfacing ads through the content network, adCenter will match against the Keyword ID that has a Content match type. In the event that a Content match type has not been created (the word “Car” is created for Exact , Phrase and Broad, but not Content), that KW continue to serve in the Content Network, however attribution will be associated with the least restrictive match type (in the order of broad, phrase, exact). It’s important to note that the contextual network is not available within EMEA, so the above information applies to the North American marketplace.

For reporting, all impression and performance data will be reported under “Content” for both delivered and bidded match types.

Reporting After Migration

If you are reporting on match type performance and reporting over a period that spans pre and post enablement, there could be two different keywords IDs with historic performance data that need to be referenced. For example, in the figure below, the March 1 rows represent performance data prior to the migration, and March 2 rows represent data reported after migration. In this example, reporting on the performance of exact match over the two day period would require referencing two different Keyword IDs. Note that if you do not report using the keyword ID column, the match type performance would be aggregated as-expected.

To assist you, adCenter is also releasing two different reporting capabilities:

· KeywordMigration Report (in Reporting v8 only). This report will surface a new report that will show the keyword conversion “mapping” to reflect keywords and their “originating” KW, if any.

· A New column called KeywordMatchTypeID (in the Keyword Performance Report). When selected as a column, the KW performance report will show post-migration keyword IDs (where new KWs were generated) and present a “unified” view of performance data. Using this column, the previous example would look as such:

Suggested Best Practices

· Pre-Enablement

o Clean up ad groups at risk of exceeding the 10,000 keyword limitafter feature enablement. Once this feature is introduced, each match type will count as a separate keyword. All keywords will be retained, but you will not be able to add new keywords to the ad group if the limit is exceeded.

o For any match types you do not wish to have normalized into a new keyword, explicitly save a bid of 0.00 priorto migration; match type bids with null values will be normalized.Eliminate any five-cent bids designed to concede traffic.

- In API version 7 and 8, code for the new service operation GetAccountMigrationStatusesto track account migration status. (Guideline: 15k calls every 4 hours)

· Post-Enablement

o Synchronize campaigns for newly generated KW instancesSupport new URL by MT business logic and accounts for any breaking changes (see table above)

o Code for reporting changes (refer to reporting section)

Update destination URLs/tracking codes to each keyword match type if applicable(Guideline: 250k updates an hour, note that existing editorial validations and rules will continue to apply as today)

Reporting Changes

Additional Resources

MSDN URL by Match Type Post
Keyword Object (Please navigate to the “Remarks” section of the document).

New Feature: Enhancements to Ad Intelligence v8 API

Ricky Poole - MSFT — Thu, 12 Apr 2012 16:58:00 GMT

In this month’s release, Ad intelligence v8 API enhancements will be incorporated within adCenter. This will impact API customers immediately; we want you to know about this now so you can plan accordingly.

The Ad intelligence v8 API enhancements will allow advertisers to build Keyword list based on new and improved Keyword suggestions and enhance Keyword research and expansion capabilities.

The Ad intelligence v8 API performs the same function at the API layer as the MAI Tool

What You Need to Know

API users need to refresh the WSDL and download the new signatures.
Refer to the API Release Notes and MSDN documentation for details

Key Points:

Advertisers need KW suggestion capability to optimize and expand their KW list with relevant KWs to improve performance of their marketing campaigns and attain their marketing goals.

Ad Center is providing new keyword research service operations that will help enhance programmatic KW research and expansion capabilities, by providing more pivots using keyword category, demographics and location. The feature will enhance relevance and coverage of KW suggestions for advertisers.

For Keyword Suggestions the Ad Intelligence v8 API supports different kinds of Suggestion Types (e.g. based on Related Search terms from Bing, Keywords Associated with the inputs in Campaign etc.)

The enhancements to existing functionality include custom date range for capturing seasonal trends in search volumes and weekly grain in Monetization.

Ad intelligence v8 API includes support for Mobile in some the operations like GetHistoricalKeywordPerformanceByDevice, GetHistoricalSearchCountByDevice , GetKeywordDemographics and GetKeywordLocations

With the Ad Intelligence v8 API enhancement five new service operations have been introduced and one service operation has been updated .Refer to the MSDN documentation for complete programming information

KSP 5.5 and 6.0 API Deprecation

Please note that KSP 5.5 and 6.0 are being deprecated and API users need to move to AdIntelligence v8.
As an adCenter API user, to continue to take advantage of Ad Intelligence make sure you code to API V8 as applications coded to earlier KSP API versions will not function after May 30^th
How to Move to V8

Heads Up: Anticipated Microsoft Advertising adCenter API Reporting Delay on Thursday, March 22nd

Tina Kelleher - MSFT — Wed, 21 Mar 2012 21:30:00 GMT

Some adCenter API users may experience a 2-hour delay in performance reporting starting on March 22nd at 9pm PDT through around 10pm to 2am tonight. Reports are expectedto be running running normally by 11pm PDT, after this 2-hour window has passed.

What the New Negative Keyword Behavior in Microsoft Advertising adCenter Means for API Users | #ppc #sem

Tina Kelleher - MSFT — Fri, 16 Mar 2012 16:00:00 GMT

As we mentioned last month, changes to negative keywords were starting to roll out to all advertisers. As of now, those changes are complete! Negative keywords uploaded at the campaign and ad group level will now be combined to filter traffic, working in tandem with one another. In the past, negative keywords at the ad group level would override those at the campaign level.

You'll find more detail on this change over on the adCenter Blog, you'll find more information for API users over on MSDN.

Coding Heads Up: Share of Voice Changes Coming Soon to Microsoft Advertising adCenter API

Tina Kelleher - MSFT — Fri, 09 Mar 2012 20:45:00 GMT

In this month’s release, there are some enhancements planned for Share of Voice reporting that will impact API customers immediately; we want you to know about this now so you can plan accordingly.

What You Need to Know

New columns will be available in your Account, Campaign and Ad group performance reports to provide more transparency and more actionable information to advertisers overall.
Data value in column 'Impression share lost to rank' will get split across 'Impression share lost to rank' and 'Impression share lost to bid'
Data value in 'Impression share lost to relevance' will get split between 'Impression share lost to landing page relevance' and 'Impression share lost to keyword relevance'

How this will be reflected in API Reporting:

You will see below changes in AccountPerformanceReport, CampaignPerformanceReport and AdPerformanceReport.

Some attribution of ImpressionLostToRankPercent may appear “lower” than before, since we’ve broken out impression share lost to rank out into a new column, called ImpressionLostToBidPercent
ImpressionLostToOthersPercent will now be zero (and restated as zero when pulling data for performance history that’s in the past)
ImpressionLostToRelevancePercent will still exist and be populated, but there where be two new columns: ImpressionLostToLandingPageRelevancePercent and ImpressionLostToKeywordRelevancePercent

As an API user, please review your current reporting and make any coding adjustments in preparation for this change.

Heads Up: Reporting Delays Expected in Microsoft Advertising adCenter API

Tina Kelleher - MSFT — Wed, 22 Feb 2012 00:48:00 GMT

Some adCenter API users may experience up to a 2-6 hour delay with API performance reports beginning Thursday February 23 at 8pm PST through between 10pm PST and 2am PST on Friday February 24. Reports are expected to be running normally by 2am PST on Friday, February 24.

Location Targeting Updates Coming to Microsoft Advertising adCenter API

Tina Kelleher - MSFT — Mon, 20 Feb 2012 17:01:00 GMT

If you saw the post on the adCenter Blog about the location targeting updates that are in the process of rolling out, no doubt you have some questions around what this means for the API.

If you are using the adCenter API, you can expect the following changes based on the version of the API you use.

While it is not required to upgrade to V8 of the adCenter API, please keep in mind that if you use V7:

The system will no longer derive Region from the AdGroup.LanguageAndRegion attribute
If you have not done so already, you will need to explicitly set the LocationTarget object to specify Publisher Countries. If no LocationTargets are specified, adCenter will create a country specific LocationTarget for you based off your previous LanguageAndRegion attribute settings
New LocationTargets will be created only if there is no geo target at the Campaign or Ad Group level (and using “EN_US” in the AdGroup.LanguageAndRegion is not considered geo-targeting)
If there are no geo targets, new LocationTargets will be created at the Ad Group level (and Campaign level targets will not be inherited).

As always, if you have any questions or comment, feel free to leave them in the comments below, post a thread in the API forum, ping us on Twitter, write on our Facebook wall or join the conversation in the newly launched Microsoft Advertising for Small Business LinkedIn group. We’re here to help!

Efficiency Updates Coming Soon to Microsoft Advertising adCenter API

Tina Kelleher - MSFT — Fri, 17 Feb 2012 22:23:00 GMT

Although this information was posted to the adCenter Blog, we wanted to make sure API users are aware of the changes that are coming to adCenter as well.

Here’s a quick summary of the changes that you could start to see as early as mid-February:

As always, if you have any questions or comment, feel free to leave them in the comments below, post a thread in our API forum, ping us on Twitter, write on our Facebook wall or join the conversation in our new LinkedIn group, Microsoft Advertising for Small Business.

Scheduled Maintenance on Microsoft Advertising adCenter API on January 14th

Tina Kelleher - MSFT — Mon, 09 Jan 2012 21:13:00 GMT

If you didn't see the post on the adCenter Blog, please be aware that on Saturday, January 14, 2012, adCenter, pubCenter, the adCenter API and the adCenter Desktop will be unavailable from approximately 11:00 A.M. to 7:00 P.M. Pacific Time for routine system maintenance. Additionally, please be aware that reporting will be delayed through 9:00 P.M., but you shouldn't notice any staleness in data beyond that point.

Though you will be unable to access your accounts during this time, please note that campaigns will continue to run normally and your ads will continue to serve.

We apologize for any inconvenience.

Negative Keyword Refinements in the Microsoft Advertising adCenter API

Eric Urban - MSFT — Thu, 17 Nov 2011 22:00:00 GMT

Last month we reached out to Microsoft Advertising adCenter users to inform that we are deprecating keyword level negative keywords. Starting today, the campaign and ad group level negative keywords will continue to impact delivery in adCenter and any existing keyword level negative keywords will be ignored.

What do these changes mean for adCenter Web users?

In the adCenter Web UI, keyword level negatives will be visible and available for export and historical reporting; adCenter will not recognize keyword level negatives. As a result, any remaining keyword level negatives will no longer restrict ad delivery. It is strongly suggested that advertisers migrate keyword level negatives to the ad group or campaign level.

How will the API be affected?

There will be no breaking API changes, and all add, get, update, delete operations will appear to succeed. We want to emphasize that delivery will not be impacted by keyword level negative keywords, even though the corresponding adCenter API service operations will appear to go through without error.

For example, an API call to the AddKeywords service operation will allow you to add new keyword level NegativeKeywords, and likewise UpdateKeywords will modify existing negative keywords. Again though, any changes will not be utilized for delivery.

Retirement of keyword level negative keywords

You’ll now only need to set negative keywords at the campaign or ad group level, simplifying account management.

Exact Match negative keywords

You can now set Exact Match negative keywords for even greater precision in filtering unwanted search traffic, which means greater campaign performance potential.

Easy identification and resolution of keyword conflicts

The new Negative Keyword Conflicts report and alerts in the adCenter web platform show you when you have negative keywords in conflict with bidded keywords. Resolving keyword conflicts may help improve campaign performance.

Please don't hesitate to reach out if you have any questions or comments; we always have an open ear for feedback.

Thanks!

Heads Up: Microsoft Advertising adCenter API Reporting Delays Expected

Tina Kelleher - MSFT — Wed, 16 Nov 2011 19:00:00 GMT

Some adCenter API users may experience up to a 2-6 hour delay with API performance reports beginning Wednesday November 16, 2011 at 8:00 PM PDT through 2:00 AM PDT Thursday November 17th. Reports are expected to be running normally by November 17, 2011 2:00 AM PDT.

Coming Soon to the Microsoft Advertising adCenter API

Tina Kelleher - MSFT — Wed, 02 Nov 2011 18:59:00 GMT

During the next week we will be announcing upgrades and improvements to the adCenter API. Below you'll find a quick sneak peek at what is coming so you are able to keep track of the announcements and leverage the new functionality as you plan your holiday campaigns.

Much of our focus this year has been around improving the adCenter experience through building features to help you unlock more volume through an engaged audience on Yahoo! Search and Bing marketplace.

Here's what’s new...

• Negative keyword enhancements
We will soon support exact match Negative Keywords, deprecate keyword level negatives to help ease campaign management, and offer a negative keywords conflict report that shows negative keyword conflicts with bidded keywords.

• Share of Voice reporting
Understand your missed impressions, and more effectively prioritize your optimization efforts, with new data available including overall impression share and impression share lost to budge, rank and relevance.

• Historic & aggregate quality scores in reporting
Gain more visibility into your campaign performance and insight into opportunities for campaign optimization. You can now request Historic Quality Score on daily grain which will now be available in the Campaign, Ad Group & Keyword Performance reports.

Other additions...

• We upgraded budget calculation to calculate your monthly budget by multiplying your daily budget amount by the actual number of days in the month instead of the average number, to help reduce cases of campaign pause for months with 31 days
• We’ve updated the way our system examines special characters during the editorial review process to more efficiently identify errors versus special characters
• Our optimizer service provides operations that you can use to discover opportunities for improving campaign performance.

More information will be coming over the next week, so keep checking back for updates (you can also stay in touch via @adCenter or the API RSS feed).

Heads Up: Microsoft Advertising adCenter API Scheduled Maintenance

Tina Kelleher - MSFT — Tue, 01 Nov 2011 18:00:00 GMT

Some adCenter API users may experience up to a 8-12 hour delay with API performance reports beginning Tuesday November 01, 2011 at 9:00 PM PDT through 9:00 AM PDT Wednesday November 2nd. Reports are expected to be running normally by November 2, 2011 9:00 AM PDT.

If you have any questions or concerns, visit the API forum.