페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 보고서

카카오모먼트

보고서

이 문서는 카카오모먼트 보고서 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 필드 하위에 배열로 보고서 데이터를 포함합니다.

보고서 조회 기준(dimension) 중 연령, 성별, 연령 및 성별, 지역, 디바이스, 게재지면은 디스플레이 타입일 때만 값이 있습니다.

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

메시지 캠페인만 있는 광고계정의 경우 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
쿼리 파라미터
이름 타입 설명 필수
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, GENDER, AGE_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

응답

본문
키 타입 설명
code Integer 응답 코드
message String 결과 안내 메시지
data Data[] 각 보고서 상세 데이터
Data
키 타입 설명
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 ${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 ${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초 이내로 다시 요청하는 것은 허용되지 않습니다.

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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, GENDER, AGE_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 ${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 ${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": {}
        }
    ]
}
주의: 캠페인 보고서

1. 디스플레이 캠페인은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 2. 메시지 캠페인은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다. 3. 그 외 자세한 설명은 광고계정 보고서 조회를 참고합니다.

광고그룹 보고서 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adGroups/report 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈앱		 필요 -

광고그룹 보고서를 조회합니다.

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
adGroupId Long[] 광고그룹 번호
해당 광고그룹 번호에 대한 보고서가 조회
최대 20개까지 조회 가능		 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, GENDER, AGE_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 ${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 ${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": {}
        }
    ]
}
주의: 광고그룹 보고서

1. 디스플레이 광고그룹은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 2. 메시지 광고그룹은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다. 3. 그 외 자세한 설명은 광고계정 보고서 조회를 참고합니다.

소재 보고서 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/creatives/report 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈앱		 필요 -

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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, GENDER, AGE_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 ${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 ${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": {}
        }
    ]
}
주의: 소재 보고서

1. 소재 단위의 보고서 요청은 소재 Level만 조회되므로 Level 지정이 별도로 필요 없습니다. 2. 디스플레이 광고 소재는 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 3. 메시지 광고 소재는 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.

더 보기

카카오모먼트> 보고서