adCenter API

ReportAggregation.Summary Value Update: TimePeriod Column Removed

2008-05-09T19:25:00Z

An update to the adCenter API was recently released to allow the ReportAggregation.Summary value to pull the aggregate reports without the TimePeriod column required.

We removed this extra column in the ReportAggregation.Summary value to help streamline your report request and simplify the data we need to create your report.

To use this updated value, you will need to remove the TimePeriod column from the ReportAggregation.Summary value. If you submit the ReportAggregation.Summary value with the TimePeriod column still in place, you may receive a 2034 error message: “The specified report request contains a TimePeriod column which is incompatible with the requested Summary report aggregation. Please submit a report request with valid report columns for a summary report.”

It is important to note that the TimePeriod is still required for all other reports. This only applies to the ReportAggregation.Summary value.

Please let us know if you have questions.

-Chris

Handling Large Arrays in API V5 (.NET)

2008-04-29T19:41:00Z

When transferring large amounts of data (large arrays) in Version 5 of the API when using .NET, some changes to the client configuration may be necessary. The following elements may need to be adjusted in app.config, for example:

· MaxReceivedMessageSize

· MaxBufferSize (should be same size as MaxReceivedMessageSize)

· MaxItemsInObjectGraph

For MaxItemsInObjectGraph, a custom behavior is needed, as shown in the following configuration file snippet:

<bindings>          
    <basicHttpBinding>
        <binding name="BasicHttpBinding_ICampaignManagementService" closeTimeout="00:01:00"
            openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00"
            allowCookies="false" bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"
            maxBufferSize="6553600" maxBufferPoolSize="524288" maxReceivedMessageSize="6553600"
            messageEncoding="Text" textEncoding="utf-8" transferMode="Buffered"
            useDefaultWebProxy="true">
            <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
                maxBytesPerRead="4096" maxNameTableCharCount="16384" />
            <security mode="Transport">
                <transport clientCredentialType="None" proxyCredentialType="None"
                    realm="" />
                <message clientCredentialType="UserName" algorithmSuite="Default" />
            </security>
        </binding>
       
    </basicHttpBinding>
</bindings>

<client>
    <endpoint address="https://adcenterapi.microsoft.com/Api/Advertiser/V5/CampaignManagement/CampaignManagementService.svc"
        binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_ICampaignManagementService"
        contract="ICampaignManagementService" name="BasicHttpBinding_ICampaignManagementService"
    behaviorConfiguration="LargeQuotaBehavior"/>           
</client>

<behaviors>
  <endpointBehaviors>
    <behavior name="LargeQuotaBehavior">
      <dataContractSerializer maxItemsInObjectGraph="2147483647"/>
    </behavior>
  </endpointBehaviors>
</behaviors>

For further information, see the following article on MSDN.

Jeff Dillon, API Support

V5 Error "Bid is less than floor price" when Updating Keyword Bids with Zeroes

2008-04-29T17:01:00Z

When using V5 of the API, it is now possible to send nulls for object properties that should remain intact. However, when sending nulls or zeroes for bids, the system incorrectly sees the bid as less than floor price and you may see an error returned in the response message. We are hoping to resolve this issue this week.

It is ok to send nulls for other object properties in V5, as described in our MSDN API documentation :

V5 offers the 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

API Upgrade for Editorial Validation Errors

2008-04-28T18:33:00Z

We’ve recently updated the adCenter API Production and Sandbox+ environments for Version 5 to improve transparency for editorial decisions.

The EditorialApiFaultDetail.EditorialErrors property now contains any editorial validation errors. Previously, this array was always empty.

This will help you understand editorial decisions, and take action to appropriately update these ads and keywords to meet editorial guidelines.

The adCenter user interface was also upgraded this week with new and improved features each designed to give you easier, more efficient ways to use adCenter. In our upcoming monthly webcast, Shamit Patel, the API program manager, will discuss a comparison of adCenter user interface features and API features.

API Version 5 Live Meeting is schedule May 20th, at 1 p.m. Pacific time. Call-in information to join the conference call will be provided in the Live Meeting.

