교육 문의커뮤니티 입장하기

Google Ads API 입문: 첫 보고서 조회와 지표 단위 확인

캠페인 보고서 한 행을 기준으로 Google Ads API의 필드와 GAQL을 익힙니다. 비용 단위와 전환수를 읽는 법, PMax 조회, 다른 매체 자료를 합칠 때의 확인 순서를 설명합니다.

지금까지 50명 넘게 읽었어요, 45%가 끝까지 읽었어요
Share
Google Ads API 입문: 첫 보고서 조회와 지표 단위 확인 대표 이미지
목차
  1. 처음 만들 보고서 한 행
  2. 필요한 데이터의 이름을 찾습니다
  3. 비용과 전환가치는 단위가 다릅니다
  4. 연결 전에 확인할 네 가지
  5. GAQL로 첫 조회 조건을 씁니다
  6. 전환수에 소수가 나오는 이유
  7. PMax의 소재와 채널 성과도 조회할 수 있습니다
  8. 다른 매체와 합칠 때는 행과 단위를 맞춥니다
  9. AI에게 첫 조회 코드를 맡기는 순서
  10. 3줄 요약

세 줄로 먼저 읽기

  1. Google Ads API의 첫 보고서는 계정 하나와 오늘을 뺀 지난 7일, 캠페인 ID를 정해 조회하고 같은 조건의 광고 화면 합계와 비교합니다.
  2. 비용 필드인 cost_micros는 100만으로 나눠야 계정 통화 금액이 되고 전환가치는 이렇게 나누지 않으며 전환수의 소수는 그대로 둡니다.
  3. 2026년 9월 9일부터 접근 관리 단위가 개발자 토큰에서 Cloud 프로젝트로 바뀌었고 PMax는 API v23 이상에서 에셋 그룹 성과를 채널별로 나눠 조회합니다.

Google Ads API는 프로그램이 광고 계정의 데이터를 요청하거나 설정을 바꿀 때 쓰는 연결 방식입니다. 이 글은 설정은 그대로 두고 캠페인별 지난 7일 성과를 조회해 금액이 광고 화면과 맞는지 확인하는 것까지 다룹니다.

개발 담당자가 연결을 맡는다면 마케터가 할 일은 두 가지입니다. 보고서 조건을 정해 전달하고, 돌아온 결과의 단위와 합계를 광고 화면과 대조하는 것입니다. API로 조회할 수 있는 항목과 광고 화면의 기능이 꼭 같지는 않으므로, 조건 전달과 결과 대조를 정확히 해 두면 연결 뒤의 혼선이 줄어듭니다.

처음 만들 보고서 한 행

첫 보고서는 결과 한 행이 어떤 모양일지부터 정합니다.

첫 보고서의 조건

  1. 1. 계정조회 권한이 있는
    광고 계정 한 개
  2. 2. 행 단위캠페인 한 개의
    기간 합계
  3. 3. 기간오늘을 제외한
    지난 7일
  4. 4. 필드캠페인 ID와 이름, 노출
    클릭, 비용, 전환수
  5. 5. 비교 대상같은 계정, 기간, 필터의
    Google Ads 화면

필드는 응답에 들어갈 항목 이름이고, 리소스는 캠페인처럼 조회하는 대상입니다. 세그먼트는 날짜나 기기처럼 성과를 나누는 기준입니다. 세그먼트에 날짜를 넣으면 같은 캠페인도 날짜별로 여러 행이 됩니다.

필요한 데이터의 이름을 찾습니다

리소스는 광고 계정의 구조를 따라 이어집니다. 검색 캠페인이라면 캠페인 아래 광고그룹이 있고, 그 아래 개별 광고와 키워드 조건이 있습니다. PMax는 광고그룹 대신 에셋 그룹으로 소재를 묶습니다.

캠페인 유형별 리소스 구조

리소스검색 캠페인광고그룹 단위PMax에셋 그룹 단위
캠페인, campaign제공제공
광고그룹, ad_group제공제공하지 않음
개별 광고, ad_group_ad제공제공하지 않음
키워드 조건, ad_group_criterion제공제공하지 않음
에셋 그룹, asset_group제공하지 않음제공
키워드 조건(ad_group_criterion)에는 키워드 말고 다른 조건도 들어 있습니다.

성과를 나누는 세그먼트와 식별용 필드는 아래처럼 씁니다.

목적필드의미
캠페인 식별campaign.id, campaign.name이름이 같아도 ID로 구분
일별 분류segments.date계정 시간대 기준으로 날짜를 나눔
기기별 분류segments.device모바일, 데스크톱 등으로 나눔

