Google Ads Developer Blog: august 2025

Changes for supporting European Union Political Ads Regulation in Display & Video 360 API and Structured Data Files

neljapäev, 21. august 2025

What’s changing? As announced last year, Google will stop serving political advertising in the European Union (EU) ahead of new regulation in October 2025. Starting September 8, 2025, the Display & Video 360 API and Structured Data Files (SDFs) will roll out enforcements related to this change. If you use either of these products to create or manage line items, you may need to update your application to handle these enforcements before September 8, 2025 to avoid an interruption of service. Background Starting September 8, 2025, Display & Video 360 will require self-declaration for EU political ads. You must declare whether a line item will serve EU political ads when creating it. You can also make this declaration for the advertiser as a whole. This declaration will state whether any line items under the advertiser will serve EU political ads. Make the declaration at the advertiser level using the Display & Video 360 API or under the advertiser Basic details settings in the Display & Video 360 UI once it launches after September 8. If you declare that your advertiser won’t serve EU political ads, new line items under that advertiser will use that declaration if another isn’t provided, avoiding an interruption of service. Display & Video 360 API and Structured Data Files have added support for declaring whether a line item serves EU political ads. Similar support for self-declaration will launch in the Display & Video 360 UI starting September 8, 2025. Display & Video 360 API In the Display & Video 360 API, the field containsEuPoliticalAds has been added to the following API objects in v3 and v4 to surface self-declaration at different resource levels:

LineItem objects for getting and setting the declaration at the line item level.

Advertiser for getting and setting the declaration at the advertiser level.

The possible settable values for the field are shown in the table below, with a meaning relevant to the resource to which it is assigned.

Value

Meaning

CONTAINS_EU_POLITICAL_ADVERTISING

The resource will be used to serve EU political ads.

DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING

The resource will not be used to serve EU political ads.

Starting September 8, 2025, Display & Video 360 API will start requiring that the containsEuPoliticalAds field is set for new line item resources or for existing line item resources when updating geography targeting of existing line items. What do I need to do? Every new line item created will need a valid declaration using the field containsEuPoliticalAds. Set the containsEuPoliticalAds field in the Advertiser object using the advertisers.patch method, or set the declaration under the advertiser Basic details settings in the Display & Video 360 UI once it is available. If you set the containsEuPoliticalAds field to DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING for the parent advertiser, new line items will use that value unless another value is set at creation, and the field will be backfilled for existing line items within a day. This field can then be updated using either the UI, API, or Structured Data Files. If your advertiser is not serving EU political ads, declaring at the advertiser level will be a sufficient action to avoid errors. If you can’t declare at the advertiser level or have declared that EU political ads may be served under your advertiser, you must update your use of the following API methods:

Set the containsEuPoliticalAds field in the new line item resource when making an advertisers.lineItems.create request.

Set the containsEuPoliticalAds field in the request body when making advertisers.lineItems.duplicate and advertisers.lineItems.generateDefault requests.

Set the containsEuPoliticalAds field in existing line item resources using an advertisers.lineItems.patch request before updating geography targeting for those line items. Geography targeting includes the following targeting types:

TARGETING_TYPE_GEO_REGION
TARGETING_TYPE_POI
TARGETING_TYPE_BUSINESS_CHAIN
TARGETING_TYPE_REGIONAL_LOCATION_LIST
TARGETING_TYPE_PROXIMITY_LOCATION_LIST

Structured Data Files In Structured Data Files, we have launched v9, which adds the column Contains EU Political Ads to the line item file. This allows for the retrieval and setting of EU political ads declaration at the line item level. This column uses the values YES and NO to represent the line item declaration. With this launch, we are also deprecating SDF v7.1, v8, and v8.1 and recommend that you migrate to v9 your earliest convenience. We will support these versions until we sunset them in March 2026. Starting September 8, 2025, Display & Video 360 will start requiring you to use v9 to upload Structured Data Files and set the Contains EU Political Ads column to YES or NO for new SDF line item entries. If your advertiser has declared that it will not serve EU political ads, you can continue to use previous versions to upload SDFs. What do I need to do? Every new line item created will need a valid declaration using the column Contains EU Political Ads. Set the containsEuPoliticalAds field in the advertiser using the Display & Video 360 API advertisers.patch method, or set the declaration under the advertiser Basic details settings in the Display & Video 360 UI once it is available. If you declare that the advertiser will not serve EU political ads, new line items will use the NO value for the Contains EU Political Ads column unless another value is set at creation, and the field will be backfilled for existing line items within a day. This enables you to use v7, v7.1, v8, or v8.1 for SDF upload. After line item creation, this field can be updated using the UI, API, or Structured Data Files. If you can’t declare at the advertiser level or have declared that EU political ads may be served under your advertiser, do the following before September 8, 2025:

