Get started with the Full Circle Query API

This guide explains how to get started writing applications that use the Full Circle Query REST API to interact with Ads Data Hub. The Full Circle Query REST API allows you to view Ads Data Hub customers associated with your Google account, create queries, and run queries.

Before you start

To gain access to the Full Circle Query v2 API, you must contact the Ads Data Hub support. They'll help you configure your Ads Data Hub account and Google Cloud Project.

Client libraries and samples

The Google API client libraries are available in several popular languages, and allow you to work with many Google APIs. Because the Full Circle Query v2 API is a non-public API, some modifications may be necessary for the client libraries to access it.

All samples in this guide include instructions, and any supplemental files necessary to access the API.

Client Library Full Circle Query v2 samples
Google API Client Library for Java Java
Google API Client Library for PHP PHP
Google API Client Library for Python Python

OAuth 2.0 setup

The API supports both the installed application and web application flows, but for this example we’ll step through the installed application flow.

  1. Go to the Google API Console Enabled APIs page.
  2. From the project drop-down, select a Google Cloud project you intend to use with the Full Circle Query REST API, or create a new one.
  3. Verify that Full Circle Query API is in the list of enabled APIs and services. If not, click ENABLE APIS AND SERVICES to search for, and enable it. If it can’t be found, contact the Ads Data Hub support team to help configure your project.
  4. In the sidebar on the left, click Credentials.
  5. Select the Create credentials drop-down, then choose OAuth client ID. On the next page, select an Application type of Other. Optionally, enter a customized name for this client ID, then click Create. You will then be redirected to the Credentials page.
  6. Under OAuth 2.0 client IDs, find the client ID that you just created, and then click the associated download icon to download the JSON client secrets file. You can use this file to step through the installed application OAuth 2.0 flow and access the Full Circle Query v2 REST API.

Make an API call

Java

      /*
 * Copyright (c) 2017 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.fullcirclequery.cmdline;

import com.google.api.services.fullcirclequery.v2.FullCircleQuery;
import com.google.api.services.fullcirclequery.v2.model.Customer;
import com.google.api.services.fullcirclequery.v2.model.ListCustomersResponse;
import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all accounts associated to the user.
 *
 * See the <a href="customers.list reference documentation">https://developers.google.com/ads-data-hub/reference/rest/v2/customers/list</a>
 * for more details.
 */
public class ListCustomers extends BaseSample {

  @Override
  public String getName() {
    return "List customers";
  }

  @Override
  public String getDescription() {
    return "Lists customers associated with the authorized user";
  }

  @Override
  public void execute(FullCircleQuery client) throws IOException {
    ListCustomersResponse response = client.customers().list().execute();
    Boolean isAdmin = response.getIsAdmin();
    List<Customer> customers = response.getCustomers();

    System.out.printf("Authorized user's administrator status: %b\n\n", isAdmin);

    if (customers != null && customers.size() > 0) {
      System.out.println("========================================");
      System.out.printf("Listing of customers associated with the authorized user:\n");
      System.out.println("========================================");
      for (Customer customer : customers) {
        System.out.printf("* Customer id: %d\n", customer.getCustomerId());
        System.out.printf("\tCustomer name: %s\n", customer.getCustomerName());
      }
    } else {
      System.out.println("No customers were found associated with the authorized user.");
    }
  }
}

      

PHP

<?php
/**
 * Copyright 2018 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__ . '/../src/BaseExample.php';

/**
 * This example illustrates how to retrieve all Full Circle Query customers
 * associated with the authorized user.
 */
class ListCustomers extends BaseExample {

  /**
   * @see BaseExample::run()
   */
  public function run() {
    $result = $this->service->customers->listCustomers();

    print '<p>Listing of customers associated with authorized user:</p>';
    if (empty($result['customers'])) {
      print '<p>No customers found</p>';
      return;
    } else {
      foreach ($result['customers'] as $customer) {
        $this->printResult($customer);
      }
    }
  }

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


        

Python

#!/usr/bin/python
#
# Copyright 2017 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 examples lists Ads Data Hub customers for the authenticated user."""

import pprint
import sys

from googleapiclient.errors import HttpError
import samples_util


def main(full_circle_query):
  try:
    # Execute the request.
    response = full_circle_query.customers().list().execute()
  except HttpError as e:
    print e
    sys.exit(1)

  if 'customers' in response:
    print 'Found the following Ads Data Hub customers for the current user:'
    for customer in response['customers']:
      pprint.pprint(customer)
  else:
    print 'No customers found for current user.'


if __name__ == '__main__':
  try:
    service = samples_util.GetService()
  except IOError, ex:
    print 'Unable to create ads data hub service - %s' % ex
    print 'Did you specify the client secrets file in samples_util.py?'
    sys.exit(1)

  main(service)

Next steps

  • See sample queries in Ads Data Hub for examples of queries you can create and run with the Full Circle Query v2 REST API.
  • Expand on the samples to familiarize yourself with the API and customize it for your use case. Then try to:
  • Contact ADH support if you have questions or feedback about the API.