Get Started

This guide explains how to get started writing applications that use the Ad Exchange Buyer REST API to interact with DoubleClick Ad Exchange. The Ad Exchange Buyer REST API allows your Real-Time Bidding application to access and update account information and to submit creatives. The API also allows an application (whether it does static bidding or real-time bidding) to discover direct deals that sellers make available.

Ad Exchange Buyer REST API v1.4 is the latest and recommended version.

There is also a version 2 of the API containing the latest developments and features, that is currently in open beta.

Before you start

  • Ask your Google account representative to set up proper permissions for accounts your application will access.

    Be sure to get an Account ID from the account representative. You'll need to use this ID when required by the API. You can check for valid Account IDs here.

  • If you're unfamiliar with Ad Exchange Buyer concepts, read the DoubleClick Ad Exchange Help and experiment with the user interface.

Prepare for authorization

Complete the following steps to prepare for authentication using OAuth 2.0. The API supports many types of credentials; for this example we'll use a service account.

  1. Go to the Google API Console Enabled APIs page.
  2. From the project drop-down, select a project or create a new one.
  3. In the list of Enabled APIs, make sure Ad Exchange Buyer API is listed. If it's not listed, click the Google APIs tab, search for and select the Ad Exchange Buyer API, and click Enable API.
  4. Next, in the sidebar on the left select Credentials.
  5. Select the Create credentials drop-down, then choose Service account key.
  6. In the Service account drop-down, choose New service Account.
  7. Enter a Name for the service account. The Service account ID is automatically generated from the name and project name.
  8. Note the service account ID email.
  9. Choose a Key type, either the recommended JSON file, or P12 if backward compatibility with code using P12 format is needed.
  10. Click Create. The JSON or P12 file with the account's public/private key pair is saved to your Downloads folder. Keep the generated JSON or P12 file in a safe place.
  11. For the service account to work you must grant it access in the AdExchange UI. Select Settings > Account Settings, then choose User Management > Account Users, and click +Service Account.

See the Authorization guide for more information.

Make an API call

The tabs below provide quickstarts for coding in each of the languages for which there is a client library.

Java

Here is a basic example that shows how to use the Ad Exchange Buyer REST API with Java.

  1. Create an Eclipse maven project

    Open the pom.xml and add these dependencies:

      <dependencies>
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-adexchangebuyer</artifactId>
          <version>RELEASE</version>
        </dependency>
        <dependency>
          <groupId>com.google.http-client</groupId>
          <artifactId>google-http-client-jackson2</artifactId>
          <version>RELEASE</version>
        </dependency>
      </dependencies>
      

  2. Set up your credentials

    All calls to the API require authentication; create a Credential using the Service Account email and P12 File discussed above.

    Credential oAuth2Credential = new GoogleCredential.Builder()
            .setTransport(httpTransport)
            .setJsonFactory(jsonFactory)
            .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
            .setServiceAccountScopes(AdExchangeBuyerScopes.all())
            .setServiceAccountPrivateKeyFromP12File(P12_FILE)
            .build();
  3. Construct a client for the AdExchangeBuyer

    You can then create your AdExchangeBuyer using the Builder pattern:

    AdExchangeBuyer buyerService = new AdExchangeBuyer.Builder(httpTransport,
            jsonFactory, oAuth2Credential).setApplicationName(APPLICATION_NAME)
            .build();

  4. Perform an operation

    After you've instantiated a client to connect to the API, you can perform an operation. The following code returns all of the Buyer Account associated with your authenticated account.

    List<Account> allAccounts = buyerService.accounts().list()
            .execute().getItems();
    
        if (allAccounts != null && allAccounts.size() > 0) {
          System.out.printf("Listing of user associated accounts%n");
          for (Account account : allAccounts) {
            System.out.printf("Account id: %d%n", account.getId());
          }
        }

For more detailed information about using the Ad Exchange Buyer REST API with Java, refer to the README file in the Ad Exchange Buyer REST API examples.

Python