We will also be preparing articles for the blog to document the comparison of the adCenter UI and API features.

Reminder: Version 4 of the API will be supported for at least 100 days from today. Please continue to actively migrate your applications from Version 4 to Version 5 of the API to avoid any disruption of your service.

adCenter UI Upgrade highlights
For more about the UI upgrades,see the advertiser blog post adCenter spring upgrade: campaign management updates

Thanks

adCenter Team

Slides and Notes from adCenter API V5 Presentation

2008-04-18T21:25:00Z

Those of you who attended the Live Meeting conference on Tuesday had a chance to talk with Shamit Patel, the program manager leading API development for adCenter. We appreciate your taking the time to learn more about the new version and to share your questions and requests. I've attached the PowerPoint slides and notes from the presentation. I will upload the recording of Shamit's session in the next couple days.

Thank you,

-Chris

Using svcutil.exe with adCenter API V5

2008-04-18T16:38:00Z

A question that has come up a few times in the community as you are working to migrate to V5 involves the use of svcutil.exe

For example, a developer asked: with adCenter API v4 and with other search engine advertising APIs, we used the wsdl.exe tool and the /sharetypes switch in the Windows framework SDKs to produce a C# code file. This file included all the services for a single search engine API in one namespace. We were able to add it to a master library that all our programs access.

We have been trying to figure out how to make this happen with the v5 files and the SvcUtil.exe tool as you suggest in your documentation, any suggestions?

Our senior development lead, Gopal Madhavan, and development engineer Sean Yao, tested the use of svcutil.exe to verify and see if there were any suggestions.

Here is the reply from Sean:

"They can use "svcutil.exe /mc <url>*" to generate API proxies with shared types in one file.

For example:

svcutil.exe /mc https://adcenterapi.microsoft.com/api/advertiser/v5/reporting/reportingservice.svc?wsdl https://adcenterapi.microsoft.com/Api/Advertiser/V5/CampaignManagement/CampaignManagementService.svc?wsdl /out:CampaignAndReporting.cs

The system will show some warnings, but it works fine, according to Sean.

Also, check documentation at Getting Started with the Microsoft adCenter API for more general information about using svcutil.

Thank you for the questions and please let us know if you have more questions on this issue.

-Chris

adCenter API V5 Update - Setting Keyword Bid Amounts to Zero

2008-04-18T16:36:00Z

An update was made recently to version 5 of the adCenter API to allow keyword bid amounts to be zero. Prior to this update, if you specified a keyword bid amount of zero, the UpdateKeywords service operation would return error 1515, which means that one or more of the keyword bid amounts are less than the floor price. This prevented you from being able to remove a match type bid that had previously been established.

Now that the update has been published, you can set one or more of the keyword bid amounts to zero and the UpdateKeywords service operation will succeed (assuming that there are no other errors).

Thank You,

Strohm Armstrong
Programming Writer
adCenter API

Announcement: Sandbox Maintenance on Monday

2008-04-17T21:49:45Z

The API Sandbox+ environment will undergo a scheduled maintenance on Monday, April 21. During this maintenance, the adCenter Sandbox user interface will be unavailable intermittently for up to 24 hours beginning at 11:00 A.M. Pacific Time (GMT-8). Calls to the API methods will execute as expected.

If you have questions about the maintenance, please let us know.

-Chris

API Live Meeting Tomorrow -

2008-04-14T17:32:56Z

To assist you with your migration process, we invite you to participate in our third API Version 5 Live Meeting on Tuesday, April 15, from 1 P.M. to 2:30 P.M. Pacific Time.

The April 15 session is the third in a series of adCenter API Live Meeting sessions. This session will feature a live demonstration using new code samples for V5 and a discussion of the most frequently asked questions about differences in V5.

The Live Meetings are a great opportunity to talk with members of the development team. Sessions are held on the third Tuesday of every month. They are recorded and saved for you to listen in later. If you have questions that you'd like the team to address, post them in the comments below or in this forum thread http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=3173789&SiteID=1

