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:
- InsertPretargetingConfig.cs (CSharp)
- InsertPretargetingConfig.java (Java)
- insert_pretargeting_config.py (Python)
- InsertPretargetingConfig.php (PHP)
- insert_pretargeting_config.rb (Ruby)
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"] }