Google's DoubleClick for Publishers API

Taking a closer look at the Publisher Query Language and the future

noreply@blogger.com (Admin) — Fri, 7 May 2010 15:00:00 -0700

Recently we launched v201004, and with that introduced the new Statement object which gives support for one of our top requested features - bind variables. In this blog post, we will take a closer look at the Publisher Query Language (PQL), Statements with bind variables, and what we have in store for the future.

Publisher Query Language

PQL plays a very significant role in the DFP API by providing the developer with a robust way of filtering which objects should be retrieved or modified before the request is completed. In other words, if you would like to retrieve only orders which are in the draft state, you could take one of two approaches. You could fetch all orders within your network and filter them one by one or instruct the server to only fetch orders in the draft state before returning all results. By doing the latter, the DFP API allows developers to create smaller and more direct requests, and, in turn, increases the efficiency of their code.

PQL has a very similar syntax to SQL, but does not include keywords such as SELECT or FROM; they are implied by the method which uses the PQL statement. The following piece of code constructs a Statement capable of fetching orders in the draft state and retrieves those orders:

// Create a statement to only select orders in the
// 'DRAFT' state.
Statement filterStatement = new Statement();
filterStatement.setQuery("WHERE status = 'DRAFT' LIMIT 500");
OrderPage orderPage =
      orderService.getOrdersByStatemet(filterStatement);

The documentation included for each "get*ByStatment" (e.g. getOrdersByStatement) method indicates which PQL fields map to which object properties.

Paging

The result for "get*ByStatment" calls are pages specific to the service; i.e. an OrderPage is returned by getOrdersByStatement. The limit for the number of objects that can be fetched for a single PQL request, and in a single Page, is 500. Because of this, you should always include LIMIT 500 in your statement. However, if you would like to fetch more than 500 objects, you will need to page through the results by including an OFFSET <#> in your statement as well. To page through orders in groups of 500, for example, in your statement, you would include LIMIT 500 as well as an OFFSET of an interval of 500.

This can be represented by the following code:

// Sets defaults for page and filter.
OrderPage page = new OrderPage();
Statement filterStatement = new Statement();
int offset = 0;

do {
    // Create a statement to get all orders.
    filterStatement.setQuery(
        "WHERE status = 'DRAFT' LIMIT 500 OFFSET " + offset);

    // Get orders by statement.
    page = orderService.getOrdersByStatement(filterStatement);

    if (page.getResults() != null) {
      int i = page.getStartIndex();
      for (Order order : page.getResults()) {
        System.out.println(i + ") Order with ID \""
          + order.getId() + "\", name \"" + order.getName()
          + "\", and advertiser ID \"" + order.getAdvertiserId()
          + "\" was found.");
        i++;
      }
    }
    offset += 500;
} while (offset < page.getTotalResultSetSize());

The loop will end when there are no pages left, i.e. the offset is greater than or equal to the to the total result set size.

Bind variables

Bind variables were recently introduced to allow for reusing of the same template PQL statement combined with varying parameters. To change the PQL statement above to differ which status is being selected, 'DRAFT' is changed to the bind variable status, represented by :status. Note that bind variables can be any name - not just the name of their property. We chose :status here for simplicity.

// Create a statement to only select orders in the state
// bound to status.
Statement filterStatement = new Statement();
filterStatement.setQuery("WHERE status = :status LIMIT 500");

To bind to :status, you will need to create a parameter map with a String_ParamMapEntry coupling :status with a StringParam. Note that ":" is not included in the bind variable name in the parameter map.

// Create the string parameter.
StringParam stringParam = new StringParam();

// Create bind parameters map.
String_ParamMapEntry[] paramMap = new String_ParamMapEntry[] {
      new String_ParamMapEntry("status", stringParam)
};

filterStatement.setParams(paramMap);

Before you make the call to getOrdersByStatement, set the stringParam value to the specific status.

stringParam.setValue("DRAFT");

In this case, because status was bound to a variable declared before the parameter map, you can set the variables value at any time.

The first iteration of the while loop above would then produce the following XML snippet:

...
<filterStatement>
    <query>WHERE status = :status LIMIT 500 OFFSET 0</query>
    <params>
      <key>status</key>
      <value xmlns:ns2=
          "https://www.google.com/apis/ads/publisher/v201004"
          xsi:type="ns2:StringParam">
        <value>DRAFT</value>
      </value>
    </params>
</filterStatement>
...

Planned features and production

The release of v201004 was the culmination of the last step before we can begin rolling out access to the production API and we will have more information about signing up to for production use in the coming weeks. We are still hard at work on the forecasting and reporting service and will have some news about those in the following weeks as well.

We appreciate all of the great feedback we've been receiving on the forum, both on the API and the client libraries, and we''ll continue to incorporate it as we continue development.

Getting Started with the API: Sandbox Environment

noreply@blogger.com (Admin) — Mon, 29 Mar 2010 17:00:00 -0700

As most of you are now aware, there are two API environments - the sandbox and production. The production environment is the one in which your real ads run; this is the environment you log into on the website. The API also has a second environment, the sandbox, which allows developers to test their code before affecting any live running ads. Production API access is in the process of being rolled out, and we'll have a blog post soon detailing how to get access. Today, we'll discuss some of the less known features of the sandbox and some new tools we've developed.

Inviting users to your network

A feature of the API that may be not immediately obvious is that the UserService allows a user with Administrator rights to create a user directly in their network. Any developer can currently do this without having the new user signup first. For example, if you are trying out the API for the first time, instead of performing every API call as an Administrator (the default for your email address), you may want to create a few users with roles such as Salesperson, Trafficker, or Advertiser to test real-world workflows.

Create some new gmail addresses such as my.name.dfp.salesperson@gmail.com.
Alternatively, register an existing non-gmail address as a new Google account.
Call createUsers with that new address and the chosen Role.
You can now log in with that new user using that user's email and password while generating your authentication token.

As a quick note, calling createUsers with an address that already has access to the sandbox, will create a new network for that user. For example, if dfp.user1@gmail.com and dfp.user2@gmail.com separately sign up for the sandbox, each account has its own independent network and objects. If dfp.user1@gmail.com invites dfp.user2@gmail.com to their network by calling createUsers with dfp.user2@gmail.com, dfp.user2@gmail.com will now have access to both networks. To decide which network dfp.user2@gmail.com will connect to, the correct networkCode will need to be supplied when making an API call. Making any API call without the proper networkCode will throw an exception.

Sandbox playground

We've listened your feedback and the top feature request was the ability to view the data in the sandbox. Today, we are announcing the DFP API Sandbox Playground.

With this online tool, you'll be able to log in via OAuth to view the objects within your network. We've also added the ability to test PQL statements directly in the tool. This app is built upon the current PHP sample web application and we'll backport many of the new features into the open-source application soon.

We also understand that having production access to the real website is also necessary for many developers. We are working on rolling this out and will have more information soon.

Monthly sandbox refresh

As a final note, the Sandbox is refreshed once a month as part of our server maintenance process. After a refresh, your account will only have the root ad unit, a test salesperson, and a test trafficker. We'll announce the next sandbox refresh coming up at the end of the month on our forum as usual.

Thanks for your continued feedback and support, and stay tuned for more info about our release to the production environment!

Getting Started with the API: The Web Services

noreply@blogger.com (Admin) — Tue, 2 Mar 2010 14:00:00 -0800

First off, we'd like to thank everyone for the feedback thus far; we will continue to incorporate it as we plan new features for the API. We are also very excited about the applications we've seen being built and would love to hear more about them on our forum.

Today, in the first part of our Getting Started with the API series, I'd like to discuss some of the more technical aspects of the API. As many of our developers are just getting started with the API, I'd like to remind everyone that we provide a full documentation site, and much of the following information is taken from there. I'd also like to point out that if at any time you feel we could better document a feature or expand on a detail, please do not hesitate to leave any suggestions on our feedback survey.

General service overview

As you have most likely determined by now, our API uses SOAP and provides one WSDL per service. The output from code generation on each WSDL can be combined to create the complete API; this is currently what we are doing in the client libraries.

Our API is versioned and, because objects are separated into namespaces according to their version, objects from one version will not work with any other version. We will support multiple versions of the API at the same time - both in our documentation and in our client libraries. Our versioning timeline has not yet been determined, but each version will have at least a 4 month sunset period before it is disabled.