If you have not used Live Meeting before, we recommend visiting API Version 5 Live Meeting a few minutes before the session begins to complete any required installation steps. You can listen on line and submit questions via Live Meeting. Also, call-in information to join the conference call will be provided in the Live Meeting.

Sessions scheduled:

Apr 15th 1pm to 2:30pm PST
May 20th 1pm to 2:30pm PST
Jun 17th 1pm to 2:30pm PST
Jul 15th 1pm to 2:30pm PST

Sincerely,

adCenter API Team

How to Check the Status of an Ad Group in PHP (V5)

2008-03-28T19:12:00Z

We will release PHP samples in V5 to MSDN by May 2008. In the interim, we'll use this site to release PHP samples in V5.

After submitting an ad group for review, you can check the status of the ad group by calling the GetKeywordAdAssociationsByAdIds, GetKeywordAdAssociationsByKeywordIds, or GetKeywordAdAssociationsByStatus service operation. The following PHP examples show how to use these service operations to check the status of an ad group. These examples assume that you have already submitted an ad group for review. These examples also assume that you have already determined which ad group IDs, ad IDs, and keyword IDs will be checked; you must substitute your own values for the ad group IDs, ad IDs, and keyword IDs used in the following code.

Thanks,
Walter Poupore
Lead Programming Writer
Microsoft adCenter API

Check the Status of an Ad Group by Using GetKeywordAdAssociationsByAdIds

<?php

// This program requires the following PHP extensions:
// php_soap.dll
// php_openssl.dll

// To ensure that a cached WSDL is not being used,
// disable WSDL caching.
ini_set("soap.wsdl_cache_enabled", "0");

try
{

$adGroupId = 50787199; //Application-specific value.

    // Use either the sandbox or production URI.
    // This example is for the sandbox URI.
    $URI =
        "https://sandboxapi.adcenter.microsoft.com/api/advertiser/v5/";
    // The following commented-out line contains the production URI.
    //$URI = "https://adcenterapi.microsoft.com/api/advertiser/v5/";

// The adCenter API namespace.
$xmlns = "https://adcenter.microsoft.com/api/advertiser/v5";

    // The proxy for the Campaign Management Web service.
    $campaignProxy =
        $URI . "CampaignManagement/CampaignManagementService.svc?wsdl";

// The name of the service operation that will be called.
$action = "GetKeywordAdAssociationsByAdIds";

    // The user name, password, and developer token are
    // expected to be passed in as command-line
    // arguments.
    // $argv[0] is the PHP file name.
    // $argv[1] is the user name.
    // $argv[2] is the password.
    // $argv[3] is the developer token.
    if ($argc !=4)
    {
        printf("Usage:\n");
        printf(
          "php file.php username password devtoken\n");
        exit(0);
    }
    $username = $argv[1];
    $password = $argv[2];
    $developerTokenValue = $argv[3];
    $applicationTokenValue="";

    // Assign the credentials to the classes
    // that are used by the SOAP headers.
    $userCredentials=new UserCredentials();
    $userCredentials->Username=$username;
    $userCredentials->Password=$password;
    $developerToken=new DeveloperToken();
    $developerToken->Value=$developerTokenValue;
    $applicationToken=new ApplicationToken();
    $applicationToken->Value=$applicationTokenValue;

    // Create the SOAP headers.
    $headerApplicationToken =
        new SoapHeader
        (
            $xmlns,
            'ApplicationToken',
            $applicationToken,
            false
        );
    $headerDeveloperToken =
        new SoapHeader
        (
            $xmlns,
            'DeveloperToken',
            $developerToken,
            false
        );
    $headerUserCredentials =
        new SoapHeader
        (
            $xmlns,
            'UserCredentials',
            $userCredentials,
            false
        );

    // Create the SOAP input header array.
    $inputHeaders = array
    (
        $headerApplicationToken,
        $headerDeveloperToken,
        $headerUserCredentials
    );

    $adIds = array
    (
        164481,
        258488,
    );

    // Create the SOAP client.
    $opts = array('trace' => true);
    $client = new SOAPClient($campaignProxy, $opts);

    // Specify the parameters for the SOAP call.
    $params = array
    (
        'AdGroupId' => $adGroupId,
        'AdIds' => $adIds
    );

    // Execute the SOAP call.
    $result = $client->__soapCall
    (
        $action,
        array( $action.'Request' => $params ),
        null,
        $inputHeaders,
        $outputHeaders
    );

    print "$action succeeded with Tracking ID "
          . $outputHeaders['ApiCallTrackingData']->TrackingId
          . ".\n";

    if (isset($result->KeywordAdAssociations->ArrayOfKeywordAdAssociation))
    {
        $associationsArray = $result->KeywordAdAssociations->ArrayOfKeywordAdAssociation;

        // Ensure that ArrayOfKeywordAdAssociations is an array.
        if ( 2 > sizeof($associationsArray))
        {
            // Only a single object, not an array, was returned.
            // Convert the object into an array.
            $temp = array();
            $temp[] = $associationsArray;
            $associationsArray = array();
            $associationsArray = $temp;
        }

        // Process each array of keyword ad associations.
        for ($i = 0; $i < sizeof($associationsArray); $i++)
        {
            $associations = $associationsArray[$i]->KeywordAdAssociation;
            if ( 2 > sizeof($associations))
            {
                // Only a single object, not an array, was returned.
                // Convert the object into an array.
                $temp = array();
                $temp[] = $associations;
                $associations = array();
                $associations = $temp;
            }

            // Print each keyword ad association.
            foreach ($associations as $association)
            {
                if (!isset($association->KeywordId))
                {
                    // There was no association returned.
                    continue;
                }

                // Print out the keyword ID, ad ID, and status.
                print "Keyword ID $association->KeywordId ";
                print "associated with ad ID $association->AdId ";
                print "has status $association->Status.\n";
            }
        }
    }
}

