페이지 이동경로
  • 문서>
  • 카카오 키워드광고>
  • 보고서

카카오 키워드광고

보고서

이 문서는 보고서 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도 명시되지 않았다면 datePresetTODAY 기준으로 조회
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도 명시되지 않았다면 datePresetTODAY 기준으로 조회
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도 명시되지 않았다면 datePresetTODAY 기준으로 조회
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도 명시되지 않았다면 datePresetTODAY 기준으로 조회
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도 명시되지 않았다면 datePresetTODAY 기준으로 조회
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
      }
    }
  ]
}

더 보기