본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트
  • 문서
  • 카카오모먼트
  • 보고서

사이드 메뉴

검색

이 문서는 카카오모먼트 보고서 API 사용 방법을 안내합니다.

메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adAccounts/report

광고계정에 대한 보고서를 반환합니다.

광고계정 보고서는 디스플레이 캠페인, 메시지 캠페인을 포함한 값을 확인할 수 있습니다. 보고서 지표 그룹(metricsGroup)은 복수 선택이 가능합니다.

특정 일자에 해당하는 보고서는 그 다음날 오전 8시 이전까지는 변동 가능한 실시간성 지표로 참고합니다. 오늘(실시간) 보고서가 궁금하다면 datePreset=TODAY를, 시간대별 데이터가 궁금하다면 dimension=HOUR를 사용합니다.

datePreset의 다른 값들, start, end를 이용한 조회에서 오늘 날짜는 제외됩니다.

start, end의 조회기간은 총 31일 이내 범위로 설정 가능합니다.

이 API는 단건 조회 시 헤더의 광고계정 번호, 다건 조회 시 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.

캠페인 보고서
  • 보고서 조회 기준(dimension) 중 연령, 성별, 연령 및 성별, 지역, 디바이스, 게재지면은 디스플레이 타입일 때만 값이 있습니다.
  • 디스플레이 캠페인만 있는 광고계정의 경우 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
  • 메시지 캠페인만 있는 광고계정의 경우 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
이름설명필수
Authorization인증 방식, 비즈니스 토큰으로 인증 요청
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountId광고계정 ID
단일 광고계정 기준 보고서 조회 시 필수
adAccountId: ${AD_ACCOUNT_ID}
X
이름타입설명필수
adAccountIdLong[]광고계정 번호(최대: 5개)O
datePresetEnum: DatePreset사전 정의된 보고서 조회기간X
timeUnitEnum: TimeUnit보고서 집계 기간 단위

사용 가능한 값:
  • DAY: 일자별로 집계(기본값)
  • ALL: 조회 기간 전체를 하나로 집계

참고: 시간대별 조회는 dimension 필드의 HOUR로 확인 가능
X
startString보고서 조회기간
시작일(yyyyMMdd 형식)
start, end 둘 중에 하나라도 null이면 datePreset 기준으로 조회
datePreset도 명시되지 않았다면 datePresetTODAY 기준으로 조회
시작일은 조회일 전일까지 설정 가능
X
endString보고서 조회기간
종료일(yyyyMMdd 형식)
종료일은 시작일부터 조회일 전일까지 설정 가능
X
levelEnum: Dimension보고서 조회 레벨 기준(기본값: AD_ACCOUNT)

사용 가능한 값:
  • AD_ACCOUNT: 광고계정(ad_account_id)
  • CAMPAIGN: 캠페인(campaign_id)

참고: 보고서 조회 시 데이터가 그룹화될 레벨 기준
X
dimensionEnum: Dimension보고서 조회 기준

사용 가능한 값:
  • CREATIVE_FORMAT: 소재 형식
  • PLACEMENT: 게재지면
  • AGE_BAND: 연령
  • GENDER: 성별
  • AGE_BAND_GENDER: 연령+성별
  • LOCATION: 지역
  • DEVICE_TYPE: 디바이스
  • HOUR: 시간대

참고: 보고서 조회 시 데이터가 그룹화될 기준
X
metricsGroupEnum: MetricsGroup[]보고서 지표 그룹

사용 가능한 값:
  • BASIC: 기본지표
  • ADDITION: 추가지표
  • MESSAGE: 메시지 기본지표
  • MESSAGE_ADDITION: 메시지 추가지표
  • MESSAGE_CLICK: 메시지 클릭지표
  • PLUS_FRIEND: 카카오친구 지표
  • PIXEL_SDK_CONVERSION: 픽셀 & SDK 전환 지표
  • SLIDE_CLICK: 슬라이드 지표
  • VIDEO: 동영상 지표
  • ADVIEW: 애드뷰 지표
  • BIZ_BOARD: 비즈보드 지표
  • SPB: 보드 지표

참고: 보고서 조회 지표를 지정, 그룹별 상세 지표는 타입 정의 표에서 확인 가능
O
이름타입설명
codeInteger에러 코드
messageString결과 안내 메시지
dataData[]각 보고서 상세 데이터
이름타입설명
startString시작일 (yyyyMMdd)
endString종료일 (yyyyMMdd)
dimensionsJSON보고서 기준과 값

참고: 조회 기준에 따라 포함되는 키와 값은 Dimensions 참고
metricsJSON보고서 지표와 값

참고: 요청한 지표 그룹에 따라 포함되는 키와 값은 Metrics 참고
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/report?datePreset=TODAY&level=AD_ACCOUNT&dimension=CREATIVE_FORMAT&metricsGroup=BASIC" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/report?start=20200101&end=20200101&level=AD_ACCOUNT&dimension=CREATIVE_FORMAT&metricsGroup=BASIC" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"ad_account_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/campaigns/report

