Pretargeting

To ensure that Google sends you the most appropriate impression calls, you must "pre-target" impressions so that Google will only send requests for impressions that match the targeting criterion you are looking for. That targeting criteria is set up through the PretargetingConfig resource and acts as a filter for the bid requests which will be sent to your bidder.

The Buyer REST API v1.4 provides the PretargetingConfig resource to:

List pretargeting configurations.
Get a particular pretargeting configuration.
Insert a new pretargeting configuration.
Delete a pretargeting configuration.
Update a pretargeting configuration.
Patch a pretargeting configuration.

The Examples illustrate the use of the PretargetingConfig resource.

List pretargeting configurations

Use the list method to retrieve a list of the authenticated user's pretargeting configurations.

Retrieve the list by sending an HTTP GET request to the Pretargeting Resource URI. The URI has the following format:

GET https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId

Request

GET https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789&key={YOUR_API_KEY}

Response

If successful, this method returns a list of PretargetingConfig resource in the response body:

{
  "items": [
    {
      "configId": "1232",
      "kind": "adexchangebuyer#pretargetingConfig",
      "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
      "configName": "PretargetOne",
      "isActive": True,
      "dimensions": [{"width": "728", "height": "90"}]
    }, {
      "configId": "1233",
      "kind": "adexchangebuyer#pretargetingConfig",
      "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
      "configName": "PretargetTwo",
      "isActive": True,
      "dimensions": [{"width": "160", "height": "600"}]
    }
  ],
  "kind": "adexchangebuyer#pretargetingConfigList"
}

Get a particular pretargeting configuration

You can request a particular pretargeting configuration by sending an HTTP GET request to the Pretargeting Resource URI. The URI has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId/configId

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789/1234&key={YOUR_API_KEY}

Response

If successful, the server responds with a PretargetingConfig resource in the response body.

{
  "configId": "1234",
  "kind": "adexchangebuyer#pretargetingConfig",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "configName": "NewPretargetingConfig",
  "isActive": True,
  "dimensions": [{"width": "300", "height": "250"}]
}

Insert new pretargeting configuration

To submit a new pretargeting configuration send an HTTP POST request to the Pretargeting Resource URI, which has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789&key={YOUR_API_KEY}
Content-Type: application/json
{
  "configName": 'NewPretargetingConfig',
  "priority" : 1,
  "isActive": True,
  "creativeType" : ["PRETARGETING_CREATIVE_TYPE_HTML"]
  "dimensions": [{"width": 300, "height": 250}]
}

Response

If successful, the server responds with a PretargetingConfig resource in the response body. In addition to the request fields the response includes the new configId.

{
  "configId": "1234",
  "kind": "adexchangebuyer#pretargetingConfig",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "configName": "NewPretargetingConfig",
  "isActive": True,
  "dimensions": [{"width": "300", "height": "250"}]
}

When you insert a new pretargeting configuration with this API, the API creates a Campaign, an AdGroup, and a Budget that you can access through the Budgets resource.

See the following code samples that use client libraries to insert a pretargeting configuration:

Delete pretargeting configuration

You can delete a particular pretargeting configuration by sending an HTTP DELETE request to the Pretargeting Resource URI. The URI has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId/configId

Request

DELETE https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789/1234&key={YOUR_API_KEY}
Authorization: Bearer /* auth token here */
Content-Type: application/json

Response

If the request succeeds, the server responds with a 200 OK status code.

Update pretargeting configuration

To update and fully replace an existing PretargetingConfig resource:

Retrieve the resource that you want to update.
Modify the properties you want to change.
Send a PUT request to the resource URI and supply the modified resource as the message body.

The URI for the PretargetingConfig Resource has the following format:

https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId/configId

Note: The configId property must be included in the body of the request or the update will fail.

Request

Here is an example of an update request (the final step above) that updates and fully replaces a PretargetingConfig resource:

PUT https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789/1234
Authorization: /* auth token here */
Content-Type: application/json
{
  "configId": "1234",
  "kind": "adexchangebuyer#pretargetingConfig",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "configName": "NewPretargetingConfig",
  "isActive": True,
  "dimensions": [{"width": "336", "height": "280"}]
}

Response

If successful, the server responds with an updated PretargetingConfig resource in the response body.

{
  "configId": "1234",
  "kind": "adexchangebuyer#pretargetingConfig",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "configName": "NewPretargetingConfig",
  "isActive": True,
  "dimensions": [{"width": "336", "height": "280"}]
}

Patch pretargeting configuration

This method of updating pretargeting configurations allows you to specify a delta update for an existing config.

To patch a PretargetingConfig Resource send a PATCH request to the following URI and include the updates in the body of the request:

https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/accountId/configId

Note: The configId property is read-only. If you try to update it you will receive an error.

Request

Here is an example of a PATCH request that updates the dimensions of a config.

