이 문서는 카카오모먼트 보고서 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[] |
각 보고서 상세 데이터 |
키 | 타입 | 설명 |
---|---|---|
start | String |
시작일 (yyyyMMdd) |
end | String |
종료일 (yyyyMMdd) |
dimensions | Dimension |
보고서 기준과 값 |
metrics | 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 ${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 ${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 |
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}"
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 |
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}"
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 |
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}"
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)를 선택하는 경우 값이 없습니다.