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

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:

Getting Started with the API: Sandbox Environment

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

Getting Started with the API: The Web Services

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.

Introducing Google's DoubleClick For Publishers API

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!