Migrate to using SDF v9. See our migration guide for instructions.

Set the Contains EU Political Ads column to YES or NO in line item entries on SDF upload when:

Creating new line items.
Updating any of the following columns of the existing line item:

Geography Targeting - Include
Geography Targeting - Exclude
Geography Regional Location List Targeting - Include
Geography Regional Location List Targeting - Exclude
Proximity Targeting
Proximity Location List Targeting

Creating new ad groups with set Geography Targeting columns under the existing line item.
Updating the Geography Targeting columns of ad groups under the existing line item.

Also, if you use Structured Data Files at all, make sure to migrate to v9 before all previous versions are sunset in March 2026. How do I get help? Reach out to the Display & Video 360 API support channels if you have more questions about this change.

- Trevor Mulchay, Display & Video 360 API Team

Maximize the performance of your Google Ads conversion data

kolmapäev, 20. august 2025

In today's data-driven world, the performance of your ad campaigns increasingly depends on the richness of the conversion data you import. When it comes to machine learning, the more signals you provide, the better the models can understand user behavior, predict outcomes, and deliver value. For conversion imports specifically, richer data can mean increased observed conversions, and better modelled conversions. For this reason it’s important to make sure that your application is set up to gather, and import, as much conversion data as possible to the Google Ads API. To do that, you may need to make improvements to your existing conversion import pipeline. Why upgrade? We recommend that you upgrade your conversion import pipeline by gathering and importing more than just GCLIDs.

Durability:

Improve conversion attribution, especially when GCLIDs are missing, by incorporating new data points.
Adapt to evolving privacy regulations and the deprecation of traditional tracking identifiers.

Better modeling:

Provide more data to Google's AI for better campaign optimization.
Get a more complete picture of user behavior and improve model reliability.

Steps to upgrade your conversion import pipeline

Update your Google Ads API version:

Move to Google Ads API version v20 or later. See our release notes and migration guides.

Include user-provided data:

Include hashed user-provided data (email, phone number), when available, to unlock cross-device and engaged-view conversions. See our documentation on sending user-provided data.
Important: Set up your application to import all conversions, even if they only have user-provided data and don’t have a GCLID.

Send additional signals:

Capture and import session attributes by using our JavaScript helper function to generate an encoded token (setting session_attributes_encoded), or by capturing the sub-fields individually as key-value pairs (setting session_attributes_key_value_pairs). We recommend using the JavaScript helper function to provide an encoded token; use of key-value pairs is available for users who cannot generate an encoded token in the browser. User's IP address is also available as a new field, though reporting and bidding benefits will become available in the future.
Make sure you provide users with clear and comprehensive information about the data you collect on your sites, apps, and other properties and get consent where required by law or any applicable Google policies.

Adopt Braid (gbraid & wbraid):

Capture and import these URL parameters for privacy-safe conversion reporting when GCLID and user-provided data are unavailable.
Note: We recently announced that gclid and gbraid can be imported together for a single conversion starting on Oct. 3, 2025.

Implement order ID:

Set the order_id field with a unique identifier. This helps reference conversions when adjustments or retractions are needed.

Provide conversion environment:

Set the conversion_environment field to specify whether the conversion source is APP or WEB.
Note: We recently announced that conversion environment data will start informing bidding models for in-app conversions in late September.

Consent and data sharing responsibilities:

Advertisers are responsible for ensuring they have the right to share all data uploaded to Google. Make sure you set the consent field on all imported conversions.

Reach out to the Google Ads API support channel if you have any questions.

- Ben Karl, on behalf of the Google Ads API Team

Google Ads API documentation gets a major upgrade!

neljapäev, 14. august 2025

We're thrilled to announce significant improvements to the Google Ads API documentation, designed to make your development experience smoother, faster, and more intuitive. These changes are a direct result of valuable feedback from our incredible API developer community. Our goal was simple: enhance discoverability and reduce the need to jump between pages, so you can spend less time searching and more time building. Let's dive into what's new: 1. Easier campaign type discovery and implementation One of the most requested features was clearer guidance on supported campaign types. You can now more easily identify which campaign types the API supports and, crucially, find all the resources you need to implement them directly within the documentation. This streamlines your workflow from discovery to deployment.

2. Unified reporting and reference documentation We've merged our Reporting and Reference documentation into a single location. This means all your essential references are now together, providing a more comprehensive and less fragmented experience when you're working with data and API specifics. 3. Seamless gRPC and REST integration For those who switch between gRPC and REST, we've introduced a highly anticipated feature: a one-button toggle!