캠페인 예산은 campaign_budget처럼 연결된 다른 리소스에서 가져옵니다. 한 리소스에서 모든 필드와 지표를 마음대로 섞어 고를 수는 없습니다. API 버전은 서비스 규격의 배포 번호이고, 함께 고를 수 있는 필드 조합은 사용하는 버전의 필드 문서에 나와 있습니다.

비용과 전환가치는 단위가 다릅니다

API가 돌려주는 숫자는 광고 화면의 표시와 형식이 다릅니다. 비용 계열은 마이크로 단위로 오고, 비율은 소수로 옵니다.

보고서 항목API 필드처리
노출수metrics.impressions횟수 그대로
클릭수metrics.clicks횟수 그대로
비용metrics.cost_micros1,000,000으로 나누기
평균 클릭당 비용(CPC)metrics.average_cpc마이크로 금액이라 1,000,000으로 나누기
전환당 비용(CPA)metrics.cost_per_conversion마이크로 금액이라 1,000,000으로 나누기
전환수metrics.conversions소수 그대로, 집계 대상 확인
전환가치metrics.conversions_value비용처럼 일괄로 나누지 않음
클릭률(CTR)metrics.ctr0.05를 백분율로 표시하면 5%

마이크로는 금액을 100만 배로 나타낸 단위입니다. 100만으로 나누는 것은 환율 변환이 아닙니다. 나눈 값은 계정 통화 그대로이므로, 계정 통화가 KRW일 때만 원으로 표시합니다. 그래서 결과에는 customer.currency_code와 customer.time_zone도 함께 남깁니다. 각 지표의 정의는 Metrics 문서에 있습니다.

예를 들어 원화 계정에서 비용 원시값 15,000,000,000, 클릭수 30, 노출수 600, 전환가치 60,000이 왔다면 화면에 맞춰 바꾼 값은 아래와 같습니다.

원화 계정 캠페인 한 행을 바꾼 값

  • 15,000원비용15,000,000,000 ÷ 1,000,000
  • 500원CPC15,000 ÷ 30
  • 5%CTR30 ÷ 600 × 100
  • 400%ROAS60,000 ÷ 15,000, 4배

ROAS는 광고비 대비 전환가치의 비율입니다. 전환가치가 실제 매출인지 임의로 정한 점수인지에 따라 ROAS의 의미가 달라지고, 매출이라 해도 원가를 빼기 전 금액이라 이익과는 다릅니다. 비용이 0인 행은 ROAS를 0으로 채우지 않고 계산 불가로 따로 표시합니다.

연결 전에 확인할 네 가지

API를 연결하려면 아래 네 가지가 갖춰져야 합니다. 개발 담당자에게 맡기더라도 어디서 막혔는지 알아들으려면 이름 정도는 알아 두는 편이 좋습니다.

연결 전에 갖출 것

  1. 1. Cloud 프로젝트API 사용과 인증 구성을
    관리하는 단위
  2. 2. OAuth 인증사용자가 계정 접근을
    승인하는 절차
  3. 3. 접근 수준Test, Explorer
    Basic, Standard
  4. 4. 계정 ID와 권한인증한 사용자가 대상 계정에
    접근할 수 있는지

OAuth 인증은 클라이언트 ID와 비밀값을 받는 것으로 끝나지 않습니다. 사용자가 승인하고 그 사용자에게 광고 계정 접근 권한이 있어야 조회가 됩니다.

2026년 10월 기준 접근 수준 안내는 Cloud 프로젝트마다 접근 수준을 Test, Explorer, Basic, Standard 네 단계로 나눕니다. Explorer도 실제 광고 계정에 접근할 수 있습니다. 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 DESC

SELECT는 받을 항목, FROM은 조회 대상, WHERE는 조건, ORDER BY는 정렬 기준이고 여기서는 비용이 큰 순서입니다. LAST_7_DAYS는 오늘을 제외한 지난 7일입니다. 일별 행이 필요하면 SELECT에 segments.date를 더합니다.

이 쿼리는 인증된 프로그램이 대상 계정에 조회 요청으로 보내야 실행됩니다. GAQL 안내의 쿼리 빌더는 함께 고를 수 있는 필드로 쿼리를 짜 주는 도구이고, 계정 연결은 따로 해야 합니다. 프로그램이 결과를 돌려주면 화면에는 대략 이런 모양으로 나옵니다.

캠페인별 지난 7일 조회 결과
python campaign_report.py
campaign.id, campaign.name, impressions, clicks, cost_micros, conversions
1234567890, 봄 신상품 검색, 600, 30, 15000000000, 2.5
cost_micros는 100만으로 나눠야 15,000원이고 전환 2.5는 그대로 둡니다
설명을 위해 만든 화면입니다. 캠페인 ID와 이름, 숫자는 예시입니다.

