LookSmart® API v4.0 Developer Implementation Guide
  Introduction
  Accounts Service
  Campaigns Service
  Ad Groups Service
  Ads Service
  Keywords Service
  Reports Service
  Geo Locations
Frequently Asked Questions
Implementation Guide

version 3
 

Frequently Asked Questions

General FAQ's
Visual Studio FAQ's
Perl FAQ's
PHP FAQ's

General FAQs

These FAQs are independent of development tool or programming language used.

What kinds of errors will I see as I am developing my code?

Error messages returned by the runtime system generally fall into two categories:

  • runtime exceptions - global system errors, usage limits and permissions problems
  • validation failures - a human-readable log of all business rules that failed validation during the transaction

Runtime exceptions are those you can recover from at the time you accessed one of the web service methods. For example, when you encounter a database or usage limit error, you can simply resubmit your query. Unfortunately dealing with permissions problems will most likely require you to access the web console directly, or work with an account manager to obtain the appropriate permissions.

Validation failures are those that you should be detecting in your own system code well before you submit your request to the web service. The business rules that your records must adhere to are documented in the reference section of this guide. It is encouraged that you create unit tests for each of these rules to ensure that you do not waste system resources by submitting invalid data.

When adding to, or updating items in my account, how can I know which fields are required?

Every record type in the system will contain a mixture of required and optional fields. For example, a campaign has an optional field called the start_date. The campaign does not require that the advertiser enter a start_date in order for the campaign to be considered valid. Optional fields are documented in this guide.

A handful of convenience methods, prefixed by the word Update, allow you to update specific attributes of a campaign, ad group, ad or keyword. In those cases, only one or two attributes your data structure will be examined, and the rest ignored. For example, the UpdateCampaignState method will modify the campaign state only, and the only fields actually required to be present in the request are campaign_id and campaign_state.

In general, the documentation for a particular should clearly point out the breakdown between optional and required fields.

The web service is asking me for a credit card number in the sandbox environment; is there an alternative I can use?

You don't have to provide a real credit card number in the sandbox environment where your only goal is to test your application. Instead, you can use 4111 1111 1111 1111 as a fake credit card number.

If an ad or keyword is rejected, will the SOAP response indicate what the user needs to do to make the ad acceptable?

If your ad or keyword is rejected, the SOAP response will indicate as much as well as highlight the reason for the rejection.

Please note that an ad might be accepted, but placed on a review queue subject to the approval of the editorial staff. In this case, you will get a normal SOAP response showing that the ad was successfully added or updated, but will not receive any indication in that the ad was placed in a review queue. Please see the help section for more details on our editorial guidelines and review process.

Can I bid on the same keyword in two separate campaigns? If I can, will they compete against each other?

Yes, you can bid for the same keyword in the different campaigns. You can even bid for the same keyword in the same campaign. The any ads from the same advertiser associated with the same keyword will compete with each other based on yield. Yield is essentially click-through-rate (CTR) * cost-per-click (CPC).

What is the recommended limit on the number of keywords or ads I can upload or download at one time?

As a general rule, uploading between 100-500 items at a time is probably a safe bet.

Larger data sets should always be downloaded using our the paginated API methods. The paginated methods break up a large download request into multiple pages of data. The client can then iterate through the total number of data pages, requesting each one in turn.

For example, you can you use GetNumKeywordPagesForAccount to get the total number of keyword pages in an account and then use GetKeywordsForAccountByPage to download each page in turn. Please refer to the documentation for the specific services for more information.

The case of method calls, structures, and variables don't match the API reference in my particular programming language.

Case is going to vary by programming language to an extent. You might see lowercase when working with C++, mixed case in Visual Studio, and camel case in other products.

If your programming environment creates a reference to the API web site for you (as is the case with Visual Studio), the environment generally changes the case to match whatever you would normally use.

When working with languages that don't provide reference automation, use the capitalization found the WSDL file, which is the reference your programming environment uses to make the web service connection.

Why does the the web service time out before it returns any data?

Some SOAP packages set very low timeout values, which means that longer data requests won't complete before the timeout has passed.

Depending on the SOAP product you use, you can normally set the service object to allow a longer timeout value. Please see the platform specific FAQ's or specific client libraries for ways to increase the timeout for your application.

How can I see the raw SOAP messages for my application?

Generally, you can use a proxy such as proxyTrace to see the messages. All you need to do is set the proxy property for your service object to use a proxy. Make sure you point proxyTrace to the same port that you use for the proxy setting in the service object. Unfortunately, this solution doesn't work for Visual Studio where you must create a special class to trap the raw XML. See the Visual Studio FAQs section for details.

Your SOAP package provider should also provide additional details on how to set your application to capture raw SOAP messages.

