Ad Exchange Buyer APIs

There are currently two Ad Exchange Buyer API versions: Version 1, and the new version 2 that is currently in open beta.

Version 1 allows you to:

• Access real-time bidding account information
• Submit creatives for verification
• Check the status of a submitted creative
• Retrieve performance reports
• Retrieve pretargeting configurations

Version 2 will eventually replace version 1. It's currently used to configure Client Access for Marketplace.

Overview

This guide explains how to get started writing applications that use the Ad Exchange Buyer API to interact with Authorized Buyers. The Ad Exchange Buyer 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 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.

If you're unfamiliar with Authorized Buyers concepts, visit the Authorized Buyers Help Center and experiment with the UI.

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: you'll need it to grant access to the new service account in the Authorized Buyers UI in step 11.
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. You must grant the service account access in the Authorized Buyers UI for it to work. Select Settings > Account Settings, then choose User Management > Account Users, and click +Service Account. Enter the service account ID you noted above in step 8. This creates a new user with the service account role.

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 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());
         }
       }
   FirstApiRequest.java

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

Python

Here is a basic example that shows how to use the Ad Exchange Buyer 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.

     credentials = service_account.Credentials.from_service_account_file(
         KEY_FILE, scopes=[SCOPE])

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, credentials=credentials)

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()
   first_api_request.py

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

PHP

Here is a basic example that shows how to use the Ad Exchange Buyer 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(
       'Authorized Buyers Ad Exchange Buyer 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($keyFileLocation);
   $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 (empty($result['items'])) {
       print '<p>No accounts found</p>';
       return;
     } else {
       foreach ($result['items'] as $account) {
         printf('<pre>');
         print_r($account);
         printf('</pre>');
       }
     }
   FirstApiRequest.php

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

.NET

Here is a basic example that shows how to use the Ad Exchange Buyer 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);
               }
   FirstApiRequest.cs

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

Ruby

Here is a basic example that shows how to use the Ad Exchange Buyer 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 Authorized Buyers 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
           unless account.bidder_location.nil?
             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
         end
       else
         puts 'No Authorized Buyers Accounts were found.'
       end
   first_api_request.rb

For more detailed information about using the Ad Exchange Buyer API with Ruby, refer to the README file in the Ad Exchange Buyer 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.v2_x;

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 com.google.api.services.samples.adexchangebuyer.cmdline.BaseSample;
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 Access Guide">https://developers.google.com/authorized-buyers/apis/guides/v2/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.println("========================================");
      System.out.printf("Listing of Client Buyers associated with AdX Account \"%s\"%n",
          accountId);
      System.out.println("========================================");
      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 os
import sys

sys.path.insert(0, os.path.abspath('..'))

from googleapiclient.errors import HttpError
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(f'Client buyers for account ID: "{account_id}"')
    pprint.pprint(clients)
  except HttpError as e:
    print(e)


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

  try:
    service = samples_util.GetService('v2beta1')
  except IOError as ex:
    print(f'Unable to create adexchangebuyer service - {ex}')
    print('Did you specify the key file in samples_util.py?')
    sys.exit(1)

  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_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 [
        [
            'name' => 'accountId',
            'display' => 'Account ID',
            'required' => true
        ]
    ];
  }

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

  /**
   * @see BaseExample::getClientType()
   */
  public 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 Authorized Buyers " +
                "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
    raise "The following server error occured:\n%s" % e.message
  rescue Google::Apis::ClientError => e
    raise "Invalid client request:\n%s" % e.message
  rescue Google::Apis::AuthorizationError => e
    raise "Authorization error occured:\n%s" % e.message
  end
end


if __FILE__ == $0
  begin
    # Retrieve the service used to make API requests.
    service = get_service(ADEXCHANGEBUYER_V2BETA1)
  rescue ArgumentError => e
    raise 'Unable to create service, with error message: %s' % e.message
  rescue Signet::AuthorizationError => e
    raise ('Unable to create service, was the KEY_FILE in samples_util.rb ' +
           'set? Error message: %s') % e.message
  end

  # Set options and default values for fields used in this example.
  options = [
    Option.new(
      'account_id', 'The integer ID of the Authorized Buyers 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 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.