매체 raw data 컬럼 가이드 — Meta, Google, TikTok, Naver의 진짜 컬럼들

Meta API의 actions, Google Ads의 conversions, TikTok의 conversion, Naver Search Ads의 ccnt. 이름이 비슷해도 같은 계약은 아닙니다. 이 글은 네 매체의 report field를 한 표로 매핑하고, 통화·시간대·attribution 설정까지 보존하는 방법을 정리합니다.

매체 UI 대시보드는 잘 그려졌지만 다음 분석을 하려면 raw data가 필요합니다.

• 매체 간 통합 대시보드 (한 BI에 4개 매체 ROAS를 동시에)
• MMM 입력 (일자별·채널별 spend·impression·click·conversion)
• 자체 attribution (last-click·data-driven 대신 자사 룰)
• 매체 default와 다른 lookback window로 재계산
• 클릭별·소재별 deep dive

매체 raw를 직접 다룰 때 가장 큰 함정은 컬럼 이름이 매체마다 다르고, 같은 이름의 컬럼도 정의가 다를 수 있다는 점입니다. “conversion”이라는 같은 단어가 매체마다 다른 걸 가리켜요.

5초 매핑 — 4개 매체 컬럼 한 표

의미	Meta (Marketing API)	Google Ads (Ads API)	TikTok (Marketing API)	Naver SA
캠페인 ID	campaign_id	campaign.id	campaign_id	nccCampaignId
광고 그룹	adset_id	ad_group.id	adgroup_id	nccAdgroupId
광고·소재 ID	ad_id	ad.id	ad_id	nccAdId
노출	impressions	metrics.impressions	impressions	impCnt
클릭	clicks	metrics.clicks	clicks	clkCnt
비용	spend	metrics.cost_micros	spend	salesAmt
전환 수	actions (nested)	metrics.conversions	conversion (선택한 optimization event)	ccnt
전환 가치	action_values (nested)	metrics.conversions_value	이벤트·report type별 value metric	convAmt
비디오 25% 시청	video_p25_watched_actions	metrics.video_quartile_p25_rate	video_views_p25	(없음)

이 표는 2026년 7월 19일 기준의 시작점입니다. API 버전·캠페인 유형·선택한 report field에 따라 지원 여부와 응답 형태가 달라질 수 있으므로, 수집기는 실제 응답 스키마를 저장하고 버전 변경 때 contract test를 통과해야 배포되도록 만듭니다.

Meta Marketing API 핵심 컬럼

Meta의 raw 데이터는 actions라는 nested array가 가장 큰 함정입니다. 한 row 안에 여러 종류의 전환이 array로 들어있고, 각각의 attribution window별 값이 또 따로예요.

자주 쓰는 액션 타입:

• purchase — 구매
• add_to_cart
• initiate_checkout
• complete_registration
• lead
• app_install
• mobile_app_install

Insights 요청에서 action_attribution_windows를 지정하면 같은 액션을 선택한 window별로 나눠 받을 수 있습니다. 지원 window와 기본 설정은 계정·목표·API 버전에 따라 달라질 수 있으므로 요청 파라미터와 응답 필드를 함께 보관해야 합니다.

Meta 액션 컬럼	의미
actions[action_type=purchase].value	기본 attribution 윈도우의 전환 수
actions[purchase]["1d_click"]	요청한 경우의 1일 click attribution 값
actions[purchase]["7d_click"]	요청한 경우의 7일 click attribution 값
actions[purchase]["1d_view"]	요청한 경우의 1일 view attribution 값
action_values[action_type=purchase].value	전환 가치 (매출)

위 표기는 실제 JSONPath가 아니라 배열 구조를 읽기 위한 pseudo-path입니다. raw export를 BigQuery로 적재할 때는 actions array를 행으로 풀고 action type과 window key를 각각 보존합니다.

purchase만 찾으면 계정에 따라 구매를 놓칠 수 있습니다. omni_purchase, pixel purchase처럼 실제 응답에 나타나는 action type을 먼저 inventory하고, 어느 타입을 비즈니스 구매로 합칠지 contract table에서 버전 관리합니다.

Google Ads API 핵심 컬럼

