Share your feedback about the Google Ads (AdWords) API. Take the 2021 AdWords API and Google Ads API Annual Survey.

The AdWords API will sunset on April 27, 2022. Migrate to the Google Ads API to take advantage of the latest Google Ads features.

Miscellaneous Samples

The code samples below provide examples of miscellaneous management functions available in the AdWords API. Client Library.

Get all image assets

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2018 Google LLC
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This code example gets all image assets. To upload an image asset,
# run upload_image_asset.rb.

require 'adwords_api'

def get_all_image_assets()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  asset_srv = adwords.service(:AssetService, API_VERSION)

  # Create the selector and filter for image assets only.
  selector = {
    :fields => ['AssetName', 'AssetStatus', 'ImageFileSize', 'ImageWidth',
        'ImageHeight', 'ImageFullSizeUrl'],
    :predicates => [
        {:field => 'AssetSubtype', :operator => 'IN', :values => ['IMAGE']}
    ],
    :paging => {
        :start_index => 0,
        :number_results => PAGE_SIZE
    }
  }

  # Set initial values.
  offset, page = 0, {}

  begin
    # Get the image assets.
    page = asset_srv.get(selector)

    # Display the results
    if page[:entries]
      page[:entries].each_with_index do |entry, i|
        full_dimensions = entry[:full_size_info]
        puts ('%s) Image asset with id = "%s", name = "%s" ' +
            'and status = "%s" was found.') %
            [i+1, entry[:asset_id], entry[:asset_name], entry[:asset_status]]
        puts '  Size is %sx%s and asset URL is %s.' %
            [full_dimensions[:image_width],
            full_dimensions[:image_height],
            full_dimensions[:image_url]]
      end
      # Increment values to request the next page.
      offset += PAGE_SIZE
      selector[:paging][:start_index] = offset
    end
  end while page[:total_num_entries] > offset

  if page.include?(:total_num_entries)
    puts "\tFound %d entries." % page[:total_num_entries]
  end
end

if __FILE__ == $0
  API_VERSION = :v201809
  PAGE_SIZE = 500

  begin
    get_all_image_assets()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Get all images and videos

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This code example gets all videos and images. Use the Google Ads website to
# upload new videos. To upload an image, run upload_image.rb.

require 'adwords_api'

def get_all_images_and_videos()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  media_srv = adwords.service(:MediaService, API_VERSION)

  # Get all the images and videos.
  selector = {
    :fields => ['MediaId', 'Height', 'Width', 'MimeType', 'Urls'],
    :ordering => [
      {:field => 'MediaId', :sort_order => 'ASCENDING'}
    ],
    :predicates => [
      {:field => 'Type', :operator => 'IN', :values => ['IMAGE', 'VIDEO']}
    ],
    :paging => {
      :start_index => 0,
      :number_results => PAGE_SIZE
    }
  }

  # Set initial values.
  offset, page = 0, {}

  begin
    page = media_srv.get(selector)
    if page[:entries]
      page[:entries].each do |entry|
        full_dimensions = entry[:dimensions]['FULL']
        puts "Entry ID %d with dimensions %dx%d and MIME type is '%s'" %
            [entry[:media_id], full_dimensions[:height],
             full_dimensions[:width], entry[:mime_type]]
      end
      # Increment values to request the next page.
      offset += PAGE_SIZE
      selector[:paging][:start_index] = offset
    end
  end while page[:total_num_entries] > offset

  if page.include?(:total_num_entries)
    puts "\tFound %d entries." % page[:total_num_entries]
  end
end

if __FILE__ == $0
  API_VERSION = :v201809
  PAGE_SIZE = 500

  begin
    get_all_images_and_videos()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Upload an image

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example uploads an image. To get images, run get_all_images.rb.

require 'adwords_api'
require 'base64'

