메타 광고 API로 분석 가시성 높이는 방법?

내용 검토: 2026년 9월 8일. 광고 성과 조회와 광고 변경을 구분하고, 집계 예제를 추가했습니다.

Meta 광고 API 보고서는 ‘무엇을 조회했는가’를 함께 기록해야 관리자 화면과 비교할 수 있습니다. 날짜·광고 ID·통화·조회 수준을 먼저 맞추고 비용, 노출, 클릭 같은 기본 지표부터 시트에 정리하세요.

Graph API와 GraphQL은 다른 이름입니다

이 글에서 사용하는 것은 Meta Graph API의 Insights 조회입니다. GraphQL 쿼리를 작성해야 한다는 이전 설명은 바로잡습니다. 기본적인 보고서 흐름은 광고 계정의 Insights 엔드포인트에 필요한 필드와 기간을 지정해 읽고, 반환된 JSON을 표의 행으로 바꾸는 방식입니다. Meta 공식 Insights API 예제에서 현재 지원 요청을 확인할 수 있습니다.

최초 조회에 필요한 준비

분석할 광고 계정과 접근 권한을 확인합니다. 토큰이 존재한다는 사실만으로 모든 광고 계정에 접근 가능한 것은 아닙니다.
앱에서 사용하는 지원 API 버전과 읽기 권한을 확인합니다. 실제 필요한 접근 수준·앱 검수 조건은 운영 환경에 따라 달라집니다.
기간, 계정 시간대·통화, 조회 수준을 정합니다. 처음에는 광고 수준의 일별 비용·노출·클릭으로 시작합니다.
토큰은 공유 시트의 셀에 저장하지 않습니다. 스크립트 속성을 사용해도 프로젝트 편집자가 접근할 수 있으므로 비밀 보관소나 사용자별 접근 통제와 같다고 여기지 마세요.

요청 모양과 가상 응답으로 열 정의하기

아래 요청은 구조를 설명하는 템플릿입니다. API_VERSION, AD_ACCOUNT_ID, 토큰은 실행할 환경에서 확인한 값으로 설정해야 합니다. 이 글 작성 과정에서 실광고 계정 조회를 실행한 것은 아닙니다.

GET https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/insights
Authorization: Bearer YOUR_ACCESS_TOKEN

fields=date_start,date_stop,account_currency,ad_id,ad_name,spend,impressions,clicks
level=ad
time_increment=1
time_range={"since":"2026-09-01","until":"2026-09-01"}

요청 시 매개변수는 사용하는 HTTP 클라이언트에 맞춰 URL 인코딩합니다. 예를 들어 가상 응답의 data가 아래 두 행이라면 숫자 문자열을 숫자로 바꿔 계산합니다. 광고 ID는 큰 정수로 변환하지 않고 문자열로 유지합니다.

{"data":[
  {"date_start":"2026-09-01","date_stop":"2026-09-01","account_currency":"KRW","ad_id":"1001","ad_name":"가상 소재 A","spend":"12000","impressions":"2000","clicks":"40"},
  {"date_start":"2026-09-01","date_stop":"2026-09-01","account_currency":"KRW","ad_id":"1002","ad_name":"가상 소재 B","spend":"8000","impressions":"1000","clicks":"10"}
]}

시트 열	의미	주의점
date_start / date_stop	보고 기간	수집 시각과 별도로 보관
ad_id / ad_name	광고 식별자와 표시명	이름이 같아도 ID가 다를 수 있음
account_currency / spend	통화와 비용	다른 통화를 단순 합산하지 않음
impressions / clicks	노출·클릭	링크 클릭 등 다른 클릭 정의와 섞지 않음

합산 CTR을 계산하는 작은 검산 예제

위 가상 자료의 총비용은 20,000원, 노출은 3,000회, 클릭은 50회입니다. 합산 CTR은 50 ÷ 3,000 × 100 = 약 1.67%입니다. 소재별 CTR 2%와 1%의 단순 평균인 1.5%를 쓰면 노출량 차이가 사라집니다.

