Search Ads 360 Reporting API structure

The primary components of the Search Ads 360 Reporting API are resources and services. A resource represents a Search Ads 360 entity and you use a service to retrieve Search Ads 360 entities.

Object hierarchy

A Search Ads 360 account is a hierarchy of objects.

  • The top-level resource of an account is the customer.

  • Each account contains one or more active campaigns.

  • Each Campaign contains one or more ad groups that group your ads into logical collections.

  • Each AdGroup contains one or more ad group ads.

  • You can attach one or more AdGroupCriterion or CampaignCriterion to an ad group or campaign. Criteria define how ads are triggered.

    • There are many criterion types, such as, keywords, age ranges, and locations. Criteria defined at the campaign level affect all other resources within the campaign. You can also specify campaign-wide budgets and dates.

Resources

Resources represent the entities in your Search Ads 360 account. Example resources include Customer, Campaign and AdGroup.

Object IDs

Every object in Search Ads 360 is identified by its own ID. Some IDs are globally unique, that is, across all Search Ads 360 accounts, while others are unique only within a confined scope.

Object ID uniqueness scope
Budget ID Global
Campaign ID Global
AdGroup ID Global
Ad ID Ad Group

Each AdGroupId / AdId pair is globally unique.
AdGroupCriterion ID Ad Group

Each AdGroupId / CriterionId pair is globally unique.
CampaignCriterion ID Campaign

Each CampaignId / CriterionId pair is globally unique.
Ad Extensions Campaign

Each CampaignId / AdExtensionId pair is globally unique.
Feed ID Global
Feed Item ID Global
Feed Attribute ID Feed
Feed Mapping ID Global
Label ID Global
UserList ID Global

These ID rules can be useful when designing local storage for your Search Ads 360 objects.

Object types

Some objects can be used for multiple entity types. If this is the case, the object contains a type field that describes its contents. For example, AdGroupAd can refer to a text ad, hotel ad, or local ad. You can access the type value through the AdGroupAd.ad.type field. Its value is returned in the AdType enum.

Resource names

Each resource is uniquely identified by a resource_name string that concatenates the resource and its parents into a path.

Campaign resource names, for example, have the form:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

A campaign with ID 987654 in the Search Ads 360 account with customer ID 1234567, has the resource_name:

customers/1234567/campaigns/987654

Services

Services let you retrieve your Search Ads 360 entities and metadata. There a three service types:

Search service
SearchAds360Service is the single, unified service for retrieving all resource objects and performance statistics. It provides two methods: Search and SearchStream. Both methods require require a query that specifies the resource to query, the resource attributes and performance metrics to retrieve, the predicates to use for filtering the request, and the segments to use to further break down performance statistics. See Create search reports and Search Ads 360 Query Language for more information.
Field service
SearchAds360FieldService retrieves metadata about resources, such as, the available attributes for a resource and its data type. You can request the catalog for resources, resource fields, segmentation keys, and metrics available in the SearchAds360Service search methods. See Retrieve resource metadata to learn more.
Entity-specific services

These services provide a GET request method that retrieves a single resource instance. This is useful for examining the structure of a resource.

Examples of entity-specific services include: