Tag Archives: google_ads_api

REST code examples now available for the Google Ads API

Historically, we have always heard from the Google Ads API developer community that code examples are one of the most useful tools to learn about the API and its features. For a long time, however, our API documentation offered code examples for the Google Ads client libraries, but not for REST. We've heard requests from the community to offer more REST code examples, and so we've been working hard to create and integrate a rich set of REST examples directly into our developer documentation.

Now, alongside client library examples, you'll find corresponding REST examples showing you exactly how to structure your curl commands or equivalent code in your preferred language to perform common operations like:
  • Create customer accounts
  • List accessible accounts
  • Manage recommendations
  • Generate keyword ideas
  • And more!
You can find these examples in relevant sections of the Google Ads API documentation on our developer site. For instance, when you look at the guide for listing accessible accounts, you'll now see a "cURL" tab alongside other language options, providing a clear and concise REST-based example.

At the moment, we've added a small, but substantial, subset of examples. We're adding more soon.

Have ideas for additional REST examples?
You can help us prioritize which examples to add and also help implement them. To request a specific code example, open an issue on the REST code examples GitHub repository. You can also open pull requests to help create new examples, or expand the existing ones. Our team will review your submission, and your contribution could help other Google Ads API users.

We hope this addition of REST examples, driven by your valuable feedback, will significantly improve the development experience for a wide range of Google Ads API users. We're excited to see how these examples help you build even more innovative solutions.
 - Mattia Tommasone, Google Ads API Team

Improved Change Tracking in Google Ads API

Over the next several Google Ads API updates, we'll be adding new types of resources you can track using the ChangeStatus feature.

What this means for you:
  • More detailed tracking: You'll soon be able to better track changes to your Google Ads accounts.
  • Important - Check for UNKNOWN changes: Even in older versions of the API, you might start seeing new change entries. These entries will show up as UNKNOWN resource types because the older versions won’t support the new values.
How to prepare:
  • Handle UNKNOWN: If your app uses ChangeStatus, make sure it can handle entries with a resource type of UNKNOWN. This will prevent errors when the new types are added.
  • Update to the latest API version: Once the new version is released, updating your app will show the correct, specific names of the new change types instead of UNKNOWN.
  • We'll announce the exact new resource types in the release notes when the update is live.
If you have any questions, please ask them in the Google Ads API forum. We're here to help!
- Mike Cloonan, Google Ads API Team

Upcoming changes to CustomerService in Google Ads API

We are introducing several changes to the CustomerService.CreateCustomerClient method to align the Google Ads API with how Google Ads UI handles new account creation functionality. These changes will take effect on March 17, 2025.

New error codes for policy enforcement
In order to limit abuse, the Google Ads API introduced two new error codes in the version v19 of the API for the purpose of policy enforcement.
  1. Google Ads manager accounts that do not have a certain threshold of spending or a certain number of active child accounts without policy issues (for example, not suspended or closed for policy violations) will be ineligible to create child accounts under them. Developers will receive a CustomerError.CREATION_DENIED_INELIGIBLE_MCC error code in the upcoming version v19 of the Google Ads API. To fix the issue, link a Google Ads account that is compliant with the Google policies and meets the threshold spending levels under your manager account.
  2. Google Ads manager accounts that have been flagged for policy violations related to account creation will no longer be able to create child accounts under them. Developers will receive a CustomerError.CREATION_DENIED_FOR_POLICY_VIOLATION error code in the upcoming version v19 of the Google Ads API.
In both these cases, existing API versions (v18 and older) will throw a ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT error instead.

Quota limits for account creation
The Google Ads API will enforce limits on creation of new Google Ads accounts. Developers will receive a QuotaError.RESOURCE_EXHAUSTED error once the limits are reached. The retry_delay field of the quota_error_details contains additional details on how long you should wait before retrying the API call. We do not expect most developers to be affected by these limits.

What do I need to do?
If your application uses the Google Ads API to create new Google Ads accounts, you should review your code to ensure that your application correctly handles these new error codes.

If you have any questions or need help, check out the Google Ads API support page for options.Reach out to the Google Ads product support team for any questions related to account policies.
 - , Google Ads API Team

Announcing v19 of the Google Ads API

Today, we’re announcing the v19 release of the Google Ads API. To use some of the v19 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week.

