이 문서는 보고서 API 사용 방법을 안내합니다.
집행한 광고의 결과를 항목별로 구성하여 확인할 수 있는 맞춤화된 보고서로 최근 2년간의 데이터를 제공합니다. 광고계정, 캠페인, 광고그룹, 키워드, 소재별로 구분하여 보고서를 만들 수 있으며, 기본 지표 외에도 전체 노출수, 클릭당비용, 평균노출순위 등 추가 지표도 함께 확인할 수 있습니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/adAccounts/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고계정에 대한 보고서를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 광고계정의 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adAccounts/report" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d "metricsGroups=BASIC" \
-d "start=20210101" \
-d "end=20210131"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111"
},
"metrics": {
"imp": 105,
"click": 10,
"spending": 700.0,
"ctr": 10.5
}
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://api.keywordad.kakao.com/openapi/v1/campaigns/report |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
캠페인에 대한 보고서를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 캠페인 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 -v -G GET "https://api.keywordad.kakao.com/openapi/v1/campaigns/report" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d "metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION" \
-d "start=20210101" \
-d "end=20210131"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"product": "PREMIUM_LINK"
},
"metrics": {
"imp": 105,
"click": 10,
"spending": 700.0,
"ctr": 10.5,
"rimp": 5000,
"ppc": 70.0,
"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 |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
광고그룹에 대한 보고서를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 광고그룹 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 -v -G GET "https://api.keywordad.kakao.com/openapi/v1/adGroups/report" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d "campaignId=3333333331" \
-d "metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION" \
-d "start=20210101" \
-d "end=20210131"
{
"data": [
{
"start": "20210101",
"end": "20210131",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"adGroupId": "4444444441",
"product": "PREMIUM_LINK"
},
"metrics": {
"imp": 105,
"click": 10,
"spending": 700.0,
"ctr": 10.5,
"rimp": 5000,
"ppc": 70.0,
"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 |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
프리미엄링크 캠페인 유형의 키워드 보고서를 조회합니다. 톡채널검색 캠페인 유형의 키워드 보고서는 제공하지 않습니다. 비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 키워드 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 -v -G GET "https://api.keywordad.kakao.com/openapi/v1/keywords/report" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d "campaignId=3333333331" \
-d "adGroupId=4444444441" \
-d "metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION" \
-d "start=20210101" \
-d "end=20210101"
{
"data": [
{
"start": "2021-01-01",
"end": "2021-01-31",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"adGroupId": "4444444441",
"keywordId": "55555555551",
"product": "PREMIUM_LINK"
},
"metrics": {
"imp": 105,
"click": 10,
"spending": 700.0,
"ctr": 10.5,
"rimp": 5000,
"ppc": 70.0,
"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 |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
- | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재 보고서를 조회합니다. 광고그룹에 연결된 소재들의 소재연결 ID(creativeLinkId) 데이터별로 조회됩니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON 객체로 소재 보고서를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_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 -v -G GET "https://api.keywordad.kakao.com/openapi/v1/creatives/report" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-d "campaignId=3333333331" \
-d "&adGroupId=4444444441" \
-d "metricsGroups=BASIC,ADDITION,PIXEL_SDK_CONVERSION" \
-d "start=20210101" \
-d "end=20210131"
{
"data": [
{
"start": "2021-01-01",
"end": "2021-01-31",
"dimensions": {
"adAccountId": "1111111111",
"campaignId": "3333333331",
"adGroupId": "4444444441",
"creativeLinkId": "7777777771",
"product": "PREMIUM_LINK"
},
"metrics": {
"imp": 105,
"click": 10,
"spending": 700.0,
"ctr": 10.5,
"rimp": 5000,
"ppc": 70.0,
"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
}
}
]
}