Our API is highly consistent; each service has the same methods:

createObject
createObjects
getObject
getObjectsByFilter
performObjectAction
updateObject
updateObjects

* Note here that these methods are examples where Object would be replaced, by Order or LineItem.

In each service, all methods act on a single type of Object. For example, the OrderService only provides methods to create, get, or update orders; i.e. getOrdersByFilter and updateOrders. This allows you to develop a standard way of handling service invocation in your application; you will always call getObjectsByFilter, but the filter may change depending on the service, and it will always return some type of Page.

For creating objects, we provide two methods that are interchangeable - createObject and createObjects; createObjects is simply a convenience method that performs the same task as createObject.

To create an object, a local object is created with all the required fields and passed via one of the mentioned methods. The returned object will be the result of this creation. It will have its defaults filled in and its ID populated.

For getting objects, we provide two methods - getting an object by its ID and getting objects by a PQL statement. In cases where you might want to get the most recent version of an object quickly, getObject would suffice. Retrieving large sets of information for the user would call for paging through a series of getObjectsByFilter service calls.

The final methods involve mutating objects on our server. The update methods provide a way of performing an object replacement by its ID. A typical workflow for updating an object given user input would resemble the following steps:

Perform a getObjectsByFilter call and present the user with a large set of data.
After the user selects one particular object, perform a getObject call by recalling its ID.
The user modifies the object to update it locally; the ID should not change.
Finally, perform an updateObject call, passing in the full updated object.

Notice that in our general workflow, getObject must be called before the updateObject call so that the most recent version of the object is modified.

The last method, performObjectAction, allows you to specify an action that takes place on the objects selected by the supplied filter. Instead of returning a set of objects to the developer, who would then typically update them, all updates occur server-side. The performObjectAction methods are mostly used to update the workflow of objects, such as approving or activating them.

As we develop new features for the API, we will continue to keep the consistency we have incorporated so far. As always, we look forward to discussing our API with you on our forum.

Introducing Google's DoubleClick For Publishers API

noreply@blogger.com (Admin) — Mon, 22 Feb 2010 08:00:00 -0800

Today, we announced the next generation of our ad serving technology for online publishers, the new DoubleClick for Publishers (DFP) from Google. I am pleased to announce that the new version of DFP comes with a modern API that enables publishers and third-parties to customize and extend the product.

As we mentioned in our Google blog post, for the past few years, we've been investing in a suite of solutions — AdSense, ad-serving technology and the DoubleClick Ad Exchange — to help online publishers make the most money possible from their content, whether they sell advertising through their own sales force directly, through an ad network such as AdSense, or a combination of both. We saw an opportunity to improve these solutions by combining Google's technology and infrastructure with DoubleClick's display advertising and ad serving experience. The new DoubleClick for Publishers is a result of that combination of strengths, as is the API that comes with it.

The new API is available to publishers who use DFP, as well as to third-parties and vendors who would like to build applications on top of DFP. A growing community of developers is already working on sales, order management, workflow and data visualization tools. We've incorporated feedback on the existing DART for Publishers API and believe the new API is a significant step forward. It uses SOAP, a standard and widely-adopted messaging technology that uses HTTP requests to transmit and receive XML data between your client and our servers. This means you can use it with virtually any programming language of your choice. We have a wealth of public documentation available online and there are numerous code samples and client libraries ready for you to download.

To learn more about the new API, there are a few places to get started:

The Google Code site that hosts all of the documentation for the new API:

http://code.google.com/apis/dfp

The Google Groups forum where we provide support and where you can provide feedback to us:

http://groups.google.com/group/google-doubleclick-for-publishers-api/

This blog, which will continue to have posts explaining new API features, discussing best practices for development, and alerting developers of planned outages.

When you are ready to begin development, please sign up to receive access to a sandbox development environment. In this environment, you will be able to explore the API without worrying about affecting your production accounts. API access to production DFP accounts is being rolled out in waves to customers who have used the sandbox environment and will be granted as resources allow. Please start your development effort using the sandbox environment now. You'll be able to contact us when your application is ready to test in the production environment through a new sign-up form that will appear on our online documentation and on our blog.

We are looking forward to working with you and seeing what you build!