Google Ads API는 cost_micros 같은 단위가 특이합니다. 계정 통화 1단위가 1,000,000 micros이므로 1,000,000으로 나눠야 일반 통화 단위가 됩니다. 계정 통화가 KRW일 때만 그 결과가 원화입니다.

자주 쓰는 컬럼:

• metrics.cost_micros — 1,000,000으로 나누면 계정 통화 단위
• metrics.impressions — 노출 수
• metrics.clicks — 클릭 수
• metrics.conversions — 전환 수 (float, 부분 attribution 가능)
• metrics.conversions_value — 전환 가치
• metrics.all_conversions — include_in_conversions_metric 설정과 무관한 전체 전환
• metrics.view_through_conversions — view-through 전환만
• metrics.search_impression_share — 검색 인벤토리 점유율

Google Ads는 conversion이 float인 게 인상적입니다. data-driven attribution에서 한 클릭이 부분 전환을 만들 수 있어 0.4 같은 값이 나옵니다. 이걸 INT로 변환하면 안 됩니다.

전환 액션을 따로 보려면 segments.conversion_action으로 지표를 분해하고 conversion_action 리소스의 이름·유형·상태를 함께 조회합니다. 예를 들어 매출 전환과 lead 전환을 분리해서 ROAS·CPL을 따로 계산하려면 그 단계가 필요해요.

TikTok Marketing API 핵심 컬럼

TikTok Reporting API도 dimensions와 metrics를 골라 요청합니다. 다만 metric ID는 목표와 report type에 따라 달라질 수 있으므로 Ads Manager의 표시 이름을 그대로 컬럼명으로 추정하면 안 됩니다.

자주 쓰는 컬럼:

• spend — 비용 (광고주 통화)
• impressions / clicks
• conversion — 선택한 optimization event에 귀속된 전환 수
• real_time_conversion — 전환이 실제로 발생한 시점 기준 지표
• total_purchase / total_purchase_value — 앱 purchase report에서 쓰는 구매 수·가치 지표
• video_play_actions — 비디오 재생 시작 수
• video_views_p25 — 25% 지점까지 재생된 횟수
• video_views_p100 — 100% 지점까지 재생된 횟수
• engagements — destination click·social interaction 등을 포함하는 all-click 계열 지표

TikTok의 conversion은 선택한 optimization event에 따라 의미가 바뀝니다. 앱 구매용 total_purchase_value를 웹이나 TikTok Shop의 일반 매출 컬럼으로 재사용해서도 안 됩니다. report type·optimization event·metric ID를 같이 봐야 의미가 잡힙니다.

비디오 광고가 많은 TikTok에서는 video-view metric 묶음을 소재 진단에 쓸 수 있습니다. 수집 시에는 count와 rate를 구분하고, 분모가 impression인지 video start인지 현재 metric dictionary에서 확인합니다.

Naver Search Ads 핵심 컬럼

Naver Search Ads는 Stat API와 생성·다운로드 방식의 StatReport를 구분해야 합니다. 두 보고 경로는 같은 개념도 컬럼 표기가 다를 수 있으므로 원본 report type을 함께 저장합니다.

자주 쓰는 컬럼:

• nccCampaignId / nccAdgroupId / nccKeywordId / nccAdId — 캠페인·그룹·키워드·광고 식별자
• impCnt — 노출 수
• clkCnt — 클릭 수
• salesAmt — 비용 (부가세 포함 원화 금액)
• ccnt — Stat API의 전환 수
• convAmt — 전환 가치
• ctr — CTR (Naver가 직접 계산해서 줌)
• cpc — CPC
• avgRnk — 평균 노출 순위 (검색 광고)

대용량 전환 보고서는 “Conversion count”, “Sales by conversion”처럼 다른 헤더를 사용합니다. ccnt와 전환 보고서의 count를 무조건 같은 컬럼으로 합치지 말고, report type·전환 방식·전환 유형을 원본 차원으로 남긴 뒤 분석 레이어에서 매핑합니다.

매체별 같은 의미·다른 정의

같은 단어를 하나로 합치기 전에 아래 다섯 가지를 데이터 계약으로 고정합니다.

