카카오 키워드광고

보고서

이 문서는 보고서 API 사용 방법을 안내합니다.

집행한 광고의 결과를 항목별로 구성하여 확인할 수 있는 맞춤화된 보고서로 최근 2년간의 데이터를 제공합니다. 광고계정, 캠페인, 광고그룹, 키워드, 소재별로 구분하여 보고서를 만들 수 있으며, 기본 지표 외에도 전체 노출수, 클릭당비용, 평균노출순위 등 추가 지표도 함께 확인할 수 있습니다.

광고계정 보고서 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://api.keywordad.kakao.com/openapi/v1/adAccounts/report`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
-	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
-	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
-	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
-	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
-	비즈 앱 전환 비즈니스 인증 리다이렉트 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
      }
    }
  ]
}

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

보고서

광고계정 보고서 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

캠페인 보고서 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

광고그룹 보고서 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

키워드 보고서 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

소재 보고서 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

예제

요청

응답

더 보기

도움이 되었나요?

보고서

광고계정 보고서 조회

캠페인 보고서 조회

광고그룹 보고서 조회

키워드 보고서 조회

소재 보고서 조회

더 보기