Get started with the Search Ads 360 Reporting API

The following sections describe how to get started with the Search Ads 360 Reporting API.

Set up your project on Google Cloud

To use the Search Ads 360 Reporting API you need to create a project for your application on Google Cloud.

Create a Google project

A Google project serves as a resource container for your Google Cloud resources.

1. Go to the Google API Console.
2. Click Create project.
3. Enter a name or accept the generated suggestion.
4. Confirm or edit any remaining fields.
5. Click Create.

Create OAuth2 credentials

The Search Ads 360 Reporting API uses OAuth 2.0 for authentication and authorization. OAuth credentials identify your app to Google, and allow you to generate OAuth tokens for managing Search Ads 360 users.

To create an OAuth 2.0 credential in the Google API Console, do the following:

1. Go to the Credentials page.
2. Click Create credentials > OAuth client ID
3. Select your application type.
4. Fill in the form and click Create.

Warning: Any Google Cloud app used to obtain credentials for the Search Ads 360 Reporting scope needs Google OAuth verification. Verification avoids the unverified UI screen displaying to users on login.

Enable the Search Ads 360 Reporting API

To use the API, you must enable Search Ads 360 Reporting API for your project in the Google API Console.

To enable an API for your project:

1. Open the API Library in the Google API Console.
2. If prompted, select a project, or create a new one. The API Library lists all available APIs, grouped by product family and popularity.
3. If the API you want to enable isn't visible in the list, use search to find it, or click View All in the product family it belongs to.
4. Select the API you want to enable, then click the Enable button.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Optionally enable billing for your project

There is no charge for using the Search Ads 360 Reporting API in Google Cloud. There is, however, a quota for the total number of free Cloud projects for each account. If you have reached your limit, you can sign up for a new Google account that will include a free project quota.

Note: If you already have billing enabled (for example, for Google Cloud), you must select a billing account for your project.

To enable billing for your project:

1. Visit the Billing page.
2. If you don't have an active billing account, create one by clicking Add billing account and following the instructions.

Enable your project's consent screen

To enable your project's consent screen:

1. Open the Consent Screen page in the Google API Console.
2. If prompted, select a project, or create a new one.
3. Fill out the form and click Save.

Create, edit, or view redirect URI(s)

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

1. Go to the Credentials page.
2. In the OAuth 2.0 client IDs section of the page, click a credential.
3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Download a client library

Using a Search Ads 360 Reporting API client library is the recommended way to connect to the Search Ads 360 Reporting API.

Download the Search Ads 360 Reporting API client library for your development environment. Follow the language-specific instructions on how to set up your client library configuration file. In most cases, you can reuse your existing configuration when migrating to the new Search Ads 360 Reporting API client library.

One important change is the new login-customer-id header. See Login customer ID header for details about when you need to add this to your configuration.

Make your first call

Once you've configured your client library, you can make your first call.

Get Campaigns

In your IDE, execute the following code:

Java

// Copyright 2022 Google LLC
//
// 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
//
//     https://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 sample;

import com.beust.jcommander.Parameter;
import com.google.ads.searchads360.v0.lib.SearchAds360Client;
import com.google.ads.searchads360.v0.services.SearchAds360Row;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse;
import com.google.ads.searchads360.v0.services.SearchSearchAds360Request;

/** Get campaign details. */
public class GetCampaigns {
  private static final int PAGE_SIZE = 200;

  private static class GetCampaignsParams extends CodeSampleParams {

    @Parameter(names = "--customerId", required = true)
    private String customerId;

    @Parameter(names = "--loginCustomerId")
    private String loginCustomerId;
  }

  public static void main(String[] args) {
    GetCampaignsParams params = new GetCampaignsParams();
    if (!params.parseArguments(args)) {
      // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId
      // here (10 digits, no dashes). If neither are set, customerId will be used as
      // loginCustomerId.
      // params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE");
    }
    final String loginCustomerId = params.loginCustomerId;
    final String customerId = params.customerId;

    try {
      // Creates a SearchAds360Client with the specified loginCustomerId. If there's
      // no loginCustomerId, customerId will be used instead.
      final SearchAds360Client searchAds360Client =
          SearchAds360Client.newBuilder()
              .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)
              .fromPropertiesFile()
              .build();
      // Creates the Search Ads 360 Service client.
      SearchAds360ServiceClient client = searchAds360Client.create();
      new GetCampaigns().runExample(client, customerId);
    } catch (Exception exception) {
      System.err.printf("Failed with exception: %s%n", exception);
      exception.printStackTrace();
      System.exit(1);
    }
  }

  private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {
    // Creates a query that retrieves all campaigns under the customerId.
    String query = "SELECT campaign.name, campaign.id, campaign.status FROM campaign";
    SearchSearchAds360Request request =
        SearchSearchAds360Request.newBuilder()
            .setCustomerId(customerId)
            .setQuery(query)
            .setPageSize(PAGE_SIZE)
            .build();

    // Issues a search request.
    final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request);
    for (SearchAds360Row element : searchPagedResponse.iterateAll()) {
      System.out.printf(
          "Campaign found with name '%s', ID %d, and status: %s.%n",
          element.getCampaign().getName(),
          element.getCampaign().getId(),
          element.getCampaign().getStatus());
    }
  }
}

Download GetCampaigns.java

Python

#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# 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
#
#     https://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.
"""Retrieves campaigns for a customer using a pagination search request."""

import argparse
import traceback
from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request
from util_searchads360 import SearchAds360Client

_DEFAULT_PAGE_SIZE = 10000


def main(client, customer_id, page_size) -> None:
  search_ads_360_service = client.get_service()

  query = """
      SELECT
        campaign.name,
        campaign.id,
        campaign.status
      FROM campaign"""

  request = SearchSearchAds360Request()
  request.customer_id = customer_id
  request.query = query
  request.page_size = page_size

  # Issues a search request.
  results = search_ads_360_service.search(request=request)

  for row in results:
    campaign = row.campaign
    print(
        f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}'
    )


if __name__ == "__main__":
  # SearchAds360Client will read the search-ads-360.yaml configuration file in
  # the home directory if none is specified.
  search_ads_360_client = SearchAds360Client.load_from_file()

  parser = argparse.ArgumentParser(
      description=("Retrieves campaigns for a customer."))
  # Arguments to provide to run the example.
  parser.add_argument(
      "-c",
      "--customer_id",
      type=str,
      required=True,
      help="The Search Ads 360 customer ID (10 digits, no dashes).",
  )

  parser.add_argument(
      "-l",
      "--login_customer_id",
      type=str,
      required=False,
      help="The Search Ads 360 login customer ID (10 digits, no dashes).",
  )

  args = parser.parse_args()

  search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)

  try:
    main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE)
  except Exception:  # pylint: disable=broad-except
    traceback.print_exc()

Download get_campaigns.py

The console should print a listing of the campaigns in your account.

Use REST

If you decide not to use a client library, you need to understand how to use REST.

If you used REST with the old Search Ads 360 API, your credentials will still work with the new Search Ads 360 Reporting API. Find the new endpoint and other details in the REST reference section.

Learn more

Learn more about the Search Ads 360 Reporting API

• Queries:

  • Search Ads 360 Query Language
  • Create search reports
  • Retrieve metadata

• Concepts:

  • Search Ads 360 Reporting API structure
  • Search Ads 360 Reporting API call structure
  • Versioning in the Search Ads 360 Reporting API
  • Client libraries for the Search Ads 360 Reporting API