이 문서는 카카오모먼트 보고서 API 사용 방법을 안내합니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/adAccounts/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정에 대한 보고서를 조회합니다. 광고계정 보고서는 디스플레이 캠페인, 메시지 캠페인을 포함한 값을 확인할 수 있습니다. 보고서 지표 그룹(metricsGroup
)은 복수 선택이 가능합니다.
특정 일자에 해당하는 보고서는 그 다음날 오전 8시 이전까지는 변동 가능한 실시간성 지표로 참고합니다. 오늘(실시간) 보고서가 궁금하다면 datePreset=TODAY
를, 시간대별 데이터가 궁금하다면 dimension=HOUR
를 사용합니다.
datePreset
의 다른 값들, start
, end
를 이용한 조회에서 오늘 날짜는 제외됩니다.
start
, end
의 조회기간은 총 31일 이내 범위로 설정 가능합니다.
요청 성공 시 응답은 data
필드 하위에 배열로 보고서 데이터를 포함합니다.
이 API는 단건 조회 시 헤더의 광고계정 번호, 다건 조회 시 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.
1. 보고서 조회 기준(dimension
) 중 연령, 성별, 연령 및 성별, 지역, 디바이스, 게재지면은 디스플레이 타입일 때만 값이 있습니다.
2. 디스플레이 캠페인만 있는 광고계정의 경우 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다.
3. 메시지 캠페인만 있는 광고계정의 경우 기본 지표(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 |
키 | 타입 | 설명 |
---|---|---|
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 ${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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/campaigns/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
캠페인에 대한 보고서를 조회합니다.
이 API는 광고계정 번호, 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.
조회 기준 파라미터 및 응답 필드에 대한 자세한 설명은 광고계정 보고서 보기를 참고합니다.
1. 디스플레이 캠페인은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 2. 메시지 캠페인은 기본 지표(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 |
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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/adGroups/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고그룹 보고서를 조회합니다.
이 API는 광고계정 번호, 앱 ID당 10초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 10초 이내로 다시 요청하는 것은 허용되지 않습니다.
조회 기준 파라미터 및 응답 필드에 대한 자세한 설명은 광고계정 보고서 보기를 참고합니다.
1. 디스플레이 광고그룹은 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 2. 메시지 광고그룹은 기본 지표(BASIC), 추가 지표(ADDITION), 카카오친구 지표(PLUS_FRIEND), 동영상 지표(VIDEO)를 선택하는 경우 값이 없습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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_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 |
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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재 보고서를 조회합니다. 한번의 요청으로 최대 100개의 소재 보고서 조회가 가능합니다.
이 API는 광고계정 번호, 앱 ID당 5초에 한 번으로 요청이 제한됩니다. 마지막 요청 후 5초 이내로 다시 요청하는 것은 허용되지 않습니다.
조회 기준 파라미터 및 응답 필드에 대한 자세한 설명은 광고계정 보고서 보기를 참고합니다.
1. 소재 단위의 보고서 요청은 소재 Level만 조회되므로 Level 지정이 별도로 필요 없습니다. 2. 디스플레이 광고 소재는 메시지 기본 지표(MESSAGE), 메시지 추가 지표(MESSAGE_ADDITION), 메시지 클릭 지표(MESSAGE_CLICK)를 선택하는 경우 값이 없습니다. 3. 메시지광고 소재는 기본 지표(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 |
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": {}
}
]
}