Are there any ad_state values for ad variations that are pending or rejected?

The ad_state for an ad will be either on or off depending on the review status of your ad.

If you submit an ad variation that needs to go into review, the ad_state, attribute will be set to on but the ad variation will not go into distribution.

If an ad variation under review is rejected, we&quo;ll send an email to the email address associated with your account along with the reason for the rejection. In this case the ad_state attribute will be set to off The API will show ad_state=OFF.

If an ad variation under review is accepted, nothing will happen. It will continue to remain on.

How do I get the position of my keyword?

Use the GetBidLandscape or GetBidLandscapes methods to obtain the keyword information.

The response will contain the following element:

<expected_position xsi:type="xsd:int"> </expected_position>

to show the keyword’s position.

How does someone use the API to cancel or delete a campaign, ad group, ad variation, or keyword?

There is no real way to cancel or delete a campaign, ad group, ad variation, or keyword. You can, however, turn each of these entities off.

To turn off a campaign you can call the UpdateCampaign method with fully populated CampaignStruct, setting campaign_state = OFF. You can now also use the UpdateCampaignState method, which requires you to only specify values for campaign_id and campaign_state.

There are similar methods in the You can use similar methods in the Ad Groups, Ads and Keywords services, that you can use to turn those entities on and off. Please consult the documentation for the individual services for details.

Sending a value for the CPC field does not make sense for a negative keyword, does it need to be included in the SOAP request? Can you send me an example request of adding a negative keyword?

The max_cpc is not required for any keyword. To add a negative keyword to an ad group you should just be able proceed as you would for any other keyword, but set the value for match_type_id to 3 (negative broad), or 5 (negative smart). You can use the AddCampaignNegativeKeyword to add negative keywords at the campaign level.

How can I use the API to determine whether an ad is pending or rejected? Do values for ad_state returned by the GetAd method reflect pending or rejected ads?

Unfortunately not, We won't have a value for pending or rejected in ad_state anytime soon. For now it's just on or off.

Is there any way to remove a keyword or ad variation from an ad group?

As mentioned above, there is no way to permanently delete an ad variation or keyword from a campaign. However, you can use methods in the various services to turn those elements on and off.

How can I pause a campaign?

To pause a campaign, simply set the state of that campaign to off. As a convenience, you can use the updateCampaignState and updateCampaignStates methods to modify the state a particular campaign or multiple campaigns respectively.

Please note that any campaign that currently off will be turned back on automatically if the start date of that campaign is set to a date in the future.

To permanently pause a campaign, set the campaign state to off and the start date to NULL.

I cannot use a NULL value for a Date. What should I use?

For methods that require a date field that you want to ignore, use the date January 1, 1970 as a substitute. The system will treat that date value the same as it would a null value.

How do I ignore the max_cpc field when I am adding or changing keyword targets?

Use the value -1 for the max_cpc field when attempting to add or modify keyword targets where you do not want to specify a value.

How is the API typically used?

Our intent is that partners will do bulk processing once every day to create or update their campaigns and pull reporting data. We have a discussion on how we intend the web service to be used on our blog, here: http://blogs.looksmart.com/developers

With that said, partners do in fact access the web service multiple times in one day. For example, some partners will pull the previous days' spend reports early in the morning and schedule campaign updates for later in the day.

Are there access limits to the API?

In its current state, the web service is set up to be used for batch processing once per day. With that said, partners do in fact access the web service multiple times in one day. Some of those transactions may be long-running (several minutes), especially campaign updates. So, to prevent any one user from consuming the majority of API resources there are limits on the total number of concurrent requests an API user may submit. At present, an API token may not have more than 5 (five) open requests at any one time.

This limit helps ensure that no one API partner will prevent another from using the web service. In addition, we ask that our partners observe the bulk nature of our API, further ensuring that other partners are not locked out of the service. Since we do not currently charge for transaction fees, we hope our partners will share the resource by observing our guidelines.

How can I get more than one production token?

It is our general policy to issue only one API Token per partner. As we currently do not limit the total number of transactions in a day, only the number of simultaneous transactions, you should not need more than one token. Our main goal is that we are able to sufficiently provision our web service so that we are able to accomdate all of our advertisers as they grow their accounts.

When is reporting data available?

Reports run today will show data for the current business day. Reporting data is updated hourly with a one hour delay. For example a report that is run at 15:00 should generally contain data for the current day through 13:59. At most reporting data should be two hours old.

Visual Studio FAQs

The questions in this section affect developers who use Visual Studio as their development environment. You may not always see these issues when working with Visual Studio, but enough developers have seen these problems that they are worth mentioning.

The Web Service request times out before it returns any data.