catch (Exception $e)
{

    print "$action failed.\n";

    // Display the fault code and the fault string.
    print $e->faultcode . " " . $e->faultstring . ".\n";

print "TrackingID: " .
$e->detail->ApiFaultDetail->TrackingId . ".\n";

    // Process operation errors.
    if (isset(
        $e->detail->ApiFaultDetail->OperationErrors->OperationError
        ))
    {
        if (is_array(
            $e->detail->ApiFaultDetail->OperationErrors->OperationError
            ))
        {
            // An array of operation errors has been returned.
            $obj =
                $e->detail->ApiFaultDetail->OperationErrors->OperationError;
        }
        else
        {
            // A single operation error has been returned.
            $obj = $e->detail->ApiFaultDetail->OperationErrors;
        }
        foreach ($obj as $operationError)
        {
            print "Operation error " .
                $operationError->Code . " encountered. ";
            print $operationError->Message . "\n";
        }
    }

    // Process batch errors.
    if (isset(
        $e->detail->ApiFaultDetail->BatchErrors->BatchError
        ))
    {
        if (is_array(
            $e->detail->ApiFaultDetail->BatchErrors->BatchError
            ))
        {
            // An array of batch errors has been returned.
            $obj = $e->detail->ApiFaultDetail->BatchErrors->BatchError;
        }
        else
        {
            // A single batch error has been returned.
            $obj = $e->detail->ApiFaultDetail->BatchErrors;
        }
        foreach ($obj as $batchError)
        {
            print "Campaign index " . $batchError->Index . "\n";
            print "Batch error " .
                $batchError->Code . " encountered. ";
            print $batchError->Message . "\n";
        }
    }

}

// Definitions for classes that are used by the SOAP headers.
class ApplicationToken
{
    public $Value;
}
class DeveloperToken
{
    public $Value;
}
class UserCredentials
{
    public $Password;
    public $Username;
}

Check the Status of an Ad Group by Using GetKeywordAdAssociationsByKeywordIds

<?php

// This program requires the following PHP extensions:
// php_soap.dll
// php_openssl.dll

// To ensure that a cached WSDL is not being used,
// disable WSDL caching.
ini_set("soap.wsdl_cache_enabled", "0");