캠페인에 대한 보고서를 반환합니다.

이 API는 광고계정 번호, 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.

조회 기준 파라미터 및 응답 필드에 대한 자세한 설명은 광고계정 보고서 조회 API를 참고합니다.

캠페인 보고서

스플레이 캠페인은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.

  • 메시지 캠페인은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
이름설명필수
Authorization인증 방식, 비즈니스 토큰으로 인증 요청
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountId광고계정 ID
adAccountId: ${AD_ACCOUNT_ID}
O
이름타입설명필수
campaignIdLong[]캠페인 번호(최대: 5개)
해당 캠페인 번호에 대한 보고서를 조회할 수 있습니다.
O
datePresetEnum: DatePreset사전 정의된 보고서 조회기간X
timeUnitEnum: TimeUnit보고서 집계 기간 단위

사용 가능한 값:
  • DAY: 일자별로 집계(기본값)
  • ALL: 조회 기간 전체를 하나로 집계

참고: 시간대별 조회는 dimension 필드의 HOUR로 확인 가능
X
startString보고서 조회기간
시작일(yyyyMMdd 형식)
start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회
datePreset도 명시되지 않았다면 datePresetTODAY 기준으로 조회
시작일은 조회일 전일까지 설정 가능
X
endString보고서 조회기간
종료일(yyyyMMdd 형식)
종료일은 시작일부터 조회일 전일까지 설정 가능
X
levelEnum: Dimension보고서 조회 레벨 기준(기본값: CAMPAIGN)

사용 가능한 값:
  • CAMPAIGN: 캠페인(campaign_id)
  • AD_GROUP: 광고그룹(ad_group_id)

참고: 보고서 조회 시 데이터가 그룹화될 레벨 기준
X
dimensionEnum: Dimension보고서 조회 기준

사용 가능한 값:
  • CREATIVE_FORMAT: 소재 형식
  • PLACEMENT: 게재지면
  • AGE_BAND: 연령
  • GENDER: 성별
  • AGE_BAND_GENDER: 연령+성별
  • LOCATION: 지역
  • DEVICE_TYPE: 디바이스
  • HOUR: 시간대

참고: 보고서 조회 시 데이터가 그룹화될 기준
X
metricsGroupEnum: MetricsGroup[]보고서 지표 그룹

사용 가능한 값:
  • BASIC: 기본지표
  • ADDITION: 추가지표
  • MESSAGE: 메시지 기본지표
  • MESSAGE_ADDITION: 메시지 추가지표
  • MESSAGE_CLICK: 메시지 클릭지표
  • PLUS_FRIEND: 카카오친구 지표
  • PIXEL_SDK_CONVERSION: 픽셀 & SDK 전환 지표
  • SLIDE_CLICK: 슬라이드 지표
  • VIDEO: 동영상 지표
  • ADVIEW: 애드뷰 지표
  • BIZ_BOARD: 비즈보드 지표
  • SPB: 보드 지표

참고: 보고서 조회 지표를 지정, 그룹별 상세 지표는 타입 정의 표에서 확인 가능
O
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/report?datePreset=TODAY&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&campaignId=11562&level=CAMPAIGN&campaignId=1,2,3,4,5" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/report?start=20200101&end=20200101&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&campaignId=11562&level=CAMPAIGN&campaignId=1,2,3,4,5" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"campaign_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
},
{}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/adGroups/report

광고그룹 보고서를 반환합니다.

이 API는 광고계정 번호, 앱 ID당 1초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 1초 이내로 다시 요청하는 것은 허용되지 않습니다.

조회 기준과 응답 필드는 캠페인 보고서 조회의 조회 기준 및 응답 필드를 참고합니다.

광고그룹 보고서

스플레이 광고그룹은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.

  • 메시지 광고그룹은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
이름설명필수
Authorization인증 방식, 비즈니스 토큰으로 인증 요청
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountId광고계정 ID
adAccountId: ${AD_ACCOUNT_ID}
O
이름타입설명필수
adGroupIdLong[]광고그룹 번호(최대: 40개)
해당 광고그룹 번호에 대한 보고서를 조회할 수 있습니다.
O
datePresetEnum: DatePreset사전 정의된 보고서 조회기간X
timeUnitEnum: TimeUnit보고서 집계 기간 단위

사용 가능한 값:
  • DAY: 일자별로 집계(기본값)
  • ALL: 조회 기간 전체를 하나로 집계

참고: 시간대별 조회는 dimension 필드의 HOUR로 확인 가능
X
startString보고서 조회기간
시작일(yyyyMMdd 형식)
start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회
datePreset도 명시되지 않았다면 datePresetTODAY 기준으로 조회
시작일은 조회일 전일까지 설정 가능
X
endString보고서 조회기간
종료일(yyyyMMdd 형식)
종료일은 시작일부터 조회일 전일까지 설정 가능
X
levelEnum: Dimension보고서 조회 레벨 기준(기본값: AD_GROUP)