첫 결과에서는 캠페인 이름보다 ID와 조회 기간, 비용 변환을 먼저 봅니다. 화면 합계와 다르면 계정, 시간대, 필터, 날짜 분류, 데이터 갱신 시점을 하나씩 맞춥니다. 숫자를 맞추려고 임의로 배수를 곱하지 않습니다.

전환수에 소수가 나오는 이유

기여 모델은 전환 하나의 공을 그 전환에 닿기까지 거친 광고 접점에 나눠 주는 방식입니다. 그래서 전환수에 소수가 나옵니다.

구매 1건이 두 광고에 나뉘는 과정

  1. 1. 검색 광고 클릭첫 번째 접점
  2. 2. 디스플레이 광고 클릭두 번째 접점
  3. 3. 구매 1건전환 발생
  4. 4. 기여 배분두 광고에 나눠 기록
    예를 들어 0.6건과 0.4건
배분 비율은 예시이며 실제 비율은 기여 모델에 따라 정해집니다.

소수는 오류가 아니므로 반올림하지 않고, 같은 기간과 집계 조건의 광고 화면 숫자와 대조합니다. metrics.all_conversions는 포함하는 전환 범위가 다른 지표이므로 정수를 얻는 용도로 쓰지 않습니다. 전환 액션별로 나눠 봐도 소수는 남습니다.

전환 액션은 구매나 문의처럼 광고 계정에 등록한 성과 행동입니다. 숫자를 대조하기 전에 어떤 액션이 집계에 들어가는지, 날짜가 광고 상호작용 기준인지 전환 발생일 기준인지 봅니다. 전환 발생일 기준 지표는 필드가 따로 있으므로 기존 지표와 한 표에 섞지 않습니다. 당일 숫자는 계속 갱신되고, 늦게 들어온 전환이나 조정으로 지난 날짜의 값도 바뀝니다. 날짜 기준과 갱신 방식은 전환 보고 안내에 정리돼 있습니다.

PMax의 소재와 채널 성과도 조회할 수 있습니다

PMax는 광고그룹 대신 에셋 그룹을 씁니다. 에셋은 이미지나 제목, 동영상 같은 소재입니다. PMax 소재 보고 안내에는 asset_group_asset에서 클릭, 노출, 전환 같은 숫자 지표를 조회하는 예시가 있습니다.

채널은 광고가 노출된 네트워크 구분입니다. 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

에셋 그룹 합계와 소재별 자료를 한 표에 합칠 때 가장 흔한 실수는 그룹 비용을 소재 행마다 복사해 두고 다시 더하는 것입니다.

소재 3개짜리 에셋 그룹의 비용 합계

  • 에셋 그룹 실제 비용100,000원
  • 그룹 비용을 소재마다 복사해 더한 값300,000원소재 3개 행에 같은 그룹 비용이 들어가 세 배가 됨
금액은 예시입니다.

여러 소재가 함께 노출된 결과도 소재마다 집계되므로 소재별 숫자를 그냥 더하면 캠페인 총계와 맞지 않습니다. 소재별 숫자를 총계로 쓰기 전에 에셋 그룹과 채널 보고의 집계 정의를 봅니다.

Demand Gen과 앱 캠페인도 캠페인, 광고그룹, 광고, 소재 리소스마다 지원하는 필드가 다릅니다. 그래서 한 캠페인 유형에서 되던 조회도 다른 유형에 쓸 때는 필드 문서에서 그 리소스가 지원하는 metrics.* 지표를 먼저 봅니다.

다른 매체와 합칠 때는 행과 단위를 맞춥니다

같은 이름의 캠페인이 여러 계정과 매체에 있을 수 있어서, 날짜와 캠페인 이름만으로 행을 연결하면 다른 캠페인이 한 행으로 합쳐집니다. 매체 자료를 합칠 때는 아래 순서로 기준을 맞춥니다.

매체 자료를 합치기 전에 맞출 기준

  1. 1. 행 연결 기준매체, 계정 ID
    캠페인 ID, 날짜
  2. 2. 기간 단위기간 합계와 일별 자료를
    섞지 않기
  3. 3. 통화USD와 KRW를
    환산 없이 더하지 않기
  4. 4. 비율 형식0.05와 5가
    둘 다 5%인지
  5. 5. 전환 정의문의와 구매, 기여 기간과
    방식이 같은지

CTR 같은 비율의 형식은 매체마다 다를 수 있습니다. Meta 자료를 합친다면 Meta 응답의 필드 정의와 실제 샘플 몇 행을 보고 Google 자료와 같은 형식으로 맞춥니다. 여러 매체가 같은 구매를 각자 자기 전환으로 집계하므로, 매체별 전환을 더한 값은 실제 주문 수보다 클 수 있습니다.

