Service and type getters

  • The client's get_service and get_type methods are used to retrieve any service or type object in the API respectively.

  • Using the get_service and get_type methods is a best practice over direct imports due to potential changes in the codebase structure.

  • Enums can be retrieved using get_type or more simply through the enums attribute of a GoogleAdsClient instance.

  • Proto object fields that are enums are represented in Python by the native enum type, allowing access to both value and name.

  • You can specify the API version when initializing the client or when calling get_service and get_type methods, with method calls overriding the client's version.

Fetching references to all the various proto classes required to use the API in Python can be verbose and requires you to have an intrinsic understanding of the API or frequently context-switch to reference the protos or documentation.

The client's get_service and get_type methods

These two getter methods allow you to retrieve any service or type object in the API. The get_service method is used to retrieve service clients. get_type is used for any other object. Service client classes are defined in code under the version path google/ads/googleads/v*/services/ and all types are defined under the various object categories google/ads/googleads/v*/common|enums|errors|resources|services/types/. All code underneath the version directory is generated, so it's a best practice to use these methods instead of importing the objects directly, in case the structure of the codebase changes.

The following example shows how to use the get_service method to retrieve an instance of the GoogleAdsService client (or an asynchronous GoogleAdsServiceAsyncClient in google-ads v28.4.0 and later by passing is_async=True):

from google.ads.googleads.client import GoogleAdsClient

# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Providing the optional `version`
# parameter means that the v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
googleads_service = client.get_service("GoogleAdsService")

# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)

The following example shows how to use the get_type method to retrieve a Campaign instance:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")

Enums

While you can use the get_type method to retrieve enums, each GoogleAdsClient instance also has an enums attribute that dynamically loads enums using the same mechanism as the get_type method. This interface is simpler and easier to read than using get_type:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v25")

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED

Proto object fields that are enums are represented in Python by the built-in enum type. That means that you can read the value of the member directly. Working with the campaign instance from the previous example in a Python REPL:

>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3

Sometimes it's useful to know the name of the field that corresponds to the enum value. You can access this information using the name attribute:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

Interacting with enums is different depending on whether you have the use_proto_plus configuration set to true or false. For details on the two interfaces, see the protobuf messages documentation.

Versioning

Multiple versions of the API are maintained at the same time. While v25 is the latest version, earlier versions are still accessible until they are sunset. The library includes separate proto message classes that correspond to each active API version. To access a message class for a specific version, supply the version keyword parameter when initializing a client so that it always returns an instance from that given version:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 version of the API.
campaign = client.get_type("Campaign")

If you don't specify a version when initializing the client, you can specify the version per call when calling the get_service and get_type methods (note that if version is set when initializing GoogleAdsClient, it overrides any version argument passed to get_service or get_type):

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()
# This loads the v25 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v25"
)

# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")

If no version keyword parameter is provided, the library defaults to the highest API version supported by your installed google-ads package ("v25" in the latest release). Note that minor API releases (such as v25.1) are accessed using their major version string (version="v25"). An updated list of the latest and other available versions can be found in the left-hand navigation section of the API Reference documentation.