def upload_image()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  media_srv = adwords.service(:MediaService, API_VERSION)

  # This utility method retrieves the contents of a URL using all of the config
  # options provided to the Api object.
  image_url = 'https://goo.gl/3b9Wfh'
  image_data = AdsCommon::Http.get(image_url, adwords.config)
  base64_image_data = Base64.encode64(image_data)

  # Create image.
  image = {
    # The 'xsi_type' field allows you to specify the xsi:type of the object
    # being created. It's only necessary when you must provide an explicit
    # type that the client library can't infer.
    :xsi_type => 'Image',
    :data => base64_image_data,
    :type => 'IMAGE'
  }

  # Upload image.
  response = media_srv.upload([image])
  if response and !response.empty?
    ret_image = response.first
    full_dimensions = ret_image[:dimensions]['FULL']
    puts ("Image with ID %d, dimensions %dx%d and MIME type '%s' uploaded " +
        "successfully.") % [ret_image[:media_id], full_dimensions[:height],
         full_dimensions[:width], ret_image[:mime_type]]
  else
    puts 'No images uploaded.'
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    upload_image()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Upload an image asset

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2018 Google LLC
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This code example uploads an image asset. To get images,
# run get_all_image_assets.rb.

require 'adwords_api'

def upload_image_asset()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  asset_srv = adwords.service(:AssetService, API_VERSION)

  # The image needs to be in a BASE64 encoded form
  image_url = 'https://goo.gl/3b9Wfh'
  image_data = AdsCommon::Http.get(image_url, adwords.config)
  image_data_base64 = Base64.encode64(image_data)

  # Create the image asset.
  image_asset = {
    :xsi_type => 'ImageAsset',
    # Optional: Provide a unique friendly name to identify your asset. If you
    # specify the assetName field, then both the asset name and the image being
    # uploaded should be unique, and should not match another ACTIVE asset in
    # this customer account.
    # :asset_name => 'Jupiter Trip %s' % (Time.new.to_f * 1000).to_i,
    :image_data => image_data_base64
  }

  # Create the operation.
  asset_operation = {:operator => 'ADD', :operand => image_asset}

  begin
    # Make the mutate request.
    response = asset_srv.mutate([asset_operation])

    # Display the results
    if response and response[:value]
      uploaded_asset = response[:value].first
      puts 'Image asset with id = "%s" and name = "%s" was created.' %
          [uploaded_asset[:asset_id], uploaded_asset[:asset_name]]
    else
      puts 'No image asset was created.'
    end
  rescue Exception => e
    puts 'Failed to create image asset.'
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    upload_image_asset()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

Upload an HTML5 zip file as a MediaBundle

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2015, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
#           you may not use this file except in compliance with the License.
#           You may obtain a copy of the License at
#
#           http://www.apache.org/licenses/LICENSE-2.0
#
#           Unless required by applicable law or agreed to in writing, software
#           distributed under the License is distributed on an "AS IS" BASIS,
#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
#           implied.
#           See the License for the specific language governing permissions and
#           limitations under the License.
#
# This example uploads an HTML5 zip file.

require 'adwords_api'
require 'base64'

def upload_media_bundle()
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  media_srv = adwords.service(:MediaService, API_VERSION)

  # Create HTML5 media.
  html5_url = 'https://goo.gl/9Y7qI2'
  # This utility method retrieves the contents of a URL using all of the config
  # options provided to the Api object.
  html5_data = AdsCommon::Http.get(html5_url, adwords.config)
  base64_html5_data = Base64.encode64(html5_data)
  media_bundle = {
    :xsi_type => 'MediaBundle',
    :data => base64_html5_data,
    :type => 'MEDIA_BUNDLE'
  }

  # Upload HTML5 zip.
  response = media_srv.upload([media_bundle])
  if response and !response.empty?
    ret_html5 = response.first
    full_dimensions = ret_html5[:dimensions]['FULL']
    puts ("HTML5 media with ID %d, dimensions %dx%d and MIME type '%s' " +
        "uploaded successfully.") % [ret_html5[:media_id],
        full_dimensions[:height], full_dimensions[:width],
        ret_html5[:mime_type]]
  else
    puts 'No HTML5 zip was uploaded.'
  end
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    upload_media_bundle()

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end