Here is a basic example that shows how to use the Ad Exchange Buyer REST API with Python.

  1. Download and install the Google API Python Client

    Example using pip:

    $ pip install --upgrade google-api-python-client

  2. Set up your credentials

    All calls to the API require authentication; create credentials using the Service Account email and P12 File discussed above. Use them to authorize a Http object.

      oauth_credentials = client.SignedJwtAssertionCredentials(
          SERVICE_ACCOUNT_EMAIL,
          open(KEY_FILE).read(),
          scope=SCOPE)
    
      # Use the credentials to authorize an Http object
      http = oauth_credentials.authorize(httplib2.Http())
  3. Construct a client for the AdExchangeBuyer

    You can then create your AdExchange Buyer client using the authorized Http object:

    buyer_service = build('adexchangebuyer', VERSION, http=http)

  4. Perform an operation

    After you've instantiated a client to connect to the API, you can perform an operation. The following code returns all of the Buyer Account associated with your authenticated account.

    request = buyer_service.accounts().list()

For more detailed information about using the Ad Exchange Buyer REST API with Python, refer to the README file in the Ad Exchange Buyer REST API examples.

PHP

Here is a basic example that shows how to use the Ad Exchange Buyer REST API with PHP.

  1. Set up dependencies

    Download and install google-api-php-client.

  2. Set up a client

    Create a Google_Client object.

    $client = new Google_Client();
    $client->setApplicationName(
        'DoubleClick Ad Exchange Buyer REST API PHP Samples');
  3. Set up your credentials

    All calls to the API require a valid access token. Obtain one by providing your pre-configured key.

    $service = new Google_Service_AdExchangeBuyer($client);
    
    if (isset($_SESSION['service_token'])) {
        $client->setAccessToken($_SESSION['service_token']);
    }
    
    $client->setAuthConfig($key_file_location);
    $client->addScope('https://www.googleapis.com/auth/adexchange.buyer');
    
    if ($client->isAccessTokenExpired()) {
        $client->refreshTokenWithAssertion();
    }
    
    $_SESSION['service_token'] = $client->getAccessToken();
  4. Construct a client for the AdExchangeBuyer

    You can then create your AdExchange Buyer client using the authorized Google_Client object:

    $service = new Google_Service_AdExchangeBuyer($client);

  5. Perform an operation

    After you've instantiated a client to connect to the API, you can perform an operation. The following code returns all of the Buyer Account associated with your authenticated account.

    $result = $service->accounts->listAccounts();
    
        print '<h2>Listing of user associated accounts</h2>';
        if (! isset($result['items']) || ! count($result['items'])) {
            print '<p>No accounts found</p>';
            return;
        } else {
            foreach ($result['items'] as $account) {
                printf('<pre>');
                print_r($account);
                printf('</pre>');
            }
        }

For more detailed information about using the Ad Exchange Buyer REST API with PHP, refer to the README file in the Ad Exchange Buyer REST API examples.

.NET

Here is a basic example that shows how to use the Ad Exchange Buyer REST API with C#.

  1. Create a new project

    Open Visual Studio and create a new project (i.e., Console Application).

  2. Add required library references to your project

    Either:

    1. Use NuGet to add the latest version of Google.Apis.AdExchangeBuyer and its dependencies.
    2. Download it manually and add a reference to the DLLs. Details on the library can be found here.

  3. Set up your credentials

    All calls to the API require authentication; create a Credential using the Service Account email and JSON File discussed above.

    ServiceAccountCredential oAuth2Credentials = new ServiceAccountCredential(
                    new ServiceAccountCredential.Initializer(
                        credentialParameters.ClientEmail)
                    {
                        Scopes = new[] { AdExchangeBuyerService.Scope.AdexchangeBuyer }
                    }.FromPrivateKey(credentialParameters.PrivateKey));
  4. Construct a client for the AdExchangeBuyer

    You can then create your AdExchangeBuyerService :

    AdExchangeBuyerService buyerService = new AdExchangeBuyerService(
                    new BaseClientService.Initializer
                    {
                        HttpClientInitializer = oAuth2Credentials,
                        ApplicationName = "FirstAPICall"
                    });
  5. Perform an operation

    After you've instantiated a client to connect to the API, you can perform an operation. The following code returns all of the Buyer Account associated with your authenticated account.

    AccountsList allAccounts = buyerService.Accounts.List().Execute();
    
                foreach (Account account in allAccounts.Items)
                {
                    Console.WriteLine("Account id: {0}", account.Id);
                }
    

For more detailed information about using the Ad Exchange Buyer REST API with C#, refer to the README file in the Ad Exchange Buyer REST API examples.

Ruby

