이 문서는 보고서 API 사용 방법을 안내합니다.
집행한 광고의 결과를 항목별로 구성하여 확인할 수 있는 맞춤화된 보고서로 최근 2년간의 데이터를 제공합니다. 광고계정, 캠페인, 광고그룹, 키워드, 소재별로 구분하여 보고서를 만들 수 있으며, 기본 지표 외에도 전체 노출수, 클릭당비용, 평균노출순위 등 추가 지표도 함께 확인할 수 있습니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adAccounts/report |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | 카카오 로그인 활성화 비즈 앱 |
필요 | - |
광고계정에 대한 보고서를 조회합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 광고계정의 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
metricsGroups | String[] |
보고서 지표 설정 | O |
start | String |
보고서 조회 시작일 (yyyyMMdd) | X |
end | String |
보고서 조회 종료일 (yyyyMMdd) | X |
datePreset | String |
사전 정의된 보고서 조회기간start , end 중에 하나라도 null 이면 datePreset 기준으로 조회datePreset 도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회 |
X |
dimension | String |
보고서 분석 항목(미입력시 NONE 으로 입력) |
X |
timeUnit | String |
보고서 기간단위(미입력시 NONE 으로 입력) |
X |
이름 | 타입 | 설명 |
---|---|---|
start | String |
보고서 시작일 |
end | String |
보고서 종료일 |
dimensions | Dimensions |
보고서 기준과 값 |
metrics | Metrics |
보고서 지표와 값 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/report?metricsGroups=BASIC&start=20210101&end=20210131" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "AdAccountId: {adAccountId}"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111"
},
"metrics": {
"imp": 1000,
"click": 10,
"spending": 700,
"ctr": 10.0
}
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/campaigns/report |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | 카카오 로그인 활성화 비즈 앱 |
필요 | - |
캠페인에 대한 보고서를 조회합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 캠페인 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
metricsGroups | String[] |
보고서 지표 설정 | O |
start | String |
보고서 조회 시작일 (yyyyMMdd) | X |
end | String |
보고서 조회 종료일 (yyyyMMdd) | X |
datePreset | String |
사전 정의된 보고서 조회기간start , end 중에 하나라도 null 이면 datePreset 기준으로 조회datePreset 도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회 |
X |
dimension | String |
보고서 분석 항목(미입력시 NONE 으로 입력) |
X |
timeUnit | String |
보고서 기간단위(미입력시 NONE 으로 입력) |
X |
이름 | 타입 | 설명 |
---|---|---|
start | String |
보고서 시작일 |
end | String |
보고서 종료일 |
dimensions | Dimensions |
보고서 기준과 값 |
metrics | Metrics |
보고서 지표와 값 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/campaigns/report?metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION&start=20210101&end=20210131" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "AdAccountId: {adAccountId}"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331"
},
"metrics": {
"imp": 1000,
"click": 10,
"spending": 700,
"ctr": 10.0,
"rimp": 5000,
"ppc": 70,
"rank": 3,
"convCmptReg1d": 0,
"convCmptReg7d": 0,
"convViewCart1d": 0,
"convViewCart7d": 0,
"convPurchase1d": 0,
"convPurchase7d": 0,
"convPurchaseP1d": 0,
"convPurchaseP7d": 0,
"convParticipation1d": 0,
"convParticipation7d": 0,
"convSignup1d": 0,
"convSignup7d": 0,
"convAppInstall1d": 0,
"convAppInstall7d": 0
}
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adGroups/report |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | 카카오 로그인 활성화 비즈 앱 |
필요 | - |
광고그룹에 대한 보고서를 조회합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 광고그룹 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
campaignId | Long |
캠페인 ID | O |
metricsGroups | String[] |
보고서 지표 설정 | O |
start | String |
보고서 조회 시작일 (yyyyMMdd) | X |
end | String |
보고서 조회 종료일 (yyyyMMdd) | X |
datePreset | String |
사전 정의된 보고서 조회기간start , end 중에 하나라도 null 이면 datePreset 기준으로 조회datePreset 도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회 |
X |
dimension | String |
보고서 분석 항목(미입력시 NONE 으로 입력) |
X |
timeUnit | String |
보고서 기간단위(미입력시 NONE 으로 입력) |
X |
이름 | 타입 | 설명 |
---|---|---|
start | String |
보고서 시작일 |
end | String |
보고서 종료일 |
dimensions | Dimensions |
보고서 기준과 값 |
metrics | Metrics |
보고서 지표와 값 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/adGroups/report?campaignId=3333333331&metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION&start=20210101&end=20210131" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111",
"adGroupId": "4444444441"
},
"metrics": {
"imp": 1000,
"click": 10,
"spending": 700,
"ctr": 10.0,
"rimp": 5000,
"ppc": 70,
"rank": 3,
"convCmptReg1d": 0,
"convCmptReg7d": 0,
"convViewCart1d": 0,
"convViewCart7d": 0,
"convPurchase1d": 0,
"convPurchase7d": 0,
"convPurchaseP1d": 0,
"convPurchaseP7d": 0,
"convParticipation1d": 0,
"convParticipation7d": 0,
"convSignup1d": 0,
"convSignup7d": 0,
"convAppInstall1d": 0,
"convAppInstall7d": 0
}
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/keywords/report |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | 카카오 로그인 활성화 비즈 앱 |
필요 | - |
키워드 보고서를 조회합니다. 액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 키워드 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} 인증 방식, 액세스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
campaignId | Long |
캠페인 ID | O |
adGroupId | Long |
광고그룹 ID | X |
metricsGroups | String[] |
보고서 지표 설정 | O |
start | String |
보고서 조회 시작일 (yyyyMMdd) | X |
end | String |
보고서 조회 종료일 (yyyyMMdd) | X |
datePreset | String |
사전 정의된 보고서 조회기간start , end 중에 하나라도 null 이면 datePreset 기준으로 조회datePreset 도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회 |
X |
dimension | String |
보고서 분석 항목(미입력시 NONE 으로 입력) |
X |
timeUnit | String |
보고서 기간단위(미입력시 NONE 으로 입력) |
X |
이름 | 타입 | 설명 |
---|---|---|
start | String |
보고서 시작일 |
end | String |
보고서 종료일 |
dimensions | Dimensions |
보고서 기준과 값 |
metrics | Metrics |
보고서 지표와 값 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/keywords/report?campaignId=3333333331&adGroupId=4444444441&metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION&start=20210101&end=20210101" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
{
"data": [
{
"start": "2021-01-01",
"end": "2021-01-31",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"adGroupId": "4444444441",
"keywordId": "55555555551"
},
"metrics": {
"imp": 1000,
"click": 10,
"spending": 700,
"ctr": 10.0,
"rimp": 5000,
"ppc": 70,
"rank": 3,
"convCmptReg1d": 0,
"convCmptReg7d": 0,
"convViewCart1d": 0,
"convViewCart7d": 0,
"convPurchase1d": 0,
"convPurchase7d": 0,
"convPurchaseP1d": 0,
"convPurchaseP7d": 0,
"convParticipation1d": 0,
"convParticipation7d": 0,
"convSignup1d": 0,
"convSignup7d": 0,
"convAppInstall1d": 0,
"convAppInstall7d": 0
}
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/creatives/report |
액세스 토큰 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
- | 카카오 로그인 활성화 비즈 앱 |
필요 | - |
소재 보고서를 조회합니다. 광고그룹에 연결된 소재들의 소재연결 ID(creativeLinkId) 데이터별로 조회됩니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 소재 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
Authorization | String |
액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달 |
O |
adAccountId | Long |
광고계정 ID | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
campaignId | Long |
캠페인 ID | O |
adGroupId | Long |
광고그룹 ID | X |
metricsGroups | String[] |
보고서 지표 설정 | O |
start | String |
보고서 조회 시작일 (yyyyMMdd) | X |
end | String |
보고서 조회 종료일 (yyyyMMdd) | X |
datePreset | String |
사전 정의된 보고서 조회기간start , end 중에 하나라도 null 이면 datePreset 기준으로 조회datePreset 도 명시되지 않았다면 datePreset 중 TODAY 기준으로 조회 |
X |
dimension | String |
보고서 분석 항목(미입력시 NONE 으로 입력) |
X |
timeUnit | String |
보고서 기간단위(미입력시 NONE 으로 입력) |
X |
이름 | 타입 | 설명 |
---|---|---|
start | String |
보고서 시작일 |
end | String |
보고서 종료일 |
dimensions | Dimensions |
보고서 기준과 값 |
metrics | Metrics |
보고서 지표와 값 |
curl -X GET "https://api.keywordad.kakao.com/openapi/v1/creatives/report?campaignId=3333333331&adGroupId=4444444441&metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION&start=20210101&end=20210131" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
{
"data": [
{
"start": "2021-01-01",
"end": "2021-01-31",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"adGroupId": "4444444441",
"creativeLinkId": "7777777771"
},
"metrics": {
"imp": 1000,
"click": 10,
"spending": 700,
"ctr": 10.0,
"rimp": 5000,
"ppc": 70,
"rank": 3,
"convCmptReg1d": 0,
"convCmptReg7d": 0,
"convViewCart1d": 0,
"convViewCart7d": 0,
"convPurchase1d": 0,
"convPurchase7d": 0,
"convPurchaseP1d": 0,
"convPurchaseP7d": 0,
"convParticipation1d": 0,
"convParticipation7d": 0,
"convSignup1d": 0,
"convSignup7d": 0,
"convAppInstall1d": 0,
"convAppInstall7d": 0
}
}
]
}