사용 가능한 값:
  • AD_GROUP: 광고그룹(ad_group_id)
  • CREATIVE: 소재(creative_id)

참고: 보고서 조회 시 데이터가 그룹화될 레벨 기준
X
dimensionEnum: Dimension보고서 조회 기준

사용 가능한 값:
  • CREATIVE_FORMAT: 소재 형식
  • PLACEMENT: 게재지면
  • AGE_BAND: 연령
  • GENDER: 성별
  • AGE_BAND_GENDER: 연령+성별
  • LOCATION: 지역
  • DEVICE_TYPE: 디바이스
  • HOUR: 시간대

참고: 보고서 조회 시 데이터가 그룹화될 기준
X
metricsGroupEnum: MetricsGroup[]보고서 지표 그룹

사용 가능한 값:
  • BASIC: 기본지표
  • ADDITION: 추가지표
  • MESSAGE: 메시지 기본지표
  • MESSAGE_ADDITION: 메시지 추가지표
  • MESSAGE_CLICK: 메시지 클릭지표
  • PLUS_FRIEND: 카카오친구 지표
  • PIXEL_SDK_CONVERSION: 픽셀 & SDK 전환 지표
  • SLIDE_CLICK: 슬라이드 지표
  • VIDEO: 동영상 지표
  • ADVIEW: 애드뷰 지표
  • BIZ_BOARD: 비즈보드 지표
  • SPB: 보드 지표

참고: 보고서 조회 지표를 지정, 그룹별 상세 지표는 타입 정의 표에서 확인 가능
O
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/report?datePreset=TODAY&level=AD_GROUP&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&adGroupId=15970&adGroupId=1,2,3,4,5" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/report?start=20200501&end=20200501&level=AD_GROUP&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&adGroupId=15970&adGroupId=1,2,3,4,5" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"ad_group_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/creatives/report

소재 보고서를 반환합니다.

한번의 요청으로 최대 100개의 소재 보고서 조회가 가능합니다.

이 API는 광고계정 번호, 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.

조회 기준과 응답 필드는 캠페인 보고서 조회의 조회 기준 및 응답 필드를 참고합니다.

소재 보고서

재 단위의 보고서 요청은 소재 Level만 조회되므로 Level 지정이 별도로 필요 없습니다.

  • 디스플레이 광고 소재는 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
  • 메시지광고 소재는 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
이름설명필수
Authorization인증 방식, 비즈니스 토큰으로 인증 요청
Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
O
adAccountId광고계정 ID
adAccountId: ${AD_ACCOUNT_ID}
O
이름타입설명필수
creativeIdLong[]원본 소재 번호(최대: 100개)
실제 집행 시 활용되는 소재 식별 값
해당 광고소재 번호에 대한 보고서를 조회할 수 있습니다.
O
datePresetEnum: DatePreset사전 정의된 보고서 조회기간X
timeUnitEnum: TimeUnit보고서 집계 기간 단위

사용 가능한 값:
  • DAY: 일자별로 집계(기본값)
  • ALL: 조회 기간 전체를 하나로 집계

참고: 시간대별 조회는 dimension 필드의 HOUR로 확인 가능
X
startString보고서 조회기간
시작일(yyyyMMdd 형식)
start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회
datePreset도 명시되지 않았다면 datePresetTODAY 기준으로 조회
시작일은 조회일 전일까지 설정 가능
X
endString보고서 조회기간
종료일(yyyyMMdd 형식)
종료일은 시작일부터 조회일 전일까지 설정 가능
X
dimensionEnum: Dimension보고서 조회 기준

사용 가능한 값:
  • CREATIVE_FORMAT: 소재 형식
  • PLACEMENT: 게재지면
  • AGE_BAND: 연령
  • GENDER: 성별
  • AGE_BAND_GENDER: 연령+성별
  • LOCATION: 지역
  • DEVICE_TYPE: 디바이스
  • HOUR: 시간대

참고: 보고서 조회 시 데이터가 그룹화될 기준
X
metricsGroupEnum: MetricsGroup[]보고서 지표 그룹

사용 가능한 값:
  • BASIC: 기본지표
  • ADDITION: 추가지표
  • MESSAGE: 메시지 기본지표
  • MESSAGE_ADDITION: 메시지 추가지표
  • MESSAGE_CLICK: 메시지 클릭지표
  • PLUS_FRIEND: 카카오친구 지표
  • PIXEL_SDK_CONVERSION: 픽셀 & SDK 전환 지표
  • SLIDE_CLICK: 슬라이드 지표
  • VIDEO: 동영상 지표
  • ADVIEW: 애드뷰 지표
  • BIZ_BOARD: 비즈보드 지표
  • SPB: 보드 지표

참고: 보고서 조회 지표를 지정, 그룹별 상세 지표는 타입 정의 표에서 확인 가능
O
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/report?datePreset=TODAY&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&creativeId=40068,40065" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/report?start=20200101&end=20200101&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&creativeId=40068,40065" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"creative_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}

도움이 되었나요?

    카카오모먼트 > 보고서 - 카카오디벨로퍼스 | 문서