Here is a basic example that shows how to use the Ad Exchange Buyer REST API with Ruby.

  1. Download and install the Google API Ruby Client

    Example using gem:

    $ gem install google-api-client
    $ gem update -y google-api-client

  2. Set up your credentials

    All calls to the API require authentication; create credentials using the Service Account email and JSON file discussed above.

    # Create credentials using the JSON key file.
      auth_options = {
        :json_key_io => File.open(KEY_FILE, "r"),
        :scope => "https://www.googleapis.com/auth/adexchange.buyer"
      }
    
      oauth_credentials = Google::Auth::ServiceAccountCredentials.make_creds(
        options=auth_options
      )
  3. Construct a client for the AdExchangeBuyer

    You can then create your authorized AdExchange Buyer client using the credentials:

    # Create the service and set credentials
      ad_exchange_buyer = (
        Google::Apis::AdexchangebuyerV1_4::AdExchangeBuyerService.new
      )
      ad_exchange_buyer.authorization = oauth_credentials
      ad_exchange_buyer.authorization.fetch_access_token!
  4. Perform an operation

    After you've instantiated a client to connect to the API, you can perform an operation. The following code returns all of the Buyer Account associated with your authenticated account.

    # Call the Accounts resource on the service to retrieve a list of
        # Accounts for the service account.
        accounts_list = ad_exchange_buyer.list_accounts()
    
        if accounts_list.items.any?
          puts 'Found the following DoubleClick Ad Exchange Buyer Accounts:'
          accounts_list.items.each do |account|
            puts 'AccountID: %d' % account.id
            puts "\tCookie matching nid: %s" % account.cookie_matching_nid
            puts "\tCookie matching URL: %s" % account.cookie_matching_url
            puts "\tMaximum active creatives: %d" % account.maximum_active_creatives
            puts "\tMaximum total QPS: %d" % account.maximum_total_qps
            puts "\tNumber active creatives: %d" % account.number_active_creatives
            puts "\tBidder Locations:"
            account.bidder_location.each do |bidder_location|
              puts "\t\tURL: %s" % bidder_location.url
              puts "\t\t\tRegion: %s" % bidder_location.region
              puts "\t\t\tBid Protocol: %s" % bidder_location.bid_protocol
              puts "\t\t\tMaximum QPS: %s" % bidder_location.maximum_qps
            end
          end
        else
          puts 'No DoubleClick Ad Exchange Buyer Accounts were found.'
        end

For more detailed information about using the Ad Exchange Buyer REST API with Ruby, refer to the README file in the Ad Exchange Buyer REST API examples.

Make an API call against version 2 open beta

The tabs below provide quickstarts for coding in each of the languages for which there is a client library.

Java

/*
 * Copyright (c) 2016 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.adexchangebuyer.cmdline;

import com.google.api.client.googleapis.services.json.AbstractGoogleJsonClient;
import com.google.api.services.adexchangebuyer2.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer2.v2beta1.model.Client;

import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all client buyers associated with a given account.
 *
 * See the <a href="Client Buyers Guide">https://developers.google.com/ad-exchange/buyer-rest/guides/client-access/clients</a>
 * for more details on the usage of this resource.
 */
public class GetAllClientBuyers extends BaseSample {
  @Override
  public ClientType getClientType() {
    return BaseSample.ClientType.ADEXCHANGEBUYERII;
  }

  @Override
  public String getName() {
    return "Get All Client Buyers";
  }

  @Override
  public String getDescription() {
    return "Lists Client Buyers associated with the given Account.";
  }

  @Override
  public void execute(AbstractGoogleJsonClient client) throws IOException {
    AdExchangeBuyerII adXClient = (AdExchangeBuyerII) client;
    long accountId = getIntInput("AccountId", "Enter the Account ID");
    List<Client> allClients = adXClient.accounts().clients().list(accountId).execute().getClients();

    if (allClients != null && allClients.size() > 0) {
      System.out.printf("========================================\n");
      System.out.printf("Listing of Client Buyers associated with AdX Account \"%s\"%n",
          accountId);
      System.out.printf("========================================\n");
      for (Client clientBuyer : allClients) {
        System.out.printf("Client Account ID: %s%n", clientBuyer.getClientAccountId());
        System.out.printf("\tClient Name: %s%n", clientBuyer.getClientName());
        System.out.printf("\tEntity ID: %s%n", clientBuyer.getEntityId());
        System.out.printf("\tEntity Name: %s%n", clientBuyer.getEntityName());
        System.out.printf("\tEntity Type: %s%n", clientBuyer.getEntityType());
        System.out.printf("\tRole: %s%n", clientBuyer.getRole());
        System.out.printf("\tStatus: %s%n", clientBuyer.getStatus());
      }
    } else {
      System.out.println("No Client Buyers were found associated to this Account.");
    }
  }
}