function summarizeInsights(rows) {
  const total = { spend: 0, impressions: 0, clicks: 0 };
  if (!Array.isArray(rows) || rows.length === 0) {
    throw new Error("계산할 행이 없습니다.");
  }
  const currencies = new Set(rows.map(row => {
    if (!row || typeof row.account_currency !== "string" ||
        !/^[A-Z]{3}$/.test(row.account_currency)) {
      throw new Error("통화 코드를 확인하세요.");
    }
    return row.account_currency;
  }));
  if (currencies.size > 1) throw new Error("통화별로 나눠 계산하세요.");
  for (const row of rows) {
    for (const key of Object.keys(total)) {
      const raw = row[key];
      if (!(["string", "number"].includes(typeof raw)) ||
          (typeof raw === "string" && raw.trim() === "")) {
        throw new Error("누락된 지표: " + key);
      }
      const value = Number(raw);
      if (!Number.isFinite(value) || value < 0 ||
          (key !== "spend" && !Number.isSafeInteger(value))) {
        throw new Error("잘못된 지표: " + key);
      }
      total[key] += value;
    }
  }
  return { ...total,
    ctrPercent: total.impressions ? total.clicks / total.impressions * 100 : null
  };
}

계산 예제를 실행해 보기

위 함수를 Apps Script 편집기에 붙여 넣고 아래 함수를 같은 프로젝트에 추가합니다. demoInsights를 실행하면 가상 데이터만 계산합니다. API 토큰이나 광고 계정이 필요하지 않으며 시트 저장·광고 변경도 하지 않습니다.

function demoInsights() {
  const rows = [
    {account_currency: "KRW", spend: "12000", impressions: "2000", clicks: "40"},
    {account_currency: "KRW", spend: "8000", impressions: "1000", clicks: "10"}
  ];
  console.log(JSON.stringify(summarizeInsights(rows)));
}

실행 로그의 예상값은 {"spend":20000,"impressions":3000,"clicks":50,"ctrPercent":1.6666666666666667}입니다. 소수의 표시 자릿수는 환경에 따라 다를 수 있습니다.

이 함수는 입력 행의 계산만 확인하는 예제입니다. API 호출이나 시트 저장은 수행하지 않습니다. 같은 날짜·광고 ID·집계 조건의 행이 중복되지 않은 입력을 사용하세요. 이 함수가 중복 행을 자동 제거하지는 않습니다. 빈 응답이나 지표 누락은 오류로 구분하며, 노출·클릭 수는 정수여야 합니다. 노출 0일 때 CTR은 0%로 단정하지 않고 계산 불가를 뜻하는 null로 반환합니다.

시트에 매일 누적할 때 빠뜨리기 쉬운 것

다음 페이지: 응답에 다음 페이지 정보가 있으면 첫 페이지에서 끝내지 않습니다. 완료하지 못한 날짜는 일부 수집 상태로 남깁니다.
중복 갱신: ‘계정 + 날짜 + 광고 ID + 집계 조건’을 키로 정합니다. 같은 기간을 재조회하면 기존 행을 교체하거나 버전으로 남기세요.
조회 실패: HTTP 상태와 API 오류 코드부터 확인합니다. 권한·토큰 만료·사용 제한·지원하지 않는 필드를 구분하고, 실패를 비용 0으로 저장하지 않습니다.
원자료 보관: 요청 조건과 수집 시각을 함께 남깁니다. 토큰은 오류 로그에도 기록하지 마세요.

Apps Script에서 연결할 경우 UrlFetchApp 공식 문서와 PropertiesService 접근 범위를 확인하세요. 공유 프로젝트에서 속성에 넣었다는 이유만으로 토큰이 다른 편집자에게 숨겨지는 것은 아닙니다.

광고 관리자와 숫자가 다르면 이 순서로 확인

같은 광고 계정·통화·시간대·날짜를 보고 있는가?
캠페인, 광고세트, 광고 중 같은 수준을 비교하는가?
전체 클릭과 링크 클릭처럼 이름이 비슷한 지표를 혼합하지 않았는가?
기기·게재 위치 등 breakdown이 다르거나 합계 행을 또 더하지 않았는가?
구매 등 전환을 추가했다면 기여기간·보고 기준과 데이터 갱신 시각이 같은가?

처음에는 위 예제처럼 기본 지표를 맞추고 전환 지표를 단계적으로 추가하는 편이 원인 추적에 좋습니다. 단순 CTR 상승만으로 매출이나 광고 수익성이 개선됐다고 판단하지 않습니다.

수집한 데이터를 운영 판단에 연결하기

소재별 성과 보고서 해석: 어떤 소재를 더 검토할지 결정하기
광고 변경 후 실제 적용 검증: 읽기 보고서와 광고 변경 작업을 구분하기
마케팅·광고 운영 가이드: 측정부터 실행 후 확인까지 연결하기

API 적용 이후의 확인 흐름은 Awen의 광고 API 실행 후 검증 기준도 참고할 수 있습니다.