Here are the highlights:
  • Added support automatically generating enhanced video assets for Performance Max campaigns.
  • Removed all feed-related entities from the Google Ads API like Feed, FeedMapping, FeedService, AdGroupFeed, feed_placeholder_view. Users should now use assets to achieve the same purpose.
  • Demand Gen ads now support 9:16 portrait image assets. Use DemandGenMultiAssetAdInfo.tall_portrait_marketing_images to include these assets in your ads.
  • Added more methods to DataLinkService for updating and removing previously created DataLink for YouTube.
  • ValueRuleItineraryAdvanceBookingWindow now supports targeting for travel searches that take place today.
  • Removed support for VIDEO_OUTSTREAM.
  • (For allowlisted accounts only) Updates to brand guidelines
    • Brand guidelines can now be enabled for Performance Max campaigns during campaign creation. We also added a new CampaignService.EnablePMaxBrandGuidelines which allows you to enable brand guidelines for existing Performance Max campaigns.
    • You can set the brand guidelines’ details such as font family and colors using Campaign.brand_guidelines.
  • (For allowlisted accounts only) Added support for message assets through Asset.business_message_asset.
Where can I learn more?
The following resources can help you get started: If you have any questions or need additional help, contact us via the forum.
 - Thanet Knack Praneenararat, on behalf of the Google Ads API Team

Update to Customer Match membership expiration starting April 7, 2025

Starting on April 7, 2025, a new maximum membership duration of 540 days will gradually roll out for Customer Match lists in Google Ads and Display & Video 360 platforms. This change is being made to better align with Customer Match best practices.

From this date, existing lists configured to have no membership expiration set or membership expiration greater than 540 days will be updated to use the maximum membership duration of 540 days, and a membership duration of 540 days will be retroactively applied to all those existing members that have a longer duration. The reflected list size decreases as memberships expire. Campaigns targeting too small a segment of users can’t serve ads and may automatically pause. Refresh your Customer Match list before April 7, 2025 to renew memberships or replace the expired Customer Match lists with up-to-date lists to ensure that your ad campaigns are not interrupted.

With a set membership duration, you will need to start refreshing your list regularly by re-uploading customer data to your lists. If you do not, the list size will get smaller over time. Refer to this article to learn more about Customer Match.

Required actions for Google Ads API users

Starting on April 7, 2025, requests to set the UserList.membership_life_span field in the Google Ads API to greater than 540 will return a RangeError.TOO_HIGH error. We recommend you check your current implementation to make sure you no longer set the field value to greater than 540.

For existing user lists with membership_life_span field in the Google Ads API greater than 540, starting from April 7, 2025 customer data user lists will be automatically migrated to have a membership life span of the maximum 540 days. If you need to update your code to regularly refresh your customer lists, check out our guide for examples.

No action is required if you do not set the membership_life_span field in the Google Ads API and you regularly refresh your customer lists. Leaving the field unset has the same effect as setting it to the maximum 540 days value.

If you run into issues or have questions about these changes, please contact us using our Google Ads API forum.

Required actions for Display & Video 360 API users

Starting on April 7, 2025, firstAndThirdPartyAudiences.create and firstAndThirdPartyAudiences.patch requests to the Display & Video 360 API that set the membershipDurationDays field to greater than 540 will return a 400 error. Setting the membershipDurationDays field is required when you create a Customer Match list, so we recommend that you check your current implementation to make sure you no longer set the field to a value greater than 540.

From April 7, 2025, existing Customer Match list with a membershipDurationDays field set to a value greater than 540 days will be automatically migrated to a membership duration of the new maximum 540 days. After this date, you will need to regularly refresh your Customer Match list. See our guide for examples on how to update your Customer Match list.

If you run into issues or have questions about these changes, please contact us using our Display & Video 360 API Technical support contact form.

- Da Yang, Google Ads API Team
- Trevor Mulchay, Display & Video 360 API Team

Join the Google Ads API Research Group

We are pleased to announce the launch of the Google Ads API Research Group. As a Developer Relations team, we want to ensure your voice is not only heard, but that your suggestions are incorporated into product decisions. Our goal is to turn your feedback into real improvements to the Google Ads API developer experience.