Python

#!/usr/bin/python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""This example lists the client buyers for a given account."""


import argparse
import pprint
import sys

from apiclient.errors import HttpError
from oauth2client.client import AccessTokenRefreshError
import samples_util


DEFAULT_ACCOUNT_ID = 'ENTER_ACCOUNT_ID_HERE'


def main(ad_exchange_buyer, account_id):
  try:
    # Construct and execute the request.
    clients = ad_exchange_buyer.accounts().clients().list(
        accountId=account_id).execute()
    print 'Client buyers for account ID: %d' % account_id
    pprint.pprint(clients)
  except HttpError as e:
    print e


if __name__ == '__main__':
  parser = argparse.ArgumentParser(
      description='Lists client buyers for a given Ad Exchange account id.')
  parser.add_argument(
      '-a', '--account_id', default=DEFAULT_ACCOUNT_ID, type=int,
      help=('The integer id of the Ad Exchange account.'))
  args = parser.parse_args()

  try:
    service = samples_util.GetService(version='v2beta1')
  except IOError, ex:
    print 'Unable to create adexchangebuyer service - %s' % ex
    print 'Did you specify the key file in samples_util.py?'
    sys.exit()
  except AccessTokenRefreshError, ex:
    print 'Unable to create adexchangebuyer service - %s' % ex
    print 'Did you set the correct Service Account Email in samples_util.py?'
    sys.exit()

  main(service, args.account_id)

PHP

<?php
/*
 * Copyright 2016 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Require the base class.
require_once __DIR__ . "/../BaseExample.php";

/**
 * This example illustrates how to retrieve all buyer clients associated
 * with a given account.
 */
class ListClientBuyers extends BaseExample
{

    /**
     *
     * @see BaseExample::getInputParameters()
     */
    protected function getInputParameters()
    {
        return array(
            array(
                'name' => 'account_id',
                'display' => 'Account id',
                'required' => true
            )
        );
    }

    /**
     *
     * @see BaseExample::run()
     */
    public function run()
    {
        $values = $this->formValues;
        $result = $this->service->accounts_clients->listAccountsClients(
            $values['account_id']);
        print '<h2>Listing buyer clients</h2>';
        if (! isset($result['clients']) || ! count($result['clients'])) {
            print '<p>No buyer clients found</p>';
            return;
        } else {
            foreach ($result['clients'] as $clients) {
                $this->printResult($clients);
            }
        }
    }

    /**
     *
     * @see BaseExample::getClientType()
     */
    function getClientType()
    {
        return ClientType::AdExchangeBuyerII;
    }

    /**
     *
     * @see BaseExample::getName()
     */
    public function getName()
    {
        return 'Client Access: List Client Buyers';
    }
}

.NET