계약 항목	반드시 남길 것	합치기 전에 묻는 질문
비용	원본 금액·통화·세금 포함 여부	1단위가 micros인지, 원화인지, VAT 포함인지
클릭	원본 metric ID	전체 클릭인지 링크·목적지 클릭인지
전환	action ID·유형·포함 설정	구매·리드 중 무엇이며 어떤 window가 적용됐는지
보고 일자	source timezone·집계 grain	광고주 시간대 일별 집계인지 event timestamp인지
계층	campaign·group·creative 원본 ID	매체 간 이름이 아니라 어느 grain에서 유일한지

특히 click과 conversion은 UI의 번역된 라벨만 보고 통합하면 위험합니다. 원본 metric ID와 API 버전을 저장하면 정의가 바뀌거나 새 캠페인 유형이 들어왔을 때 과거 데이터와 구분할 수 있습니다.

이 API로 실제 무엇을 만들 수 있는지

네 API를 한 번에 연결하는 목적은 “컬럼을 많이 모으는 것”이 아니라 운영 질문에 답하는 것입니다.

• 일별 예산 pacing: 계획 예산과 매체별 spend를 같은 원화 기준으로 비교하고 과소·과다 집행을 알립니다.
• reconciliation 리포트: 매체 conversion, GA4 주요 이벤트, 주문 DB 주문을 나란히 두고 차이의 원인을 window·시간대·누락으로 분류합니다.
• 소재 성과 사전: creative ID를 기준으로 노출·목적지 클릭·영상 구간·구매를 묶되, 지원하지 않는 지표는 0이 아니라 NULL로 둡니다.
• schema drift 경보: 응답에 새 필드가 생기거나 필수 필드 타입이 바뀌면 적재를 조용히 계속하지 않고 격리 테이블과 알림으로 보냅니다.
• 환율·세금 감사표: 원본 금액과 원본 통화를 보존한 채 일별 환율·VAT 규칙을 적용해 spend_krw를 재현합니다.

통합 테이블의 최소 계약

매체 raw를 한 BI 테이블로 합칠 때의 시작 스키마는 이렇습니다.

컬럼	타입	의미
source_date	DATE	원본 보고서의 기준 일자
source_timezone	STRING	원본 일자가 사용하는 시간대
report_date_kst	DATE	KST 비교가 필요할 때 만든 파생 일자
media_source	STRING	meta / google / tiktok / naver
campaign_id	STRING	매체 캠페인 ID
campaign_name	STRING	캠페인 이름
adset_id / adset_name	STRING	광고 그룹
ad_id / ad_name	STRING	소재
impressions	INT	노출
clicks	INT	선택한 원본 click metric 값
click_metric_id	STRING	link·destination·all click 등 원본 정의
spend_krw	NUMERIC	환율 변환된 비용
conversions	NUMERIC	전환 수 (float 허용)
conversion_value_krw	NUMERIC	전환 가치
attribution_window	STRING	”click_7d_view_1d” 같은 라벨
currency_original	STRING	원본 통화
spend_original	NUMERIC	원본 통화 비용
metric_contract_version	STRING	수집 코드·API 정의 버전
ingested_at	TIMESTAMP	수집 완료 시각

이 스키마를 정의해두면 새 매체를 추가할 때도 매핑만 작성하면 됩니다.

마치며

매체 raw data는 컬럼이 많지만 원본 metric ID·통화·시간대·attribution 설정을 함께 보존하면 통합 BI의 숫자를 다시 설명할 수 있습니다. 새 매체를 붙일 때는 이름이 비슷한 컬럼부터 합치지 말고, fixture와 contract test로 정의가 같은지부터 확인해야 합니다.

다음 글은 raw data에서 마케터가 가장 헷갈리는 트래픽 소스 — Organic·Direct·Referral의 4가지 정의를 organicdirectreferral-ga4-mmp-amplitude-organic-4에서 다룹니다.

참고

• Meta Marketing API — Insights
• Google Ads API v24 — Metrics
• Google Ads API — Conversion reporting
• TikTok Marketing API — Reporting
• TikTok Reporting API — metric dictionary
• Naver Search Ad API
• Naver Search Ad API — Stat 지표 공지
• 사내 글: GA4 + BigQuery로 ROAS 파이프라인 직접 만들기
• 사내 글: 광고 측정 데이터 흐름
• 사내 글: 광고 SQL·BI 안티패턴 7가지
• 사내 글: MMP raw export 컬럼 사전