Google Ad Manager Key-Values:
The Definitive Guide to Limits & API

Understanding the Types: Predefined vs Free-form

Google Ad Manager provides two types of targeting keys. The distinction affects how values are inserted via the API and how they surface in reports:

• Predefined: You must declare all possible values in the GAM console or via API beforehand. Typical example: gender=female,male,other. Best used when targeting values are static. These values map cleanly to reporting dimensions.
• Free-form: You define the key (e.g., search_term), but values are created dynamically when requests hit GAM from the browser tags. Typical example: keywords=running-shoes. Essential for high-cardinality dynamic data.

Critical Technical Limits You Must Know

The Google Ad Manager API throws blocking exceptions or silently truncates parameters if you violate these hard rules:

Recommended Key-Values by Inventory Type

To effectively target direct and programmatic ad campaigns, here are the essential key-values to configure based on your business model:

Simplifying Key-Values via the OrbiAds MCP Plugin

You no longer need to navigate the heavy GAM interface to configure targeting keys or values. The OrbiAds MCP plugin exposes direct writing tools for your AI agents or local scripts.

Step 1: Create the targeting key

# In Claude — OrbiAds MCP plugin
create_custom_targeting_key(
  name="pos",
  display_name="Position sur la page",
  key_type="PREDEFINED",
  reportable_type="ON",
  dry_run=false
)

Step 2: Add values to a predefined key:

# Append values to the targeting key (ID returned from Step 1)
create_custom_targeting_values(
  key_id="12984572",
  values=[
    {"name": "atf", "displayName": "Above the Fold"},
    {"name": "btf", "displayName": "Below the Fold"}
  ],
  dry_run=false
)

Visualizing with the Admin explorer tool

For logged-in users, OrbiAds provides a visual dashboard to inspect all active custom targeting keys and values at:

This explorer reads active configs dynamically, counts value instances, and displays predefined values in a tag list format to avoid spelling errors before launching campaigns.

Integration Code: From SOAP API to Client-side GPT

Here is how to create a targeting key programmatically using the Python SDK, and then implement targeting in the web browser using Google Publisher Tag (GPT).

1. Creating Key-Values in Python (SOAP SDK)

from googleads import ad_manager

# Initialiser le client Ad Manager
client = ad_manager.AdManagerClient.LoadFromStorage()
custom_targeting_service = client.GetService(
    'CustomTargetingService', version='v202602'
)

# Déclarer une clé de ciblage "freeform"
key = {
    'name': 'consent_status',
    'displayName': 'Consent status (GDPR)',
    'type': 'FREEFORM'
}

keys = custom_targeting_service.createCustomTargetingKeys([key])
print(f"Clé créée avec l'ID: {keys[0]['id']}")

2. Client-side targeting (JavaScript GPT)

Once configured on the server, append targeting coordinates inside the page headers:

window.googletag = window.googletag || { cmd: [] };
window.googletag.cmd.push(function () {
  // Ciblage au niveau de la page entière
  window.googletag.pubads().setTargeting('section', 'tech');
  window.googletag.pubads().setTargeting('consent', '1');

  // Ciblage spécifique sur un slot publicitaire particulier
  window.googletag.defineSlot('/1234/site/banner', [300, 250], 'div-gpt-ad')
    .setTargeting('pos', 'atf')
    .addService(window.googletag.pubads());
});

Robustness Best Practices

• Lowercasing in GPT: GPT automatically converts targeted values to lowercase in ad requests. Avoid injecting uppercase strings through the API to prevent targeting match failures.
• API Throttling: Modifying large volumes of targeting values over SOAP triggers QuotaError.EXCEEDED_QUOTA exceptions. Implement client-side exponential backoff of at least 500ms between batch requests.

Start Automating Your Targeting Structures

Leverage the OrbiAds MCP plugin to inspect and populate targeting parameters in seconds. Synchronize all your advertising properties with a few instructions.