As mentioned previously, sometimes a request takes longer than expected and the client times out before you receive a response. When working with Visual Studio, you'll create the service object and then set the timeout value as shown here.

Dim RS As New ReportsService()
RS.Timeout = Integer.MaxValue

Refer to the documentation for the SOAP package that you're using for additional details on how to set the timeout value. Every SOAP package uses a slightly different method for performing this task.

I receive a 417 error when I make a request of the API.

A 417 error signifies that the server doesn't understand the 100-Continue expectation. Visual Studio developers will always encounter this error unless they apply the required fix to their application. Here is the code to fix this problem in Visual Studio:

System.Net.ServicePointManager.Expect100Continue = false;

As an alternative, when working with ASP.NET applications, you can set the Expect100Continue property false using an application setting. Here's the required setting information.

<configuration>
<system.net>
<settings>
<servicePointManager expect100Continue="false" />
</settings>
</system.net>
</configuration>

Visual Studio won't allow me to use a proxy to obtain raw SOAP messages for diagnosis; what can I do?

Visual Studio applications will generally freeze when you try to use a product such as tcpTrace or proxyTrace to obtain raw SOAP messages. Fortunately, you can create a special class to intercept and save the raw SOAP messages. Contact your account manager or customer service representative for additional information about this technique.

How can I configure Visual Studio to provide dynamic Web references so the same code works in both the sandbox and production environments?

You can change the <appSettings> section of the App.config file for your application to hold the Web reference you need. Using this approach, all you need to do is modify one entry to change from the sandbox to the production environment. The new entry will look like this one:

<add key="[Web Service Namespace]" value="" />

Notice that the entry doesn't point to the WSDL file. If you modify the entry so it does point to the WSDL file, you'll receive a "POST not supported" response from the server. You need one entry for each of the services that is offered. For example, when you want to make account calls, the entry changes to:

<add key="[Web Service Namespace]" value="accounts/api" />

The <appSettings> section can contain all of the entries when necessary to provide full access to the API. However, you should only provide the entries you actually need to avoid introducing performance problems.

Perl FAQs

The questions in this section affect developers who use Perl as their development environment. Whether you see these issues depends on the SOAP package you use and the development platform you rely on. Some issues only appear when working with specific versions of Perl.

I receive a Type 'IntegerArray' can't be found in a schema class 'SOAP::Serializer' error when using PERL

Newer versions of the SOAP::Lite library don't provide the support required by the API. Use the 0.55 or 0.60 version of the SOAP::Lite library, rather than versions 0.65 and newer.

What can I do when I see a deprecated error message when processing data using Perl?

It's easy to get confused when working with the complex data types that SOAP returns from a call. A piece of data that looks like a hash may actually generate a warning when you process it that way. Consequently, even though this code would return the proper information from a GetCampaignsForAccounts method call

#Display the results on screen.
foreach $item (@{$output}) {
print %{$item}->{'campaign_id'}, "\n";
}

…you should use this method to process the data instead

# Display the results on screen.
foreach $item (@{$output}) {
print $item->{'campaign_id'}, "\n";
}

PHP FAQs

The questions in this section affect developers who use PHP as their development environment. Whether you see these issues depends on the SOAP package you use and the development platform you rely on. Some issues only appear when working with specific versions of PHP.

I'm having trouble with my PHP code because I think I'm correctly invoking the API web method, but when I display the response it is empty.

Of course, there can be many causes for your empty response. But a good first step in debugging your problem is to examine the SOAP message that your PHP code is sending, and the SOAP response from the web server.

You can generate this "raw" XML using the methods of the proxy object you created in your PHP code to access the API. Here's the code that does it (for a program run from the command line):

echo "\n Request:\n {proxy->request}\n";
echo "\n Response:\n {proxy->response}\n";

If you are working with PHP in a web browser, you can add code like this to display the message and response:

echo "\n Request:\n";
echo $proxy->request;
echo "\n Response:\n";
echo $proxy->response;

I'm trying to call the GetCampaignsmethod of the Campaigns service using PHP in a web page, and the method isn't returning anything to me, or is returning an error, even though I am sure I have passed it the correct arguments.

Make sure that you explicitly type your arguments to the requirements of the API method. For example, if the user enters the account id on one page and then the application posts the results to another PHP web page, PHP will pick it up as a string.

You need to cast it to integer type explicitly, which is what GetCampaignListForAccounts is expecting for this argument like this:

$account = (int) $_POST['account'];
...

You'll get an empty return value, or an error, if you just pick up the posted value without the explicit cast, which is the normal procedure. For more details, see the PHP samples.

I receive a 417 error when I make a request of the API.

If you are using the NuSOAP library, there is a workaround for the 417 error but it invloves an edit to the library itself. to the NuSoap library. Please contact your account manager or customer service representative for more details.