Your First App: Prerequisites

Before you can start coding your first client application, there are a few things you need to do, if you haven't done them already.

Create a Google Account and get Search Ads 360 permissions

To use the Search Ads 360 API, you need a Google Account and appropriate permissions granted to that account from Search Ads 360:

  1. If you don't already have a Google Account, create one.

  2. Ask a Search Ads 360 Agency Manager to create a Search Ads 360 user for your Google Account.

    To download reports, you'll need view permission for the advertisers you'll be working with.

    To add or edit conversions, you'll need edit permission for the advertisers you'll be working with. In a shared Floodlight configuration, you need edit permission for each child advertiser you want to upload conversions into. You don't need access to the parent advertiser, nor do you need access to child advertisers that you're not uploading conversions into. If you use click IDs to attribute conversions to visits, make sure you have edit access to the advertiser that generated the click ID. If you specify a click ID from an advertiser you don't have edit access to, the request will not succeed.

    The Agency Manager can set up your account as an Advertiser user with access to specific advertisers, or set up your account with a higher level of access such as Agency user with access to all advertisers in the agency.

Activate the API Conversion Service

If you want to upload data about conversions, a Search Ads 360 user with Agency Manager privileges needs to sign in to the Search Ads 360 UI and activate the API conversion service. See the Search Ads 360 help center for instructions.

Create a Google API Console project and OAuth credentials for your client

  1. Start the Google API Console setup tool.
    The setup tool guides you through creating a project (or using an existing project), enabling the Search Ads 360 API, and creating OAuth 2.0 credentials.
  2. On the Register your application page, select an existing project or select Create a project. Then click Continue.
  3. After the Google API Console enables the Search Ads 360 API, click the Go to credentials button.
  4. On the Create credentials page, enter the following information:
    • Which API are you using?: Search Ads 360 API
    • What data will you be accessing?: User data
  5. Click the Next button.

    The setup tool now offers to help you create an OAuth 2.0 client ID.

  6. Follow the rest of the steps in the setup tool.

Install sa360Api.py

Search Ads 360 provides a utility script to facilitate the process of setting up authorization. You can also use this script to send and receive data in the JSON format, if you want to try sending and receiving data before you design and write a full application. You can copy many of the JSON examples in this documentation site and input them directly to the script.

To install the script:

  1. Install Python 2.7.
    The script does not work with Python 3.x.
  2. Install cURL.
  3. Download sa360Api.zip.
  4. Extract sa360Api.py from sa360Api.zip.
  5. Make sa360Api.py executable.

Learn REST basics

There are two ways to invoke the API:

If you decide not to use client libraries, you'll need to understand the basics of REST.

REST is a style of software architecture that provides a convenient and consistent approach to requesting and modifying data.

The term REST is short for "Representational State Transfer." In the context of Google APIs, it refers to using HTTP verbs to retrieve and modify representations of data stored by Google.

In a RESTful system, resources are stored in a data store; a client sends a request that the server perform a particular action (such as creating, retrieving, updating, or deleting a resource), and the server performs the action and sends a response, often in the form of a representation of the specified resource.

In Google's RESTful APIs, the client specifies an action using an HTTP verb such as POST, GET, PUT, or DELETE. It specifies a resource by a globally-unique URI of the following form:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Because all API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the web's distributed infrastructure.

You may find the method definitions in the HTTP 1.1 standards documentation useful; they include specifications for GET, POST, PUT, and DELETE.

REST in the Search Ads 360 API

The Search Ads 360 API operations map directly to REST HTTP verbs.

The specific format for Search Ads 360 API URIs is:

https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters

The full set of URIs used for each supported operation in the API is summarized in the API Reference.

Learn JSON basics

If you use REST, you'll need to use the JSON format for the request bodies. You can specify that the responses be either in the JSON or CSV format.

JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.