Resource metadata

Page Summary

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 (through GetGoogleAdsField or SearchGoogleAdsFields) to dynamically request the catalog of resources, resource 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/v25/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/v25/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 without segmenting metrics. Only populated for fields where the category is RESOURCE.
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 (segments.* fields and segmenting resources) 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: Resources, segments, or metrics that can be selected in the same Google Ads Query Language query when this resource or segment is not the primary resource in the FROM clause.

Query compatibility with selectableWith

The selectableWith attribute on a resource or segment field specifies other resources, segments, or metrics that can be selected in the same Google Ads Query Language 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 Google Ads Query Language query:

The resource in the FROM clause is the primary entity. You can always select fields from this resource.
You can also select compatible metrics and segments that are available with the primary entity.
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 (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 GoogleAdsFieldService (either by resource name with GetGoogleAdsField or by querying with SearchGoogleAdsFields) at these GoogleAdsFieldCategory levels:

Resource (RESOURCE): For example, googleAdsFields/campaign.
Resource attribute (ATTRIBUTE): For example, googleAdsFields/campaign.name.
Segmentation field (SEGMENT): For example, googleAdsFields/segments.ad_network_type.
Metric (METRIC): For example, googleAdsFields/metrics.clicks.

Retrieving objects

Call structure