As a member of the research group, we'll invite you to participate in user research opportunities, such as surveys and usability studies. These opportunities let you voice your opinions and ideas about the Google Ads API, inform product design and prioritization, and ultimately shape the Google Ads API developer experience.

To sign up for the Google Ads API Research Group, fill out the opt-in form. This form takes about 5 minutes to complete. We are deeply committed to improving developer experience and appreciate your feedback.

 - Laura Chevalier, Google Ads API Team

Join the Google Ads API Research Group

We are pleased to announce the launch of the Google Ads API Research Group. As a Developer Relations team, we want to ensure your voice is not only heard, but that your suggestions are incorporated into product decisions. Our goal is to turn your feedback into real improvements to the Google Ads API developer experience.

As a member of the research group, we'll invite you to participate in user research opportunities, such as surveys and usability studies. These opportunities let you voice your opinions and ideas about the Google Ads API, inform product design and prioritization, and ultimately shape the Google Ads API developer experience.

To sign up for the Google Ads API Research Group, fill out the opt-in form. This form takes about 5 minutes to complete. We are deeply committed to improving developer experience and appreciate your feedback.

 - Laura Chevalier, Google Ads API Team

Google Ads API and Google Ads scripts search term insight report update starting March 3, 2025

Starting on March 3, 2025, the Google Ads API and Google Ads scripts search term insight reports will return all search subcategories as empty. The Google Ads UI already removed this field, and the API is also rolling out this change to be consistent across Google Ads.

What do I need to do?

Starting March 3, 2025, it is expected that all values for segments.search_subcategory will be empty.

If you query segments.search_subcategory in the campaign_search_term_insight or customer_search_term_insight reports, then:

  1. Check that your code can handle an empty value in segments.search_subcategory. An empty string already is a catch-all, so your code should be already handling this.
  2. We recommend removing segments.search_subcategory from your query.

If you have any questions or concerns, you can reach out to us through our support form.

Nadine Wang, Google Ads API Team

Google Ads API v16 sunset reminder

Google Ads API v16 will sunset on February 5, 2025. After this date, all v16 API requests will begin to fail. Migrate to a newer version prior to February 5, 2025 to ensure your API access is unaffected.

Here are some resources to help you with the migration: You can view a list of methods and services your project has recently called using the Google Cloud Console:
  1. Open the APIs & Services in the Google Cloud Console.
  2. Click Google Ads API in the table.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. You can see which methods you've sent requests to in the Methods table. The method name includes a Google Ads API version, a service, and a method name, such as google.ads.googleads.v18.services.GoogleAdsService.Mutate.
  4. (Optional) Choose the timeframe you want to view for your requests.
If you have questions while you’re upgrading, reach out to us on the forum or at [email protected].
 - Thanet Knack Praneenararat, Google Ads API Team

Upcoming changes to enable brand guidelines in Performance Max

Starting on January 20, 2025, new Performance Max (PMax) campaigns created with the UI will have brand guidelines enabled and require business name and logo brand assets to be linked at the campaign level rather than the asset group level. Brand guidelines is a new feature that allows you to control how your brand is represented in your Performance Max campaign automated assets or formats.

What this means for API users

New PMax campaigns created in the UI with brand guidelines enabled will automatically link BUSINESS_NAME, LOGO, and LANDSCAPE_LOGO via the CampaignAsset resource rather than by using the AssetGroupAsset resource, which may impact integrations that attempt to report on or update these assets. You can check if brand guidelines are enabled for a PMax campaign by referencing the Campaign.brand_guidelines_enabled field.

As of v18 of the Google Ads API, it is not possible to create brand guidelines-enabled PMax campaigns via the API, which means new campaigns must link BUSINESS_NAME, LOGO, and LANDSCAPE_LOGO assets using the AssetGroupAsset resource. In a future release, you will be able to create and fully manage PMax campaigns with brand guidelines enabled.

It is important to note that the same asset requirements will continue to apply to all PMax campaigns regardless of whether or not brand guidelines are enabled. However, BUSINESS_NAME, LOGO, and LANDSCAPE_LOGO asset requirements will be evaluated at the campaign level for campaigns with brand guidelines enabled and the asset group level for campaigns without brand guidelines enabled. You can reference the relevant section of our Performance Max optimization and troubleshooting guide for more information, and as always, contact our team if you need support.

- Devin Chasanoff, on behalf of the Google Ads API Team