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/v17/googleAdsFields/{resource_or_field}
The following is an example of a request followed by the response returned from
GoogleAdsFieldService
for ad_group resource:
Request
https://googleads.googleapis.com/v17/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 thecategory
isRESOURCE
. 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 thecategory
isRESOURCE
. selectableWith
-
- Fields that can be selected alongside a given field, when not in the
FROM
clause. This attribute is only relevant when identifying resources or segments that are able to be selected in a query where they are not included by the resource in theFROM
clause. As an example, if we are selectingad_group.id
andsegments.date
fromad_group
, and we want to include attributes fromcampaign
, we would need to check thatsegments.date
is in theselectableWith
attribute for campaign, since it's being selected alongside the existingsegments.date
field.
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
.