Background

Before you start

  1. Ask your account representative to set up proper permissions for accounts your application will access.
  2. If you're unfamiliar with Ad Exchange Buyer concepts, read the DoubleClick Ad Exchange Help and experiment with the user interface. If your application is expected to perform real-time bidding, read the Ad Exchange RTB Protocol documentation.
  3. Visit the APIs Console to set up a new project. Either sign into your developer Google account or create an account. You will then be prompted to create a project and sign off on a couple of Terms of Service.

Parent and child accounts

If you're working within an account structure containing parent and child accounts, you may be able to work more effectively if you understand how they interact. The following is a brief summary:

Child accounts

A user with credentials that grant access to a child account can only view and modify resources associated with their account. Child accounts can't view or modify resources belonging to other child or parent accounts.

Parent accounts

A user with credentials that grant access to a parent account can view and modify resources for the parent account in addition to all associated child accounts. For operations listing all of a given resource, this user will receive a response including data for their account and all of their child accounts. Note that for other types of requests, the parent account will need to specify an accountId for the child account being modified as part of the API request rather than the parent accountId.

The REST API data model

A resource is an individual data entity with a unique identifier. The Accounts resource represents an Ad Exchange buyer account entry, and is the root data class for the Ad Exchange Buyer REST API. The API's methods operate on individual Accounts resources, and on collections of Accounts resources.

An Accounts Resource includes: an Account ID, information used in cookie matching, bidder locations, the URL to which Ad Exchange sends bid requests, and a request to specify the maximum queries per second to be sent by the Ad Exchange.

In addition to the Accounts resource and collection, the Ad Exchange Buyer REST API defines the following data structures:

Bidder location

Bidder locations are structures that are returned with Accounts Resources to provide the URL to which the Ad Exchange should send bid requests and the maximum number of queries per second the Ad Exchange should send. Here is an example of a bidder location, expressed in JSON:

"bidderLocation": [
    {
      "url": "http://bid.url.com/bidder",
      "maximumQps": 1500
    }
  ],

Items

Items provide a list of accounts. Here is an example of items, expressed in JSON:

{
  "kind": "adexchangebuyer#accountsList",
  "items": [
    accounts Resource
  ]
}

Supported operations

You can invoke three different methods on collections and resources in the Ad Exchange Buyer REST API as described in the following table. All operations require authorization.

Operation Description REST HTTP mappings
list Lists all accounts that can be accessed by the currently authenticated user. GET on a collection URI.
get Gets a specific Accounts resource. GET on a resource URI.
update Updates a specific Accounts resource. PUT on a resource URI, where you pass in data for the updated resource.

Calling style

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.

For more information about REST, you may find the following third-party documents useful:

REST in the Ad Exchange Buyer REST API

The supported operations map directly to REST HTTP verbs, as described in API operations.

The specific format for API URIs are:

https://www.googleapis.com/adexchangebuyer/v1.4/resourceID?parameters

where resourceID is the identifier for an Accounts resource, and parameters are any parameters to apply to the query. See standard query parameters and the reference documentation for details.

The format of the resourceID path extensions lets you identify the resource you're currently operating on, for example:

https://www.googleapis.com/adexchangebuyer/v1.4/accounts
https://www.googleapis.com/adexchangebuyer/v1.4/accounts/id

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

Here's an example of how this works in the Ad Exchange Buyer API.

Get the authenticated user's list of accounts:

GET https://www.googleapis.com/adexchangebuyer/v1.4/accounts

Data format

JSON

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.

Send feedback about...

Buyer REST API
Buyer REST API