Cookbook kueri

Panduan ini menyediakan serangkaian kueri Bahasa Kueri Google Ads yang menunjukkan cara menampilkan data yang sama seperti layar di UI Google Ads, serta cara mencari konstanta geografis. Anda dapat menggunakan kueri ini apa adanya, atau sebagai titik awal untuk membuat kueri kustom Anda sendiri.

Untuk mengetahui tabel ringkasan istilah UI umum dan laporan standar yang dipetakan ke resource API, lihat Laporan di UI Google Ads.

Catatan: Anda dapat menggunakan Ekstensi Pelaporan Google Ads API untuk mengidentifikasi resource dan kolom API langsung dalam UI Google Ads, dan alat Pembuat Kueri Interaktif untuk memvalidasi dan membuat prototipe kueri secara interaktif. Tab curl menunjukkan penggunaan langsung antarmuka REST API; lihat halaman search panduan REST untuk mengetahui detail tambahan.

Mereplikasi layar UI Google Ads

Bagian ini menampilkan kueri API yang menampilkan data yang sama dengan layar default UI Google Ads. Jika Anda membuat aplikasi yang menampilkan metrik dan data yang mirip dengan Google Ads, kueri ini dapat membantu Anda mengambil data yang serupa dari API.

Catatan: Kecuali dinyatakan lain, semua kueri bertanggal dalam panduan ini secara default menampilkan data dari tujuh hari terakhir.

Kampanye

Mengambil data dari layar Ringkasan kampanye default di UI Google Ads.

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

Grup iklan

Mengambil data dari layar ringkasan Grup iklan default di UI Google Ads.

GAQL

SELECT ad_group.name,
  campaign.name,
  ad_group.status,
  ad_group.type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM ad_group
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group.status != 'REMOVED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group.name,
    campaign.name,
    ad_group.status,
    ad_group.type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM ad_group
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group.status != 'REMOVED'
"
}'

Iklan

Mengambil data dari layar ringkasan Iklan default di UI Google Ads. Kueri ini mengambil setiap komponen iklan, yang dirender bersama oleh UI di kolom Ad.

GAQL

SELECT ad_group_ad.ad.expanded_text_ad.headline_part1,
  ad_group_ad.ad.expanded_text_ad.headline_part2,
  ad_group_ad.ad.expanded_text_ad.headline_part3,
  ad_group_ad.ad.final_urls,
  ad_group_ad.ad.expanded_text_ad.description,
  ad_group_ad.ad.expanded_text_ad.description2,
  campaign.name,
  ad_group.name,
  ad_group_ad.policy_summary.approval_status,
  ad_group_ad.ad.type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM ad_group_ad
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group_ad.status != 'REMOVED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_ad.ad.expanded_text_ad.headline_part1,
    ad_group_ad.ad.expanded_text_ad.headline_part2,
    ad_group_ad.ad.expanded_text_ad.headline_part3,
    ad_group_ad.ad.final_urls,
    ad_group_ad.ad.expanded_text_ad.description,
    ad_group_ad.ad.expanded_text_ad.description2,
    campaign.name,
    ad_group.name,
    ad_group_ad.policy_summary.approval_status,
    ad_group_ad.ad.type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM ad_group_ad
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group_ad.status != 'REMOVED'
"
}'

Kata kunci penelusuran

Mengambil data dari layar ringkasan Kata kunci penelusuran default di UI Google Ads.

GAQL

SELECT ad_group_criterion.keyword.text,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.approval_status,
  ad_group_criterion.final_urls,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM keyword_view
WHERE segments.date DURING LAST_7_DAYS
  AND ad_group_criterion.status != 'REMOVED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.keyword.text,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.keyword.match_type,
    ad_group_criterion.approval_status,
    ad_group_criterion.final_urls,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM keyword_view
  WHERE segments.date DURING LAST_7_DAYS
    AND ad_group_criterion.status != 'REMOVED'
"
}'

Istilah penelusuran

Mengambil data dari layar ringkasan Istilah penelusuran default di UI Google Ads.

GAQL

SELECT search_term_view.search_term,
  segments.keyword.info.match_type,
  search_term_view.status,
  campaign.name,
  ad_group.name,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM search_term_view
WHERE segments.date DURING LAST_7_DAYS

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT search_term_view.search_term,
    segments.keyword.info.match_type,
    search_term_view.status,
    campaign.name,
    ad_group.name,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM search_term_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

Audiens

Mengambil data dari layar ringkasan Audiens default di UI Google Ads.

