Google Ads API 입문: 첫 보고서 조회와 지표 단위 확인
캠페인 보고서 한 행을 기준으로 Google Ads API의 필드와 GAQL을 익힙니다. 비용 단위, 전환수, PMax 조회와 다른 매체 자료를 합칠 때의 확인 순서를 설명합니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
Google Ads API는 프로그램이 광고 계정의 데이터를 요청하거나 설정을 변경하는 연결 방식입니다. 이 글의 첫 목표는 설정 변경 없이 캠페인별 지난 7일 성과를 조회하고 금액이 맞는지 확인하는 것입니다. API로 조회할 수 있는 범위와 광고 화면의 기능이 항상 같지는 않습니다.
계정 연결이 없다면 아래 가상 데이터 계산부터 해도 됩니다. 연결 담당자가 있다면 먼저 보고서 조건을 전달하고 읽기 조회 결과를 받아 확인합니다.
처음 만들 보고서 한 행
| 항목 | 가상 보고서 조건 |
|---|---|
| 대상 | 조회 권한이 있는 광고 계정 한 개 |
| 행 단위 | 캠페인 한 개의 기간 합계 |
| 기간 | 오늘을 제외한 지난 7일 |
| 필드 | 캠페인 ID와 이름, 노출, 클릭, 비용, 전환수 |
| 비교 대상 | 같은 계정과 기간, 필터를 적용한 Google Ads 화면 |
필드는 응답에 들어갈 항목 이름이고, 리소스는 캠페인 같은 조회 대상입니다. 세그먼트는 날짜나 기기처럼 성과를 나누는 기준입니다. 날짜를 추가하면 같은 캠페인도 일별 여러 행으로 나뉩니다.
필요한 데이터의 이름을 찾습니다
| 목적 | 리소스 또는 필드 | 의미 |
|---|---|---|
| 캠페인 식별 | campaign.id, campaign.name | 이름이 같아도 ID로 구분 |
| 광고그룹 | ad_group | 캠페인 안의 광고그룹 |
| 개별 광고 | ad_group_ad | 광고그룹에 연결된 광고 |
| 키워드 조건 | ad_group_criterion | 키워드 등을 담는 조건이며 모두 키워드는 아님 |
| PMax 에셋 그룹 | asset_group | PMax에서 소재를 묶는 단위 |
| 일별 분류 | segments.date | 계정 시간대를 기준으로 날짜 분리 |
| 기기별 분류 | segments.device | 모바일, 데스크톱 등으로 분리 |
캠페인 예산은 campaign_budget 같은 연결 리소스를 확인해야 합니다. 한 리소스에서 모든 필드와 지표를 아무렇게나 섞을 수는 없습니다. API 버전은 서비스 규격의 배포 번호입니다. 사용하는 API 버전의 필드 문서에서 함께 선택 가능한 조합을 확인합니다.
비용과 전환가치는 단위가 다릅니다
| 보고서 항목 | API 필드 | 처리 |
|---|---|---|
| 노출수 | metrics.impressions | 횟수 |
| 클릭수 | metrics.clicks | 횟수 |
| 비용 | metrics.cost_micros | 1,000,000으로 나누기 |
| 평균 클릭당 비용(CPC) | metrics.average_cpc | 마이크로 금액을 1,000,000으로 나누기 |
| 전환당 비용(CPA) | metrics.cost_per_conversion | 마이크로 금액을 1,000,000으로 나누기 |
| 전환수 | metrics.conversions | 소수 유지, 집계 대상 확인 |
| 전환가치 | metrics.conversions_value | 마이크로 비용처럼 일괄 나누지 않음 |
| 클릭률(CTR) | metrics.ctr | 0.05를 백분율로 표시하면 5% |
마이크로는 금액을 백만 배로 표현한 단위입니다. 나누기 1,000,000은 환율 변환이 아닙니다. 계정 통화가 KRW일 때만 변환 결과를 원으로 표시합니다. customer.currency_code와 customer.time_zone도 함께 기록합니다. 지표 정의
가상 데이터로 계산해 보기
계정 통화가 KRW이고 비용 원시값이 15,000,000,000, 클릭수 30, 노출수 600, 전환가치가 60,000이라고 가정합니다.
| 확인할 값 | 계산 | 결과 |
|---|---|---|
| 비용 | 15,000,000,000 ÷ 1,000,000 | 15,000원 |
| CPC | 15,000 ÷ 30 | 500원 |
| CTR | 30 ÷ 600 × 100 | 5% |
| ROAS | 60,000 ÷ 15,000 | 4배 또는 400% |
ROAS는 광고비 대비 전환가치의 비율입니다. 전환가치가 매출인지 임의로 설정한 점수인지 확인해야 하며 ROAS가 이익을 뜻하지는 않습니다. 비용이 0이면 ROAS를 0으로 채우지 말고 계산 불가로 구분합니다.
연결 전에 확인할 네 가지
- Cloud 프로젝트: Google Cloud에서 API 사용과 인증 구성을 관리하는 단위입니다.
- OAuth 인증: 계정 접근을 허용하는 절차입니다. 클라이언트 ID와 비밀값만 있다고 사용자 승인이나 광고 계정 접근이 완료되지는 않습니다.
- 접근 수준: 테스트 계정용인지 실제 광고 계정 조회가 가능한지 확인합니다.
- 계정 ID와 권한: 조회 대상 광고 계정과 인증한 사용자의 접근 권한이 맞는지 확인합니다.
2026년 10월 확인한 공식 안내는 접근 수준을 Cloud 프로젝트 기준으로 설명하며 Test, Explorer, Basic, Standard를 구분합니다. Explorer도 실제 계정에 접근할 수 있으므로 ‘실제 계정에는 반드시 Basic이 필요하다’고 단정하지 않습니다. Basic의 일일 한도 15,000은 단순한 HTTP 요청 횟수와 같은 뜻으로 취급하지 말고 작업 계산 규칙을 확인합니다. 접근 수준 안내
Google은 2026년 9월 9일 개발자 토큰을 종료하고 접근 관리를 Cloud 프로젝트로 이전했다고 안내합니다. 새 Google Ads API 신청은 Cloud Console에서 진행하며 옛 Google Ads API 센터에서 토큰을 신청하지 않습니다. 기존 코드에 남은 토큰 헤더는 현재 무시되지만 이후 버전에서 거부될 수 있으므로 사용하는 라이브러리와 이전 안내를 확인합니다. 인증 파일이나 갱신 토큰, 비밀값은 AI 대화나 공개 저장소에 붙여넣지 않습니다. 시작 안내, 개발자 토큰 안내
GAQL로 첫 조회 조건을 씁니다
GAQL(Google Ads Query Language)은 가져올 항목과 조건을 적는 Google Ads의 조회 언어입니다. 아래는 캠페인별 지난 7일 합계를 요청하는 예시입니다.
SELECT
campaign.id,
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.cost_micros,
metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.cost_micros DESCSELECT는 받을 항목, FROM은 조회 대상, WHERE는 조건입니다. ORDER BY는 정렬이며 여기서는 비용이 큰 순서입니다. LAST_7_DAYS는 오늘을 제외한 지난 7일입니다. 일별 행이 필요하면 SELECT에 segments.date를 추가합니다.
이 쿼리만 메모장에 붙이면 API가 실행되는 것은 아닙니다. 인증된 프로그램이 대상 계정에 조회 요청으로 보내야 합니다. GAQL 안내의 쿼리 빌더는 필드와 조합을 구성하는 데 쓰며 실제 계정 연결 성공까지 보장하지 않습니다.
첫 결과에서는 캠페인 이름보다 ID, 조회 기간, 비용 변환을 먼저 봅니다. 화면과 합계가 다르면 계정, 시간대, 필터, 날짜 분류와 데이터 갱신 시점을 맞춥니다. 숫자를 맞추려고 임의로 배수를 곱하지 않습니다.
전환수를 정수로 만들려고 다른 지표를 쓰지 않습니다
기여 모델은 전환의 기여를 광고 접점에 배분하는 방식입니다. 그 결과 전환수에 소수가 나타날 수 있습니다. 소수라는 이유만으로 오류는 아니지만 같은 기간과 집계 조건의 광고 화면과 대조합니다. metrics.all_conversions는 포함 범위가 다른 지표이지 소수를 정수로 바꾸는 기능이 아닙니다. 전환 액션별로 나눠도 소수가 남을 수 있습니다.
전환 액션은 구매나 문의처럼 등록한 성과 행동입니다. 어떤 액션이 포함되는지와 날짜가 광고 상호작용 기준인지 전환 발생일 기준인지 확인합니다. 전환 발생일별 지표가 필요하면 해당 필드 정의를 확인하고 기존 지표와 혼합하지 않습니다. 당일 숫자는 갱신되며 이후 전환이나 조정으로 과거 값도 달라질 수 있습니다. 모든 지표가 정확히 3시간 뒤 확정되는 것은 아닙니다. 전환 보고 안내
PMax의 소재와 채널 성과도 조회할 수 있습니다
PMax는 광고그룹 대신 에셋 그룹을 사용합니다. 에셋은 이미지나 제목, 동영상 같은 소재입니다. 현재 공식 문서는 asset_group_asset에서 클릭, 노출, 전환 등 숫자 지표를 조회하는 예시를 제공합니다. ‘개별 소재는 등급만 제공한다’는 옛 제한을 그대로 적용하지 않습니다. PMax 소재 보고 안내
채널은 광고가 노출된 네트워크 구분입니다. 공식 안내는 API v23 이상에서 에셋 그룹 성과에 segments.ad_network_type을 추가할 수 있다고 설명합니다.
SELECT
campaign.id,
asset_group.id,
asset_group.name,
segments.ad_network_type,
metrics.impressions,
metrics.clicks,
metrics.cost_micros,
metrics.conversions
FROM asset_group
WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'
AND segments.date DURING LAST_7_DAYS에셋 그룹 합계와 개별 소재 자료를 합칠 때 그룹 비용을 소재마다 복제해 합산하면 안 됩니다. 소재가 함께 노출된 결과도 있으므로 소재별 숫자를 단순 합쳐 캠페인 총계로 쓰기 전에 집계 정의를 확인합니다. 에셋 그룹과 채널 보고
Demand Gen과 앱 캠페인도 캠페인, 광고그룹, 광고 및 소재 리소스별 지원 필드를 확인합니다. 한 유형의 제한을 다른 유형에 적용하거나 모든 metrics.*를 조회할 수 있다고 가정하지 않습니다.
다른 매체와 합칠 때는 행과 단위를 맞춥니다
같은 이름의 캠페인은 여러 계정과 매체에 있을 수 있습니다. 날짜와 캠페인 이름만으로 연결하지 말고 매체 + 계정 ID + 캠페인 ID + 날짜처럼 행을 구분할 기준을 정합니다. 기간 합계 자료와 일별 자료도 섞지 않습니다.
| 확인 | 잘못 합치기 쉬운 경우 |
|---|---|
| 통화 | USD와 KRW 금액을 환산 없이 더함 |
| 비율 | 0.05와 5가 둘 다 5%인지 확인하지 않음 |
| 전환 정의 | 문의와 구매를 같은 성과로 합침 |
| 기여 조건 | 다른 기여 기간과 방식의 전환을 동일하게 취급 |
| 자료 연결 | 같은 이름 때문에 다른 캠페인을 한 행으로 연결 |
Meta의 CTR을 Google과 똑같은 소수 형식이라고 가정하지 않습니다. 매체 응답의 필드 정의와 실제 샘플을 확인해 출력 형식을 통일합니다. 여러 매체가 같은 구매를 각자 전환으로 인정할 수 있으므로 매체 전환 합계가 실제 주문 수와 같다고 보장하지 않습니다.
AI에게 전달할 첫 요청
Google Ads API의 읽기 조회용 Python 코드 초안을 작성해줘.
광고 설정을 변경하는 요청은 제외해줘.
대상: 권한이 있는 광고 계정 한 개. 실제 ID와 비밀값은 내가 로컬에서 넣음.
기간: 오늘을 제외한 지난 7일, 계정 시간대 기준.
행: 캠페인 한 개의 기간 합계.
필드: 계정 ID, 통화, 시간대, 캠페인 ID와 이름, 노출, 클릭, 비용, 전환수.
비용은 cost_micros를 100만으로 나누되 계정 통화를 유지해줘.
전환수의 소수는 보존해줘.
현재 사용하는 라이브러리와 API 버전을 먼저 확인해줘.
인증값은 출력하지 말고, 준비와 실행 방법 및 CSV 확인 방법을 설명해줘.CSV는 표의 행과 열을 텍스트로 저장하는 파일 형식입니다. AI가 만든 코드는 초안입니다. 먼저 작은 기간과 계정 하나로 조회하고 화면과 비교한 다음 확장합니다. 오류가 나면 비밀값을 지운 오류 코드, 사용 버전, 요청한 리소스와 필드만 공유합니다.
| 증상 | 먼저 확인할 것 |
|---|---|
| 권한 오류 | 인증 사용자, 대상 계정, 프로젝트 접근 수준과 관리자 경유 설정 |
| 필드 조합 오류 | 사용 버전과 리소스에서 함께 선택 가능한 필드 |
| 결과 없음 | 계정과 날짜, 필터, 실제 광고 활동과 0값 행 처리 |
| 금액이 지나치게 큼 | 마이크로 변환 누락과 중복 행 |
| 화면 합계와 다름 | 시간대, 필터, 세그먼트, 전환 정의 및 갱신 시점 |
관리자 계정을 거쳐 조회하는 구성에서는 로그인 기준 관리자 계정과 실제 조회 대상 광고 계정을 구분합니다. 결과에 0값 행이 생략될 수 있으므로 행이 없다는 이유만으로 캠페인이 삭제됐다고 판단하지 않습니다. 이 글의 쿼리는 조회 형식 예시이며 실제 계정 실행 결과는 계정 연결 후 확인해야 합니다.
혼자 다시 확인하기
가상 USD 계정의 cost_micros가 15,000,000이고 전환수가 2.5입니다. 이를 ‘15원, 전환 3건’으로 저장해도 될까요?
아닙니다. 비용은 15달러이고 전환수는 2.5를 유지합니다. 소수라는 이유만으로 지표를 바꾸거나 반올림하지 않습니다. 이 차이를 설명하고 첫 조회 결과의 계정, 기간, 단위를 확인할 수 있으면 다음 보고서로 넘어갑니다.
3줄 요약
-
첫 조회는 계정과 기간, 캠페인 ID를 정하고 광고 화면의 같은 조건과 비교합니다.
-
비용의 마이크로 단위와 전환가치, 통화 및 비율의 표시 형식을 구분합니다.
-
PMax도 소재와 채널 성과를 조회할 수 있으며 사용 버전과 필드 조합을 확인합니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
계정 통화가 USD이고 cost_micros가 15000000이면 비용은 얼마인가요?
이 글이 도움이 되었나요?
GA4 화면의 숫자를 모으고 읽고 보여 주는 세 단계를 정리했습니다
코스 전체 보기 →
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.