메타 광고 라이브러리 API 가이드: 화면 검색부터 조회 범위 이해하기
경쟁사 광고를 화면에서 찾아 3개만 기록해 봅니다. 광고 라이브러리와 API의 조회 범위, 광고 성과를 단정하면 안 되는 이유, 요청과 응답을 읽는 방법을 설명합니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
경쟁사가 어떤 광고를 내보내는지 알고 싶다면 Meta 광고 라이브러리에서 먼저 광고 3개를 찾아 기록해 보세요. 화면에서 보는 광고를 API로 모두 받을 수 있는 것은 아닙니다.
API는 프로그램이 다른 서비스의 자료를 요청하는 기능입니다. 광고 라이브러리 API를 쓰기 전에 내가 조사하려는 광고가 조회 대상인지 확인해야 합니다. 이 글에서는 화면 조사부터 하고, 필요한 경우 API 요청을 읽는 단계로 이어갑니다.
세 가지 도구를 구분합니다
| 도구 | 주로 확인할 것 | 처음 선택할 상황 |
|---|---|---|
| 광고 라이브러리 화면 | 공개된 광고 소재와 게재 정보 | 경쟁사의 현재 소재를 몇 개 비교할 때 |
| 광고 라이브러리 API | 지원 범위 안의 공개 광고 자료 | 같은 조건의 자료를 프로그램으로 조회할 때 |
| 마케팅 API의 Insights | 접근 권한이 있는 광고 계정의 성과 | 우리 계정의 비용과 전환을 보고할 때 |
Insights는 광고 성과를 조회하는 기능입니다. 내 계정의 실적이 목적이라면 Meta 광고 API 안내로 진행합니다. 다른 회사의 공개 광고를 조회할 수 있다고 해서 그 회사의 실제 비용, 매출, 고객 명단에 접근할 수 있는 것은 아닙니다.
첫 실습: 한 광고주의 광고 3개 기록하기
- 광고 라이브러리에서 조사할 국가를 대한민국으로 정합니다.
- 일반 상품이나 서비스를 조사한다면 광고 분류에서 ‘모든 광고’를 선택합니다.
- 브랜드 이름을 검색하고 실제 조사 대상의 페이지인지 확인합니다.
- 광고주를 좁힌 뒤 필요하면 활동 상태, 플랫폼이나 미디어 유형 필터를 적용합니다.
- 광고 상세 정보를 열어 ID와 게재 시작일, 소재 특징을 기록합니다.
페이지는 광고주가 Facebook에서 사용하는 공개 공간이고, 라이브러리 ID는 광고를 구분하는 번호입니다. 이름이 비슷한 판매점이나 대행사의 광고가 함께 나올 수 있으므로 페이지 이름과 연결 정보를 대조합니다.
위 이미지는 기존 조사 당시의 화면입니다. 국가와 검색창 부분은 잘려 있으므로 이미지 자체에서 검색 조건을 확인할 수는 없습니다. 내 조사에서는 조건을 별도로 적습니다.
다음은 실제 광고 성과가 아닌 기록 양식의 가상 예시입니다.
| 확인 날짜 | 국가와 광고주 | 라이브러리 ID | 시작일 | 관찰한 특징 | 모르는 것 |
|---|---|---|---|---|---|
| 2026-10-04 | 대한민국, 예시 브랜드 | DEMO-A | 2026-09-20 | 짧은 영상, 사용 장면 중심 | 비용과 구매수 |
| 2026-10-04 | 대한민국, 예시 브랜드 | DEMO-B | 2026-10-01 | 이미지, 가격 안내 | 비용과 구매수 |
| 2026-10-04 | 대한민국, 예시 브랜드 | DEMO-C | 미표시 | 여러 소재 버전 표시 | 실제 노출 비중 |
내 표에는 화면에 나온 실제 ID를 적습니다. 광고가 3개보다 적다면 보이는 수만 기록하고 나머지를 만들어 채우지 않습니다. ‘여러 버전’이나 ‘같은 소재 사용’ 표시가 있으면 그 문구도 남기되, 표시된 숫자를 서로 다른 이미지 개수나 제작비로 바로 환산하지 않습니다.
결과가 없을 때
국가, 광고 분류, 광고주와 활동 상태 필터를 다시 확인합니다. 한 번에 하나씩 조건을 바꿔야 어떤 조건이 결과에 영향을 줬는지 알 수 있습니다. 검색어는 광고주 이름과 다른 이름으로 등록돼 있을 수도 있습니다.
결과가 없다는 사실은 ‘이 조건에서 찾지 못했다’는 뜻입니다. 그 회사가 광고를 전혀 하지 않는다는 증거는 아닙니다. 연령 제한 소재는 로그인과 연령 조건에 따라 보이지 않을 수 있습니다. 화면 이용과 표시 범위
화면에서 알 수 있는 것과 없는 것
일반적인 한국 상업 광고에서는 소재, 문구, 페이지와 게재 정보를 관찰합니다. 클릭수와 구매수, 광고 수익은 공개 성과표처럼 제공되지 않습니다. 정치나 사회 이슈 광고에는 지출과 노출이 정확한 단일 값이 아닌 범위로 표시될 수 있습니다.
이미지의 일부 광고에는 지출 범위와 노출 범위가 보입니다. 이런 범위의 중간값을 실제 비용이라고 적거나, 노출을 구매수로 바꾸면 안 됩니다. 도달은 광고를 본 계정 수에 관한 지표이고 노출은 광고가 표시된 횟수여서 서로 다릅니다.
오래 게재됐다는 사실만으로 잘 팔린다고 결론내리지 않습니다. 낮은 예산으로 오래 유지했거나 중간에 집행이 달라졌을 가능성도 있습니다. 여러 버전이 있다는 사실 역시 어떤 버전이 더 많이 노출됐거나 구매를 만들었는지 알려주지 않습니다.
보고서에서는 다음처럼 관찰과 가설을 나눕니다.
관찰: 조사일에 이 광고가 활성 상태였고 시작일은 9월 20일로 표시됐다.
미확인: 실제 누적 지출, 중간 중지 여부, 구매수와 매출.
가설: 사용 장면 중심 설명을 우리 상품에서도 시험해 볼 수 있다.
검증: 우리 계정에서 비교 조건을 정하고 직접 성과를 측정한다.어떤 광고를 API로 받을 수 있나요?
Meta의 API 안내는 전 세계의 정치 및 사회 이슈 광고 최근 7년과 영국 또는 EU에 게재된 모든 유형의 광고 최근 1년을 조회 범위로 설명합니다. EU는 유럽 연합이며 관련 지역의 세부 범위는 공식 문서에서 확인합니다.
한국에만 게재된 일반 상업 광고는 이 범위와 다릅니다. 한국 회사라도 독일에 광고를 게재했다면 지역 조건에 해당할 수 있고, 반대로 미국 회사라도 한국에만 게재한 일반 상품 광고라면 같은 방식으로 판단합니다. 광고주의 국적과 광고가 도달한 국가는 다릅니다.
또한 화면의 보관 범위도 구분해야 합니다. 정치와 사회 이슈 광고는 7년, 영국과 EU 및 관련 지역에 게재된 광고는 마지막 노출 후 1년 보관 대상입니다. 이 조건에 해당하지 않는 일반 상업 광고가 종료된 뒤에도 계속 남아 있을 것으로 기대하면 안 됩니다. 광고 라이브러리 보관 안내
API가 필요한 경우의 준비
공식 API 시작 안내는 Facebook 계정의 신원과 위치 확인, 개발자 계정 준비, 앱 추가 순서로 설명합니다. 앱은 API 이용 주체를 등록하는 단위입니다. 인증과 접근 설정이 끝난 뒤에 조회할 수 있고 승인 시간은 상황에 따라 달라집니다. API 시작 절차
액세스 토큰은 API 이용 권한을 확인하는 비밀 인증값입니다. 비밀번호처럼 공개하지 않습니다.
아래는 실행 명령이 아니라 독일에 게재된 광고를 찾기 위한 요청 설계 예시입니다. 실제 토큰을 넣어 브라우저 주소창에 붙여 넣는 용도로 쓰지 않습니다.
요청 방식: GET
조회 경로: /<사용할 API 버전>/ads_archive
ad_reached_countries: ["DE"]
ad_type: ALL
ad_active_status: ALL
search_terms: fitness
fields: id,page_name,ad_creative_bodies,ad_delivery_start_timeGET은 자료를 조회하는 요청이고 ads_archive는 공개 광고 검색 경로입니다. 국가 코드 DE는 독일, KR은 대한민국입니다. fields는 응답에서 받을 항목을 뜻합니다. 실제 호출은 인증을 준비한 개발 환경에서 공식 문서의 지원 버전에 맞춰 구성합니다.
검색어는 자동 번역되지 않으므로 찾으려는 광고의 언어에 맞춥니다. 활동 상태를 생략하면 기본값이 게재 가능한 광고를 뜻하는 ACTIVE입니다. 비활성 광고까지 함께 조사하려면 전체 상태를 뜻하는 ALL을 명시합니다. 광고주 페이지 ID로 검색할 때는 search_page_ids를 사용할 수 있습니다. 검색 조건과 기본값
응답을 읽는 연습
다음은 실제 API 호출 결과가 아닌 가상 응답입니다.
{
"data": [
{
"id": "DEMO_001",
"page_name": "Example Brand",
"ad_creative_bodies": ["Try our fitness class"],
"ad_delivery_start_time": "2026-09-20T00:00:00+0000"
}
]
}data는 받은 광고 목록입니다. 이 예시에서는 광고가 한 개이고 ad_creative_bodies는 소재 문구를 담은 목록입니다. 문구가 여러 개일 수 있어 단일 문자열로 가정하지 않습니다. 응답에 비용이 없다고 비용이 0이라는 뜻은 아닙니다.
ad_delivery_start_time은 공식 필드 설명상 광고주가 설정한 게재 시작 시각이며 UTC, 즉 세계 표준시 기준입니다. 한국 시간으로 비교할 때는 시간대를 맞추고, 이 값만으로 실제 첫 노출이나 중단 없는 집행을 확인했다고 적지 않습니다. 시각 필드의 정의
더 많은 결과가 있으면 응답의 paging에 다음 결과를 받는 정보가 제공될 수 있습니다. 한 페이지의 행 수를 전체 광고 수로 보고하지 않습니다. 다음 페이지까지 처리할 때는 ID로 중복을 구분하고, 조회 조건과 수집 시점을 함께 저장합니다. 다음 페이지 URL이나 소재 조회 URL에는 인증값이 포함될 수 있으므로 보고서나 공개 로그에 그대로 남기지 않습니다. 응답과 페이지 처리
지역과 유형에 따라 받을 수 있는 필드가 다릅니다. 예를 들어 spend와 impressions는 정치 및 사회 이슈 광고의 범위 값이고 eu_total_reach는 EU 도달 추정값입니다. 영국 도달을 EU 필드로 대신 읽지 않습니다. 필요할 때 광고 필드 참조에서 지원 범위를 확인합니다.
| 결과 또는 오류 | 먼저 확인할 것 |
|---|---|
빈 data | 지원 광고 범위, 국가, 검색어와 활동 상태 |
190 | 액세스 토큰의 유효성과 인증 상태 |
100 | 국가와 필드 등 요청 조건의 형식 |
613 | 호출 제한과 재시도 간격 |
| 일부 값이 없음 | 해당 광고 종류와 지역에서 제공되는 필드인지 |
빈 목록을 광고 부재로 바로 해석하거나 오류 응답을 빈 목록으로 저장하지 않습니다. 오류 번호와 메시지를 확인하되 인증값은 기록에서 제외합니다.
같은 조사를 혼자 반복해 보기
처음 기록한 국가, 광고주와 필터를 저장하고 다음 조사에서도 동일하게 적용합니다. 검색 저장 기능을 사용할 수 없다면 검색 주소와 조건을 별도로 기록하면 됩니다. 광고 3개의 ID를 비교해 계속 보이는 것, 새로 보이는 것, 더 이상 찾지 못한 것을 구분합니다.
없어진 광고를 곧바로 ‘실패한 소재’라고 쓰지 않습니다. 조사 조건과 보관 범위가 달라졌을 수도 있습니다. 화면에서 관찰한 사실을 적고, 우리 상품에 적용할 아이디어는 가설로 따로 남깁니다.
소재가 공개돼 있다는 사실이 자유로운 재사용 허락을 뜻하지는 않습니다. 검색 결과 다운로드에는 로그인과 이용 조건 동의가 필요하고, API 소재 저장에도 분석 목적과 보관 조건이 적용됩니다. 보고서에 쓰려면 자료 출처와 확인일을 남기고 해당 이용 조건을 확인합니다. 화면 다운로드 안내, API 소재 필드와 저장 조건
확인 질문입니다. 광고 문구가 두 개이고 비용 필드가 없다면 ‘광고 2개를 비용 0원으로 집행했다’고 써도 될까요? 그렇지 않습니다. 한 광고에 여러 문구가 있을 수 있고 비용은 미확인입니다. 광고 ID와 문구 목록, 미확인 지표를 구분했다면 응답의 기본 구조를 이해한 것입니다.
3줄 요약
-
광고 라이브러리 화면에서는 광고를 찾아 소재와 게재 정보를 관찰할 수 있지만 경쟁사의 매출이나 전환 성과는 알 수 없습니다.
-
API는 정치와 사회 이슈 광고 및 영국과 EU 등에 게재된 광고를 대상으로 하므로 한국에만 게재된 일반 상업 광고 조사와 구분합니다.
-
처음에는 광고 3개의 검색 조건과 ID를 기록하고 같은 조건으로 다시 확인하며 보이지 않는 값은 미확인으로 남깁니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
대한민국에만 게재된 일반 화장품 광고를 광고 라이브러리 API로 받으려 할 때 먼저 알아야 할 점은 무엇인가요?
이 글이 도움이 되었나요?
광고 화면에 나오는 지표를 정의와 계산식으로 정리했습니다
코스 전체 보기 →
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.