PATCH https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789/1234
Authorization: /* auth token here */
Content-Type: application/json
{
  "dimensions": [{"width": 336, "height": 280}]
}

Response

If successful, the server responds with an updated PretargetingConfig resource in the response body.

{
  "configId": "1234",
  "kind": "adexchangebuyer#pretargetingConfig",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "configName": "NewPretargetingConfig",
  "isActive": True,
  "dimensions": [{"width": "336", "height": "280"}]
}

Examples

Sample 1

Create a new PretargetingConfig to target all display inventory in the United States and Canada, where the ad size is 300x250, 336x280, 728x90 or 160x600.

Getting criteria IDs

Download a copy of geo-table.csv containing the geoCriteriaIds.

In the CSV, search for the countries "United States" and "Canada" to get the geoCriteriaIds: 2840 and 2124, respectively.

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789&key={YOUR_API_KEY}
Content-Type: application/json
{
  "configName": "Test config: US and Canada",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "isActive": true,
  "geoCriteriaIds": ["2840", "2124"],
  "dimensions": [
    {"height": "250", "width": "300"},
    {"height": "280", "width": "336"},
    {"height": "90", "width": "728"},
    {"height": "600", "width": "160"}
  ]
}

Response

{
  "kind": "adexchangebuyer#pretargetingConfig",
  "configId": "1235",
  "configName": "Test config: US and Canada",
  "isActive": true,
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "dimensions": [
    {"height": "250", "width": "300"},
    {"height": "280", "width": "336"},
    {"height": "90", "width": "728"},
    {"height": "600", "width": "160"}
  ],
  "geoCriteriaIds": ["2840", "2124"]
}

Sample 2

Modify a PretargetingConfig to only include inventory where the language is English, and where the ad is being shown on mobile web or in-app. Here we're refining the previous sample to make a more precise targeting; e.g., rather than just US and Canada, we're targeting users in US and Canada who speak English and are using mobile platforms. With greater precision comes a lower overall number of bid requests because you are filtering out requests that do not match the criteria you are setting.

In this sample we use the update approach. We could also have used the patch methodology.

Request

PUT https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789&key={YOUR_API_KEY}
Content-Type: application/json
{
  "configId": "1235",
  "configName": "Test config: US and Canada",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "isActive": true,
  "geoCriteriaIds": ["2840", "2124"],
  "dimensions": [
    {"height": "250", "width": "300"},
    {"height": "280", "width": "336"},
    {"height": "90", "width": "728"},
    {"height": "600", "width": "160"}
  ],
  "languages": [ "en" ],
  "platform": ["PRETARGETING_PLATFORM_MOBILE", "PRETARGETING_PLATFORM_TABLET"]
}

Response

{
  "kind": "adexchangebuyer#pretargetingConfig",
  "configId": "1235",
  "configName": "Test config: US and Canada",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_HTML"],
  "isActive": true,
  "geoCriteriaIds": ["2840", "2124"],
  "dimensions": [
    {"height": "250", "width": "300"},
    {"height": "280", "width": "336"},
    {"height": "90", "width": "728"},
    {"height": "600", "width": "160"}
  ],
  "languages": [ "en" ],
  "platform": ["PRETARGETING_PLATFORM_MOBILE", "PRETARGETING_PLATFORM_TABLET"]
}

Sample 3

Create a new PretargetingConfig to target all skippable video inventory worldwide excluding China and Japan, where the ad is being shown on desktop, and where the user is included in any of three remarketing lists (list1, list2, list3).

There is no mechanism to target skippable video inventory exclusively. If you declare that your inventory is entirely skippable it will be filtered from requests that don't allow it. We need to set supportedCreativeAttributes; you can find details on the options for this field here and the value for "Skippable Instream Video" is 44.

Getting criteria IDs

Download a copy of geo-table.csv if you haven't already.

In the CSV, search for the countries "China" and "Japan" to get the geoCriteriaIds: 2156 and 2392, respectively.

Request

POST https://www.googleapis.com/adexchangebuyer/v1.4/pretargetingconfigs/123456789&key={YOUR_API_KEY}
Content-Type: application/json
  "configName": "Skippable Video Test Config",
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_VIDEO"],
  "isActive": true,
  "supportedCreativeAttributes": ["44"],
  "excludedGeoCriteriaIds": ["2156", "2392"],
  "userLists": ["123456", "456789", "789123"],
  "platform": ["PRETARGETING_PLATFORM_DESKTOP"]
}

Response

{
  "kind": "adexchangebuyer#pretargetingConfig",
  "configId": "1236",
  "configName": "Skippable Video test config",
  "isActive": true,
  "creativeType": ["PRETARGETING_CREATIVE_TYPE_VIDEO"],
  "supportedCreativeAttributes": ["44"],
  "excludedGeoCriteriaIds": ["2156", "2392"],
  "userLists": ["123456", "456789", "789123"],
  "platform": ["PRETARGETING_PLATFORM_DESKTOP"]
}