Resource Metadata

AI-generated Key Takeaways

outlined_flag

• GoogleAdsFieldService allows dynamic requests for catalog information about resources, fields, segmentation keys, and metrics available in GoogleAdsService Search and SearchStream methods.

• The catalog provides metadata used by Google Ads API clients for validating and constructing Google Ads Query Language statements.

• You can request the catalog using GoogleAdsFieldService at the levels of Resource, Resource's field, Segmentation field, and Metric.

• The example response shows important arrays like attributeResources, metrics, segments, and selectableWith that provide information about joinable resources, available metrics, segment keys, and selectable fields.

You can use GoogleAdsFieldService to dynamically request the catalog for resources, resource's fields, segmentation keys and metrics available in the GoogleAdsService Search and SearchStream methods. The catalog provides metadata that can be used by Google Ads API clients for validation and construction of Google Ads Query Language statements.

Sample HTTP request and response

The request consists of an HTTP GET to the Google Ads API server at the following URL:

https://googleads.googleapis.com/v22/googleAdsFields/{resource_or_field}

The following example shows a request followed by the response returned from GoogleAdsFieldService for the ad_group resource:

Request

https://googleads.googleapis.com/v22/googleAdsFields/ad_group

Response

{
  "resourceName": "googleAdsFields/ad_group",
  "name": "ad_group",
  "category": "RESOURCE",
  "selectable": false,
  "filterable": false,
  "sortable": false,
  "selectableWith": [
    "campaign",
    "customer",
    "metrics.average_cpc",
    "segments.device",
    ...
  ],
  "attributeResources": [
    "customer",
    "campaign"
  ],

  "metrics": [
    "metrics.conversions",
    "metrics.search_budget_lost_impression_share",
    "metrics.average_cost",
    "metrics.clicks",
    ...
  ],
  "segments": [
    "segments.date",
    "segments.ad_network_type",
    "segments.device",
    ...
  ]
}

For this example, the important arrays are:

attributeResources

Resources that can be implicitly joined to the resource in the FROM clause.

metrics

Metrics that are available to be selected with the resource in the FROM clause. Only populated for fields where the category is RESOURCE.

segments

Segment keys that can be selected with the resource in the FROM clause. These segment the metrics specified in the query. Only populated for fields where the category is RESOURCE.

selectableWith

The selectableWith attribute on a resource or segment field specifies other resources, segments, or metrics that can be selected in the same GAQL query. This attribute is crucial when you want to include fields from a resource or segment that is not specified in the FROM clause.

When constructing a GAQL query:

1.  The resource in the FROM clause is the primary entity. You can always select fields from this resource.
2.  You can also select compatible metrics and segments that are available with the primary entity.
3.  If you include fields from any resource or segment outside of the FROM clause, you must ensure that this non-FROM resource or segment is compatible with all other fields, segments, and metrics that are selected in the query.

The selectableWith list for a specific resource (let's call it Resource A) contains all the other resources, segments, and metrics that can be selected alongside fields from Resource A when Resource A is not the primary entity.

Example:

Consider this example query: SELECT ad_group.id, segments.date, campaign.name FROM ad_group

•   The FROM clause specifies ad_group.

•   This query selects ad_group.id (from the FROM resource), segments.date, and campaign.name.

•   Because campaign.name is selected, but campaign is not in the FROM clause, you must verify its compatibility with other selected elements.

•   To ensure this query is valid, the campaign resource must be compatible with segments.date (another field being selected). Therefore, you must check the selectableWith attribute for the campaign resource. If segments.date is present in campaign's selectableWith list, the query is valid.

If you select fields from a resource that is not in the FROM clause, that resource's selectableWith list must include all other segments and resources present in your SELECT clause.

Metadata details

You can request the catalog using the GoogleAdsFieldService at these levels:

Resource

For example, googleAdsFields/campaign.

Resource's field

For example, googleAdsFields/campaign.name.

Segmentation field

For example, googleAdsFields/segments.ad_network_type.

Metric

For example, googleAdsFields/metrics.clicks.