This lets you effortlessly switch between the two protocols on the same page. If you haven't yet, we highly recommend trying out our Try-it feature directly from the developer site. With gRPC and REST now co-located, accessing Try-it is more efficient than ever, making it perfect for quickly testing new features and requests. 4. Reorganized and clustered guides All your familiar guides are still there, but we've given them a thoughtful re-ordering. Guides with similar features are now clustered together, creating a more logical flow and helping you navigate to related topics more quickly. This thoughtful reorganization aims to reduce friction and enhance your learning. We want your feedback! These changes are just the beginning, and your feedback is crucial as we continue to refine and improve. If you have any thoughts on these updates, or suggestions for future enhancements, please click the Send Feedback button at the bottom of any page in the documentation.

This direct line lets you provide valuable input that will help shape the future of the Google Ads API documentation. We're incredibly excited about these updates and believe they will significantly enhance your experience with the Google Ads API. Happy coding!

- Lois Patterson, Google Ads API Team

Changes for supporting European Union Political Ads Regulation in Google Ads API and Google Ads scripts

neljapäev, 7. august 2025

What’s changing? As announced last year, Google will stop serving political advertising in the European Union ahead of a new regulation taking effect in October 2025. On September 3, 2025, the Google Ads API and Google Ads scripts will roll out enforcements related to this change. If you use either of these products to create or manage campaigns, you may need to update your application to handle these enforcements before September 3, 2025. API support for self-declaration of EU political ads Google Ads API and Google Ads scripts have added support for self-declaration as to whether a campaign has EU political ads. Learn how an EU political ad is defined here. Versions v19.2, v20.1, and v21 of the API contain a new field named contains_eu_political_advertising in the Campaign object. The possible values and their meaning are shown in the table below.

Value

Meaning

CONTAINS_EU_POLITICAL_ADVERTISING

The campaign has EU political ads.

DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING

The campaign does not have EU political ads.

UNSPECIFIED

The campaign is missing self-declaration about EU political ads.

You can retrieve the self-declaration status of a campaign in Google Ads API by running the following query using either the Search or SearchStream methods of the GoogleAdsService. For Google Ads Scripts, use the AdsApp.search or AdsApp.report methods. select campaign.id, campaign.contains_eu_political_advertising from campaign If you use the Google Ads API client libraries, you may need to download the latest library version to use this functionality in versions v19 and v20 of the API. API validation & enforcement changes On September 3, 2025, Google Ads API and Google Ads scripts will start enforcing the following checks in versions v19 and v20 of the API.

All new campaigns created either through Google Ads API or Google Ads scripts should set the contains_eu_political_advertising field. The API call to create a new campaign using CampaignService.MutateCampaigns will fail with a FieldError.REQUIRED error if this field is not set. Google Ads Scripts will enforce these checks when creating campaigns using AdsApp.mutate or AdsApp.mutateAll methods.

All the existing campaigns should set the contains_eu_political_advertising field before attempting to change proximity, location, or location_group targeting either at the campaign or ad group levels. The API call to create or update these campaign criteria using CampaignCriterionService.MutateCampaignCriteria method for existing campaigns will fail with a CriterionError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION error if the campaign hasn’t completed the self-declaration. The API call to create or update these ad group criteria using AdGroupCriterionService.MutateAdGroupCriteria will also fail in a similar manner if the campaign hasn’t completed the self-declaration. Google Ads scripts will enforce these checks when attempting to change targeting using AdsApp.mutate, AdsApp.mutateAll, AdsApp.Campaign.addProximity, and AdsApp.Campaign.addLocation methods.

These enforcements also apply to other mechanisms that you can use to make campaigns, such as running Batch Jobs and using GoogleAdsService.Mutate method to create and update entities.

Attempting to schedule a new experiment using ExperimentService.ScheduleExperiment method will throw an ExperimentError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION error if the contains_eu_political_advertising declaration is missing on the treatment draft campaigns.

If you use the bulk upload feature in Google Ads scripts, check the product documentation to learn more about the spreadsheet template changes required as part of this change.

These checks are already enforced in version v21 of the Google Ads API. How will this affect my campaign serving? Any campaign that has declared EU political ads by setting contains_eu_political_advertising to true will stop serving ads in the EU on September 22, 2025. Refer to our Help Center to learn more. Existing campaigns without a declaration will remain unaffected for now. We recommend updating the existing campaigns in your accounts with an appropriate declaration as soon as possible. You can retrieve campaigns without a declaration using the following GAQL query using either the Search or SearchStream methods of the GoogleAdsService. select campaign.id, campaign.contains_eu_political_advertising from campaign where campaign.contains_eu_political_advertising NOT IN ( 'CONTAINS_EU_POLITICAL_ADVERTISING', 'DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING' ) What do I need to do? If your application uses either Google Ads API or Google Ads scripts to create or manage campaigns, make sure to update your application to handle these enforcements before September 3, 2025. How do I get help? Reach out to the Google Ads API support or Google Ads scripts support channels if you have more questions about this change.

- Anash P. Oommen, Google Ads API Team

Announcing v21 of the Google Ads API

kolmapäev, 6. august 2025

Today, we’re announcing the v21 release of the Google Ads API. To use some of the v21 features, you must upgrade your client libraries and client code. All the updated client libraries and code examples have been published. As previously announced, we are also releasing minor versions v20.1 and v19.2 of the Google Ads API. Here are some of the key features in this release:

We have added a new field named contains_eu_political_advertising for the Campaign object. Use this field to self-declare whether your campaign contains political advertising content targeted towards the European Union. If this field is set to true, the campaign will no longer serve in the EU starting September 23, 2025. This feature is also released in versions v20_1 and v19_2 of the API so you can start using this feature immediately without upgrading to the latest version of the API. See our blog post to learn more.

A new view campaign_search_term_view aggregates search term data at the campaign level and exposes search term data for Performance Max campaigns. We encourage you to migrate from search_term_view to campaign_search_term_view if you are interested in fetching search term data for Performance Max campaigns.

Brand guidelines will automatically be enabled on new campaigns.

You can now use the ai_max_setting.enable_ai_max field of the Campaign object to enable AI Max for Search campaigns. Google Ads AI Max is a suite of AI-powered features for standard Search campaigns designed to increase conversions and reach. It works by using machine learning to expand keyword targeting, dynamically generate ad creatives based on user intent, and send users to the most relevant landing pages on your website. Refer to our blog post to learn more. A new view ai_max_search_term_ad_combination_view exposes search term data for AI Max for Search campaigns. We plan to launch a consolidated version of this view including data from other campaign types in a future API version.

We are allowing Terms & Service, QR codes, and various other barcodes to be added to PromotionAssets.

Where can I learn more? The following resources can help you get started:

Release Notes

Upgrade from a previous version

Guides

Reference

Diff between v21 and v20

If you have any questions or need additional help, contact us via the forum.

- Anash P. Oommen, Google Ads API Team

Unlocking enhanced Performance Max targeting in the Google Ads API

esmaspäev, 4. august 2025

This blog post was updated on August 12, 2025 to add clarification on how to attach a negative keyword list to your campaign. We're excited to announce the launch of three powerful new features for Performance Max campaigns within the Google Ads API. These updates will give you greater control and flexibility over your Performance Max campaigns, allowing for even more precise targeting and optimization. Available today across all supported versions of the Google Ads API, these features empower developers and advertisers to refine their Performance Max strategies. Introducing new targeting capabilities1. Device targeting With the introduction of device targeting, you now have the ability to specify at the campaign level where your Performance Max ads will appear. This feature provides a new layer of control, enabling you to optimize your campaign reach across various platforms. To set up device targeting, add a DeviceInfo criterion to your Performance Max campaign. 2. Negative keyword lists To help prevent your ads from showing for irrelevant searches, we're introducing support for negative keyword lists at the campaign level on Performance Max campaigns. This highly requested feature allows you to upload and apply lists of keywords that you want to exclude, ensuring your ads are displayed to the most relevant audience. You can attach a negative keyword list to your campaign by attaching a SharedSet with the type NEGATIVE_KEYWORDS using the CampaignSharedSetService. Refer to this page for an example on how to attach a negative keyword set to a campaign. 3. Age range exclusions We're also adding the capability to exclude specific age ranges from your Performance Max campaigns. This allows for more granular audience targeting, which helps you comply with age-related advertising regulations and focus your spend on the most appropriate demographics for your products or services. To set up an age range exclusion, add an AgeRangeInfo as a negative criterion on your PMax campaign. How to get started These new features are available starting today on all supported versions of the Google Ads API. For detailed documentation on how to implement these new targeting options in your Performance Max campaigns, refer to our developer guides. We're committed to continually enhancing the Google Ads API to provide you with the tools you need to succeed. We encourage you to explore these new features and incorporate them into your Performance Max strategies to achieve even better results.

- Sarah Pollack, Google Ads API Team

Ads Developer Blog