try
{

$adGroupId = 50787199; //Application-specific value.

// The adCenter API namespace.
$xmlns = "https://adcenter.microsoft.com/api/advertiser/v5";

    // The proxy for the Campaign Management Web service.
    $campaignProxy =
        $URI . "CampaignManagement/CampaignManagementService.svc?wsdl";

// The name of the service operation that will be called.
$action = "GetKeywordAdAssociationsByKeywordIds";

    // Create the SOAP input header array.
    $inputHeaders = array
    (
        $headerApplicationToken,
        $headerDeveloperToken,
        $headerUserCredentials
    );

    $keywordIds = array
    (
        58528531,
        58527999,
        58528000,
        58528001
    );

    // Create the SOAP client.
    $opts = array('trace' => true);
    $client = new SOAPClient($campaignProxy, $opts);

    // Specify the parameters for the SOAP call.
    $params = array
    (
        'AdGroupId' => $adGroupId,
        'KeywordIds' => $keywordIds
    );

    // Execute the SOAP call.
    $result = $client->__soapCall
    (
        $action,
        array( $action.'Request' => $params ),
        null,
        $inputHeaders,
        $outputHeaders
    );

    print "$action succeeded with Tracking ID "
          . $outputHeaders['ApiCallTrackingData']->TrackingId
          . ".\n";

    if (isset($result->KeywordAdAssociations->ArrayOfKeywordAdAssociation))
    {
        $associationsArray = $result->KeywordAdAssociations->ArrayOfKeywordAdAssociation;

        // Ensure that ArrayOfKeywordAdAssociations is an array.
        if ( 2 > sizeof($associationsArray))
        {
            // Only a single object, not an array, was returned.
            // Convert the object into an array.
            $temp = array();
            $temp[] = $associationsArray;
            $associationsArray = array();
            $associationsArray = $temp;
        }

        // Process each array of keyword ad associations.
        for ($i = 0; $i < sizeof($associationsArray); $i++)
        {
            $associations = $associationsArray[$i]->KeywordAdAssociation;
            if ( 2 > sizeof($associations))
            {
                // Only a single object, not an array, was returned.
                // Convert the object into an array.
                $temp = array();
                $temp[] = $associations;
                $associations = array();
                $associations = $temp;
            }

            // Print each keyword ad association.
            foreach ($associations as $association)
            {
                if (!isset($association->KeywordId))
                {
                    // There was no association returned.
                    continue;
                }

                // Print out the keyword ID, ad ID, and status.
                print "Keyword ID $association->KeywordId ";
                print "associated with ad ID $association->AdId ";
                print "has status $association->Status.\n";
            }
        }
    }
}

catch (Exception $e)
{

    print "$action failed.\n";

    // Display the fault code and the fault string.
    print $e->faultcode . " " . $e->faultstring . ".\n";

print "TrackingID: " .
$e->detail->ApiFaultDetail->TrackingId . ".\n";

}

Check the Status of an Ad Group by Using GetKeywordAdAssociationsByStatus

<?php

// This program requires the following PHP extensions:
// php_soap.dll
// php_openssl.dll

// To ensure that a cached WSDL is not being used,
// disable WSDL caching.
ini_set("soap.wsdl_cache_enabled", "0");