/* Copyright 2016, Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

using Google.Apis.AdExchangeBuyerII.v2beta1;
using Google.Apis.AdExchangeBuyerII.v2beta1.Data;
using Google.Apis.Services;

using System;

namespace Google.Apis.AdExchangeBuyer.Examples.v2_x
{
    /// <summary>
    /// Retrieves the authenticated user's list of client buyers for the given
    /// account ID.
    /// </summary>
    public class ListClientBuyers : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments</param>
        public static void Main(string[] args)
        {
            AdExchangeBuyerIIService service = Utilities.GetV2Service();
            ExampleBase example = new ListClientBuyers();
            Console.WriteLine(example.Description);

            example.Run(service);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get { return "This code example lists all client buyers for a "
                    + "given account ID."; }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="service">An authenticated AdExchangeBuyerIIService</param>
        public override void Run(BaseClientService service)
        {
            AdExchangeBuyerIIService adXService =
                (AdExchangeBuyerIIService)service;
            long accountId = long.Parse("INSERT ACCOUNT ID HERE");

            ListClientsResponse response = adXService.Accounts.Clients
                .List(accountId).Execute();

            Console.WriteLine("========================================\n");
            Console.WriteLine("Listing of client buyers associated with AdX "
                + "Account \"{0}\"", accountId);
            Console.WriteLine("========================================\n");

            if (response.Clients.Count == 0)
            {
                Console.WriteLine("No client buyers found.");
            } else
            {
                foreach (Client clientBuyer in response.Clients)
                {
                    Console.WriteLine("Client Account ID: {0}", clientBuyer.ClientAccountId);
                    Console.WriteLine("\tClient Name: {0}", clientBuyer.ClientName);
                    Console.WriteLine("\tEntity ID: {0}", clientBuyer.EntityId);
                    Console.WriteLine("\tEntity Name: {0}", clientBuyer.EntityName);
                    Console.WriteLine("\tEntity Type: {0}", clientBuyer.EntityType);
                    Console.WriteLine("\tRole: {0}", clientBuyer.Role);
                    Console.WriteLine("\tStatus: {0}", clientBuyer.Status);
                }
            }
        }

        public override ClientType getClientType()
        {
            return ClientType.ADEXCHANGEBUYERII;
        }
    }
}

Ruby

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# Lists the client buyers for a given account.
#
# To get Account IDs, run list_accounts.rb.
#
# Tags: Accounts.Clients.list

require 'optparse'

require_relative 'samples_util'


def list_client_buyers(ad_exchange_buyer, account_id, page_size)
  begin
    client_buyers = ad_exchange_buyer.list_account_clients(
      account_id, page_size: page_size
    )

    if !client_buyers.clients.nil?
      puts 'Found the following client buyers for account ID %s:' % account_id
      client_buyers.clients.each do |client_buyer|
        puts '* Client account ID: %s' % client_buyer.client_account_id
        puts "\tClient name: %s" % client_buyer.client_name
        puts "\tEntity ID: %s" % client_buyer.entity_id
        puts "\tEntity name: %s" % client_buyer.entity_name
        puts "\tEntity Type: %s" % client_buyer.entity_type
        puts "\tRole: %s" % client_buyer.role
        puts "\tStatus: %s" % client_buyer.status
        puts "\tVisible to seller: %s" % client_buyer.visible_to_seller
      end
    else
      puts 'No client buyers found for account ID %s.' % account_id
    end

  rescue Google::Apis::ServerError => e
    puts "The following server error occured:\n%s" % e.message
  rescue Google::Apis::ClientError => e
    puts "Invalid client request:\n%s" % e.message
  rescue Google::Apis::AuthorizationError => e
    puts "Authorization error occured:\n%s" % e.message
  end
end


if __FILE__ == $0
  begin
    # Retrieve the service used to make API requests.
    service = get_service(version=ADEXCHANGEBUYER_V2BETA1)
  rescue ArgumentError => e
    puts 'Unable to create service: %s' % e.message
    puts 'Did you specify the key file in util.rb?'
    exit
  rescue Signet::AuthorizationError => e
    puts e.message
    puts 'Did you set the correct Service Account Email in samples_util.rb?'
    exit
  end

  # Set options and default values for fields used in this example.
  options = [
    Option.new(
      'account_id', 'The integer ID of the Ad Exchange buyer account.',
      :type => Integer, :short_alias => 'a', :required => true,
      :default_value => nil  # Insert default value here.
    ),
    Option.new(
      'max_page_size',
      'The maximum number of entries returned on one result page.',
      :type => Integer, :short_alias => 'm', :required => true,
      :default_value => MAX_PAGE_SIZE
    )
  ]

  # Parse options.
  parser = Parser.new(options)
  opts = parser.parse(ARGV)

  list_client_buyers(service, opts['account_id'], opts['page_size'])
end

Next steps

  • Read the background guide to more fully understand what is happening in the samples and the options available to you in developing your solution.
  • When you have got a client library up and running, try extending the code examples to meet your needs.
  • Visit the reference documentation for the version you are working with to learn more about the API.
  • If you need help, visit the Forum.
  • If your application is expected to perform real-time bidding, read the Ad Exchange RTB Protocol documentation.
  • Read the Performance Tips.

Take a survey

Help us improve this documentation; tell us what worked and what we missed by filling out a quick survey.

Send feedback about...

Buyer REST API
Buyer REST API