AI에게 첫 조회 코드를 맡기는 순서

코드를 직접 짜지 않는다면 AI에게 초안을 맡길 수 있습니다. 아래 요청문을 그대로 붙여 넣고, 계정 ID와 인증값은 내 컴퓨터에서 직접 넣습니다.

Google Ads API의 읽기 조회용 Python 코드 초안을 작성해줘. 광고 설정을 변경하는 요청은 제외해줘. 대상: 권한이 있는 광고 계정 한 개. 실제 ID와 비밀값은 내가 로컬에서 넣음. 기간: 오늘을 제외한 지난 7일, 계정 시간대 기준. 행: 캠페인 한 개의 기간 합계. 필드: 계정 ID, 통화, 시간대, 캠페인 ID와 이름, 노출, 클릭, 비용, 전환수. 비용은 cost_micros를 100만으로 나누되 계정 통화를 유지해줘. 전환수의 소수는 보존해줘. 현재 사용하는 라이브러리와 API 버전을 먼저 확인해줘. 인증값은 출력하지 말고, 준비와 실행 방법 및 CSV 확인 방법을 설명해줘.

CSV는 표의 행과 열을 텍스트로 저장하는 파일 형식입니다. AI가 준 코드는 초안이므로 작은 범위로 시작해 넓혀 갑니다.

AI 초안 코드로 첫 조회까지

  1. 1. 요청 보내기위 요청문으로
    코드 초안 받기
  2. 2. 인증값 넣기계정 ID와 비밀값은
    내 컴퓨터에서 직접
  3. 3. 작게 실행계정 하나, 지난 7일로
    CSV 받기
  4. 4. 화면과 대조비용, 클릭, 전환 합계가
    광고 화면과 같으면 성공
  5. 5. 범위 넓히기맞으면 기간과
    계정을 늘리기

오류가 나면 AI나 동료에게 비밀값을 지운 오류 코드, 사용 버전, 요청한 리소스와 필드만 보여 줍니다. 증상별로 먼저 볼 곳은 아래와 같습니다.

증상먼저 확인할 것
권한 오류인증한 사용자, 대상 계정, 프로젝트 접근 수준, 관리자 계정 경유 설정
필드 조합 오류사용 버전에서 그 리소스와 함께 고를 수 있는 필드인지
결과 없음계정과 날짜, 필터, 그 기간에 실제 광고 활동이 있었는지
금액이 지나치게 큼마이크로 변환을 빠뜨렸는지, 행이 중복됐는지
화면 합계와 다름시간대, 필터, 세그먼트, 전환 정의, 갱신 시점

관리자 계정을 거쳐 조회하는 구성이라면 로그인에 쓴 관리자 계정과 실제 조회 대상 광고 계정을 따로 적습니다. 성과가 0인 행은 결과에서 빠질 수 있으므로, 캠페인 행이 보이지 않으면 삭제를 의심하기 전에 그 기간의 성과가 0이었는지부터 봅니다.

3줄 요약

  1. Google Ads API의 첫 보고서는 계정 하나와 오늘을 뺀 지난 7일, 캠페인 ID를 정해 조회하고 같은 조건의 광고 화면 합계와 비교합니다.

  2. 비용 필드인 cost_micros는 100만으로 나눠야 계정 통화 금액이 되고 전환가치는 이렇게 나누지 않으며 전환수의 소수는 그대로 둡니다.

  3. 2026년 9월 9일부터 접근 관리 단위가 개발자 토큰에서 Cloud 프로젝트로 바뀌었고 PMax는 API v23 이상에서 에셋 그룹 성과를 채널별로 나눠 조회합니다.

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

계정 통화가 USD이고 cost_micros가 15000000이면 비용은 얼마인가요?

이 글이 도움이 되었나요?

이 글 다음 배우기마케터를 위한 데이터 분석 기초입문 코스 · 9편

GA4 화면의 숫자를 모으고 읽고 보여 주는 세 단계를 정리했습니다

  1. 1데이터 분석 뜻과 방법, 절차 4단계
  2. 2GA4 (Google Analytics 4) 뜻과 데이터 구조
  3. 3GTM (Google Tag Manager) 뜻과 구조
코스 전체 보기 →
이어서 읽기 좋은 글GA4 direct/none이 많을 때: 원인 8가지와 UTM 점검 순서 →

GA4의 (direct) / (none)은 유입 출처를 알 수 없는 트래픽입니다. 실제 직접 방문과 출처 정보 누락을 나누는 8가지 상황, UTM 링크를 만들고 보고서 반영을 확인하는 순서를 정리했습니다.