Poin Penting: Reporting API menampilkan audiens berdasarkan ID kriterianya. Untuk mendapatkan nama tampilannya, cari ID di tabel referensi yang disediakan di halaman Kode dan format. Anda dapat menggunakan kolom ad_group_criterion.type untuk menentukan tabel jenis kriteria yang akan digunakan.

GAQL

SELECT ad_group_criterion.resource_name,
  ad_group_criterion.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM ad_group_audience_view
WHERE segments.date DURING LAST_7_DAYS

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.resource_name,
    ad_group_criterion.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM ad_group_audience_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

Usia (Demografi)

Ambil data dari layar ringkasan demografi Usia default di UI Google Ads.

GAQL

SELECT ad_group_criterion.age_range.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM age_range_view
WHERE segments.date DURING LAST_7_DAYS

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.age_range.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM age_range_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

Gender (Demografi)

Ambil data dari layar ringkasan demografi Gender default di UI Google Ads.

GAQL

SELECT ad_group_criterion.gender.type,
  campaign.name,
  ad_group.name,
  ad_group_criterion.system_serving_status,
  ad_group_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.advertising_channel_type
FROM gender_view
WHERE segments.date DURING LAST_7_DAYS

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT ad_group_criterion.gender.type,
    campaign.name,
    ad_group.name,
    ad_group_criterion.system_serving_status,
    ad_group_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.advertising_channel_type
  FROM gender_view
  WHERE segments.date DURING LAST_7_DAYS
"
}'

Lokasi

Ambil data dari layar ringkasan Lokasi default di UI Google Ads.

Poin Penting: Reporting API menampilkan lokasi berdasarkan ID kriterianya. Untuk mendapatkan nama tampilannya, cari campaign_criterion.location.geo_target_constant di data target geografis, atau gunakan API untuk mengkueri resource geo_target_constant.

GAQL

SELECT campaign_criterion.location.geo_target_constant,
  campaign.name,
  campaign_criterion.bid_modifier,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM location_view
WHERE segments.date DURING LAST_7_DAYS
  AND campaign_criterion.status != 'REMOVED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign_criterion.location.geo_target_constant,
    campaign.name,
    campaign_criterion.bid_modifier,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros
  FROM location_view
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign_criterion.status != 'REMOVED'
"
}'

Mencari konstanta geografis

Halaman Kode dan format menyediakan tabel referensi untuk sebagian besar konstanta yang digunakan dalam API. Namun, Anda juga dapat mencari beberapa konstanta secara dinamis menggunakan Bahasa Kueri Google Ads.

Contoh ini menunjukkan cara mencari lokasi berdasarkan nama resource atau nama tampilannya.

Menurut nama resource

Cari Mountain View, CA, berdasarkan nama resource-nya geoTargetConstants/1014044.

GAQL

SELECT geo_target_constant.canonical_name,
  geo_target_constant.country_code,
  geo_target_constant.id,
  geo_target_constant.name,
  geo_target_constant.status,
  geo_target_constant.target_type
FROM geo_target_constant
WHERE geo_target_constant.resource_name = 'geoTargetConstants/1014044'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
\"query\": \"
  SELECT geo_target_constant.canonical_name,
    geo_target_constant.country_code,
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.status,
    geo_target_constant.target_type
  FROM geo_target_constant
  WHERE geo_target_constant.resource_name = 'geoTargetConstants/1014044'
\"
}"

Menurut nama tampilan

Cari "Mountain View" sebagai nama kota di Amerika Serikat.

Catatan: Saat mengkueri lokasi berdasarkan nama, Anda mungkin akan menerima beberapa kecocokan. Filter menurut geo_target_constant.country_code, geo_target_constant.target_type, dan geo_target_constant.status, lalu periksa geo_target_constant.canonical_name untuk memperjelas daftar hasil dalam kode klien Anda.

GAQL

SELECT geo_target_constant.canonical_name,
  geo_target_constant.country_code,
  geo_target_constant.id,
  geo_target_constant.name,
  geo_target_constant.status,
  geo_target_constant.target_type
FROM geo_target_constant
WHERE geo_target_constant.country_code = 'US'
  AND geo_target_constant.target_type = 'City'
  AND geo_target_constant.name = 'Mountain View'
  AND geo_target_constant.status = 'ENABLED'

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
\"query\": \"
  SELECT geo_target_constant.canonical_name,
    geo_target_constant.country_code,
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.status,
    geo_target_constant.target_type
  FROM geo_target_constant
  WHERE geo_target_constant.country_code = 'US'
    AND geo_target_constant.target_type = 'City'
    AND geo_target_constant.name = 'Mountain View'
    AND geo_target_constant.status = 'ENABLED'
\"
}"