try
{
$adGroupId = 50787199; //Application-specific value.

// The adCenter API namespace.
$xmlns = "https://adcenter.microsoft.com/api/advertiser/v5";

    // The proxy for the Campaign Management Web service.
    $campaignProxy =
        $URI . "CampaignManagement/CampaignManagementService.svc?wsdl";

// The name of the service operation that will be called.
$action = "GetKeywordAdAssociationsByStatus";

    // Create the SOAP input header array.
    $inputHeaders = array
    (
        $headerApplicationToken,
        $headerDeveloperToken,
        $headerUserCredentials
    );

    // Create the SOAP client.
    $opts = array('trace' => true);
    $client = new SOAPClient($campaignProxy, $opts);

    // This sample checks for the Active status.
    // Update your code as needed to check for
    // different statuses.
    $status = "Active";

// Show all status changes since Jan. 1, 2008, at 12:00 P.M. (noon).
$modifiedAfter = '2008-01-01T12:00:00.000Z';

    // Specify the parameters for the SOAP call.
    $params = array
    (
        'AdGroupId'     => $adGroupId,
        'ModifiedAfter' => $modifiedAfter,
        'Status'        => $status
    );

    // Execute the SOAP call.
    $result = $client->__soapCall
    (
        $action,
        array( $action.'Request' => $params ),
        null,
        $inputHeaders,
        $outputHeaders
    );

    print "$action succeeded with Tracking ID "
          . $outputHeaders['ApiCallTrackingData']->TrackingId
          . ".\n";

    if (isset($result->KeywordAdAssociations))
    {
        $associations = $result->KeywordAdAssociations->KeywordAdAssociation;

        // Ensure that $associations is an array.
        if ( 2 > sizeof($associations))
        {
            // Only a single object, not an array, was returned.
            // Convert the object into an array.
            $temp = array();
            $temp[] = $associations;
            $associations = array();
            $associations = $temp;
        }

        // Print each keyword ad association.
        foreach ($associations as $association)
        {
            if (!isset($association->KeywordId))
            {
                // There was no association returned.
                continue;
            }

            // Print out the keyword ID, ad ID, and status.
            print "Keyword ID $association->KeywordId ";
            print "associated with ad ID $association->AdId ";
            print "has status $association->Status.\n";
        }
    }
}

catch (Exception $e)
{

    print "$action failed.\n";

    // Display the fault code and the fault string.
    print $e->faultcode . " " . $e->faultstring . ".\n";

print "TrackingID: " .
$e->detail->ApiFaultDetail->TrackingId . ".\n";

}

How to Submit an Ad Group for Approval in PHP (V5)

2008-03-28T19:09:00Z

We will release PHP samples in V5 to MSDN by May 2008. In the interim, we'll use this site to release PHP samples in V5.

Ad groups are submitted for approval by calling the SubmitAdGroupForApproval service operation. The approval process includes several automated checks for relevance and adherence to Editorial Guidelines. Generally, an ad is approved or disapproved immediately after being submitted. In some cases, however, the process might take up to five business days.

The following PHP example shows how to submit an ad group for approval by using SubmitAdGroupForApproval. This example assumes that you have already created your ads and keywords. This example also assumes that you have already determined which ad group ID will be submitted for approval; you must substitute your ad group ID for the $adGroupId variable that is assigned 50786905 in the following code.

Thanks,
Walter Poupore
Lead Programming Writer
Microsoft adCenter API

<?php

// This program requires the following PHP extensions:
// php_soap.dll
// php_openssl.dll

// To ensure that a cached WSDL is not being used,
// disable WSDL caching.
ini_set("soap.wsdl_cache_enabled", "0");

try
{

$adGroupId = 50786905; //Application-specific value.

// The Microsoft adCenter API namespace.
$xmlns = "https://adcenter.microsoft.com/api/advertiser/v5";

    // The proxy for the Campaign Management Web service.
    $campaignProxy =
        $URI . "CampaignManagement/CampaignManagementService.svc?wsdl";

// The name of the service operation that will be called.
$action = "SubmitAdGroupForApproval";

    // Create the SOAP input header array.
    $inputHeaders = array
    (
        $headerApplicationToken,
        $headerDeveloperToken,
        $headerUserCredentials
    );

    // Create the SOAP client.
    $opts = array('trace' => true);
    $client = new SOAPClient($campaignProxy, $opts);

    // Specify the parameters for the SOAP call.
    $params = array
    (
        'AdGroupId' => $adGroupId
    );

    // Execute the SOAP call.
    $result = $client->__soapCall
    (
        $action,
        array( $action.'Request' => $params ),
        null,
        $inputHeaders,
        $outputHeaders
    );

    print "$action succeeded with Tracking ID "
          . $outputHeaders['ApiCallTrackingData']->TrackingId
          . ".\n";

}

catch (Exception $e)
{

    print "$action failed.\n";

    // Display the fault code and the fault string.
    print $e->faultcode . " " . $e->faultstring . ".\n";

print "TrackingID: " .
$e->detail->ApiFaultDetail->TrackingId . ".\n";

}