사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
보고서
이 문서는 카카오모먼트 보고서 API 사용 방법을 안내합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/adAccounts/report | 비즈니스 토큰 |
광고계정에 대한 보고서를 조회합니다.
광고계정 보고서는 디스플레이 캠페인, 메시지 캠페인을 포함한 값을 확인할 수 있습니다. 보고서 지표 그룹(metricsGroup)은 복수 선택이 가능합니다.
특정 일자에 해당하는 보고서는 그 다음날 오전 8시 이전까지는 변동 가능한 실시간성 지표로 참고합니다. 오늘(실시간) 보고서가 궁금하다면 datePreset=TODAY를, 시간대별 데이터가 궁금하다면 dimension=HOUR를 사용합니다.
datePreset의 다른 값들, start, end를 이용한 조회에서 오늘 날짜는 제외됩니다.
start, end의 조회기간은 총 31일 이내 범위로 설정 가능합니다.
요청 성공 시 응답은 data 필드 하위에 배열로 보고서 데이터를 포함합니다.
이 API는 단건 조회 시 헤더의 광고계정 번호, 다건 조회 시 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.
- 보고서 조회 기준(
dimension) 중 연령, 성별, 연령 및 성별, 지역, 디바이스, 게재지면은 디스플레이 타입일 때만 값이 있습니다. - 디스플레이 캠페인만 있는 광고계정의 경우 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
- 메시지 캠페인만 있는 광고계정의 경우 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID 단일 광고계정 기준 보고서 조회 시 필수 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| adAccountId | Long[] | 광고계정 번호 최대 5개까지 한번에 조회 가능 | O |
| datePreset | DatePreset | 사전 정의된 보고서 조회기간 사용 가능한 값: TODAY, YESTERDAY, LAST_7DAY, LAST_14DAY, LAST_30DAY, THIS_MONTH, LAST_MONTH | X |
| timeUnit | TimeUnit | 보고서 집계 기간 단위 사용 가능한 값: DAY(기본값)참고: 시간대별 조회는 dimension 필드의 HOUR를 이용하여 확인 가능합니다. | X |
| start | String | 보고서 조회기간 시작일( yyyyMMdd 형식)start, end 둘 중에 하나라도 null이면 datePreset 기준으로 조회됩니다.datePreset도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회됩니다.시작일은 조회일 전일까지 설정 가능합니다. | X |
| end | String | 보고서 조회기간 종료일( yyyyMMdd 형식)종료일은 시작일부터 조회일 전일까지 설정 가능합니다. | X |
| level | Dimension | 보고서 조회 레벨 기준 보고서 조회시 데이터가 그룹화될 레벨 기준을 지정합니다. 광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다. 사용 가능한 값: AD_ACCOUNT, CAMPAIGN(기본값: AD_ACCOUNT) | O |
| dimension | Dimension | 보고서 조회 기준 보고서 조회시 데이터가 그룹화 될 기준을 지정합니다. 사용 가능한 값: CREATIVE_FORMAT, PLACEMENT, AGE_BAND, GENDER, AGE_BAND_GENDER, LOCATION, DEVICE_TYPE, HOUR | X |
| metricsGroup | MetricsGroup | 보고서 지표 그룹 보고서 조회 지표들을 지정합니다. 지표 그룹별 상세 지표 리스트는 타입 정보의 MetricGroup을 참고합니다.사용 가능한 값: BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_SDK_CONVERSION, SLIDE_CLICK, VIDEO, ADVIEW, BIZ_BOARD, SPB | O |
| 키 | 타입 | 설명 |
|---|---|---|
| start | String | 시작일 (yyyyMMdd) |
| end | String | 종료일 (yyyyMMdd) |
| dimensions | Dimension | 보고서 기준과 값 |
| metrics | Metrics | 보고서 지표와 값 |
요청: datePreset 지정
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}"
요청: datePreset 미지정
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 | 인증 방식 |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/campaigns/report | 비즈니스 토큰 |
캠페인에 대한 보고서를 조회합니다.
이 API는 광고계정 번호, 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.
조회 기준 파라미터 및 응답 필드에 대한 자세한 설명은 광고계정 보고서 조회를 참고합니다.
스플레이 캠페인은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
- 메시지 캠페인은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| campaignId | Long[] | 캠페인 번호 해당 캠페인 번호에 대한 보고서를 조회할 수 있습니다. 최대 5개까지 한번에 조회 가능합니다. | O |
| datePreset | DatePreset | 사전 정의된 보고서 조회기간 사용 가능한 값: TODAY, YESTERDAY, LAST_7DAY, LAST_14DAY, LAST_30DAY, THIS_MONTH, LAST_MONTH | X |
| timeUnit | TimeUnit | 보고서 집계 기간 단위 사용 가능한 값: DAY(기본값)참고: 시간대별 조회는 dimension 필드의 HOUR를 이용하여 확인 가능합니다. | X |
| start | String | 보고서 조회기간 시작일( yyyyMMdd 형식)start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회됩니다. datePreset도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회됩니다.시작일은 조회일 전일까지 설정 가능합니다. | X |
| end | String | 보고서 조회기간 종료일( yyyyMMdd 형식)종료일은 시작일부터 조회일 전일까지 설정 가능합니다. | X |
| level | Dimension | 보고서 조회 레벨 기준 보고서 조회시 데이터가 그룹화 될 레벨 기준을 지정합니다. 광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다. 사용 가능한 값: CAMPAIGN, AD_GROUP(기본값: CAMPAIGN) | O |
| dimension | Dimension | 보고서 조회 기준 보고서 조회시 데이터가 그룹화 될 기준을 지정합니다. 사용 가능한 값: CREATIVE_FORMAT, PLACEMENT, AGE_BAND, GENDER, AGE_BAND_GENDER, LOCATION, DEVICE_TYPE, HOUR | X |
| metricsGroup | MetricsGroup | 보고서 지표 그룹 보고서 조회 지표들을 지정합니다. 지표 그룹별 상세 지표 리스트는 타입 정보의 MetricGroup을 참고합니다.사용 가능한 값: BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_SDK_CONVERSION, SLIDE_CLICK, VIDEO, ADVIEW, BIZ_BOARD, SPB | O |
요청: datePreset 지정
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}"
요청: datePreset 미지정
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 | 인증 방식 |
|---|---|---|
GET | https://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 | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| adGroupId | Long[] | 광고그룹 번호 해당 광고그룹 번호에 대한 보고서를 조회할 수 있습니다. 최대 40개까지 한번에 조회 가능합니다. | O |
| datePreset | DatePreset | 사전 정의된 보고서 조회기간 사용 가능한 값: TODAY, YESTERDAY, LAST_7DAY, LAST_14DAY, LAST_30DAY, THIS_MONTH, LAST_MONTH | X |
| timeUnit | TimeUnit |
DAY(기본값)참고: 시간대별 조회는 dimension 필드의 HOUR를 이용하여 확인 가능합니다. | X |
| start | String | 보고서 조회기간 시작일( yyyyMMdd 형식)start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회됩니다. datePreset도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회됩니다.시작일은 조회일 전일까지 설정 가능합니다. | X |
| end | String | 보고서 조회기간 종료일( yyyyMMdd 형식)종료일은 시작일부터 조회일 전일까지 설정 가능합니다. | X |
| level | Dimension | 보고서 조회 레벨 기준 보고서 조회시 데이터가 그룹화 될 레벨 기준을 지정합니다. 광고계정 레벨의 보고서에서는 광고계정 혹은 광고계정 하위의 캠페인별 보고서 조회가 가능합니다. 사용 가능한 값: AD_GROUP, CREATIVE(기본값: AD_GROUP) | O |
| dimension | Dimension | 보고서 조회 기준 보고서 조회시 데이터가 그룹화 될 기준을 지정합니다. 사용 가능한 값: CREATIVE_FORMAT, PLACEMENT, AGE_BAND, GENDER, AGE_BAND_GENDER, LOCATION, DEVICE_TYPE, HOUR | X |
| metricsGroup | MetricsGroup | 보고서 지표 그룹 보고서 조회 지표들을 지정합니다. 지표 그룹별 상세 지표 리스트는 타입 정보의 MetricGroup을 참고합니다.사용 가능한 값: BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_SDK_CONVERSION, SLIDE_CLICK, VIDEO, ADVIEW, BIZ_BOARD, SPB | O |
요청: datePreset 지정
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}"
요청: datePreset 미지정
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 | 인증 방식 |
|---|---|---|
GET | https://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 | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| creativeId | Long[] | 원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 해당 광고소재 번호에 대한 보고서를 조회할 수 있습니다. 최대 100개까지 조회 가능합니다. | O |
| datePreset | DatePreset | 사전 정의된 보고서 조회기간 사용 가능한 값: TODAY, YESTERDAY, LAST_7DAY, LAST_14DAY, LAST_30DAY, THIS_MONTH, LAST_MONTH | X |
| timeUnit | TimeUnit | 보고서 집계 기간 단위 사용 가능한 값: DAY(기본값)참고: 시간대별 조회는 dimension 필드의 HOUR를 이용하여 확인 가능합니다. | X |
| start | String | 보고서 조회기간 시작일( yyyyMMdd 형식)start, end 둘중에 하나라도 null이면 datePreset 기준으로 조회됩니다. datePreset도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회됩니다.시작일은 조회일 전일까지 설정 가능합니다. | X |
| end | String | 보고서 조회기간 종료일( yyyyMMdd 형식)종료일은 시작일부터 조회일 전일까지 설정 가능합니다. | X |
| dimension | Dimension | 보고서 조회 기준 보고서 조회시 데이터가 그룹화 될 기준을 지정합니다. 사용 가능한 값: CREATIVE_FORMAT, PLACEMENT, AGE_BAND, GENDER, AGE_BAND_GENDER, LOCATION, DEVICE_TYPE, HOUR | X |
| metricsGroup | MetricsGroup | 보고서 지표 그룹 보고서 조회 지표들을 지정합니다. 지표 그룹별 상세 지표 리스트는 타입 정보의 MetricGroup을 참고합니다.사용 가능한 값: BASIC, ADDITION, MESSAGE, MESSAGE_ADDITION, MESSAGE_CLICK, PLUS_FRIEND, PIXEL_SDK_CONVERSION, SLIDE_CLICK, VIDEO, ADVIEW, BIZ_BOARD, SPB | O |
요청: datePreset 지정
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}"
요청: datePreset 미지정
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": {}}]}