FAQ - naver/searchad-apidoc GitHub Wiki

여러 광고주에게 권한을 위임받은 계정의 엑세스 라이선스와 비밀키로 검색광고 API를 통해 해당 광고주들의 광고를 관리하실 수 있습니다. 이때 특정 광고주에게 제공한 애플리케이션에서는 다른 광고주의 정보가 노출되어서는 안됩니다.

네이버 검색광고 API 이용약관에서 액세스 라이선스와 비밀키는 제3자에게 전달하는 것을 금지하고 있습니다. 따라서 권한 위임을 받은 계정을 통해 API 를 사용해야 합니다.

https://saedu.naver.com/adguide/policy/api.nhn#step5

제 5 조 (사용자 액세스 라이선스 및 비밀키 관리 의무) +
① "액세스 라이선스"와 "비밀키"에 대한 관리책임은 "사용자"에게 있습니다. +
② "액세스 라이선스"와 "비밀키"는 제 3자에게 전달 하여서는 안 되며 제 3자의 이용에 따른 모든 불이익과 분쟁에 대하여 "회사"는 책임을 지지 않습니다.

네이버 검색광고 API는 호출량에 대한 제한은 없습니다. 하지만
광고주별 호출 속도 제한은 있습니다.
단 특정숫자가 정해진것은 아니고 초 단위 이하에서 측정합니다.
횟수는 Customer id 기준이며 연관키워드의 api의 경우 ip도 포함됩니다.
속도는 저희 시스템이 현재 시스템 사용량을 판단하여 실시간으로 설정하고 있어 정확한 수를 특정하기는 어렵습니다.
호출 속도 초과 시 HTTP 429 Too Many Requests 응답을 받을 수 있으며, 이 경우 잠시 후 다시 시도하시면 됩니다.

요일별로 매시간에 대한 타게팅 여부를 1 bit의 값으로 0(타게팅 하지 않음) 또는 1(타게팅)로 표현하도록 하고 있습니다.
0~1시간은 0 번째 bit 값을 사용하며, 1~2시간은 1번째 bit 값, …​. 22~23시간은 22번째 bit 값, 23~24시간은 23번째 bit 값을 사용합니다. (0 ~ 23의 번째의 bit를 가짐)
시간 타게팅 값의 범위는 0 (타게팅 없음) ~ 16777215(모든 시간대)입니다.
요일별로 타게팅 하고 싶은 시간대의 bit 위치를 모두 1로 설정한 다음 해당 integer 값을 타게팅 숫자 값으로 넣어주시면 됩니다.

java 코드를 참고하시기 바랍니다.

매체 타게팅과 관련해서는 노출 매체 유형 중에 상위 매체로는 검색 매체와 콘텐츠 매체가 존재하며, 각 상위 매체별 하위 매체로는 네이버 매체와 파트너 매체로 구분됩니다. 타게팅 설정을 통해 원하는 매체를 선택하면, 해당 매체에만 광고가 노출됩니다.

HTTP Response Status : 403 Forbidden

해당 오류는 요청 메시지에 포함된 X-Timestamp 값이 기준 시간 이상 차이날 경우에 발생합니다.

주로 timestamp 값을 생성하고 실제 호출하기까지 오래걸리거나,
클라이언트의 시간이 표준 시간 서버와 동기화가 제대로 안되어있을 경우에 발생합니다.

우선 아래 문서에 있는 시간 서버 또는 공개된 다른 시간 서버와 NTP 시간 동기화를 하시기 바랍니다.
http://time.ewha.or.kr/domestic.html

이후에도 동일한 오류가 발생할 경우에는 X-Timestamp 를 최대한 호출 직전에 생성하도록 하거나 네트워크 지연이 있는지 확인해볼 필요가 있습니다.

광고주가 설정할 수 있는 타겟팅은 아래의 9가지가 있습니다.

• 요일 시간 타겟팅 (TIME_WEEKLY_TARGET)

• 지역 타겟팅 (REGIONAL_TARGET)

• 매체 타겟팅 (MEDIA_TARGET)

• PC/Mobile 타겟팅 (PC_MOBILE_TARGET)

• 노출 제한 키워드 타겟팅 (RESTRICT_KEYWORD_TARGET)

• 검색어 없는 경우 광고 노출 제외 타겟팅 (NON_SEARCH_KEYWORD_TARGET)

• 성별 타겟팅 (GENDER_TARGET)

• 기간 타겟팅 (PERIOD_TARGET)

• 광고 태그 타겟팅 (AD_TAG)

타겟팅은 기본 적으로 그룹에 적용되지만 몇몇 타겟팅은 캠페인 유형별 특정 그룹, 소재에 적용됩니다.

타겟팅	대상 캠페인
요일 시간 타겟팅 (TIME_WEEKLY_TARGET)	파워링크, 플레이스, 파워 컨텐츠, 쇼핑 캠페인
지역 타겟팅 (REGIONAL_TARGET)	파워링크, 플레이스, 파워 컨텐츠
매체 타겟팅 (MEDIA_TARGET)	파워링크, 파워 컨텐츠, 쇼핑 캠페인
PC/Mobile 타겟팅 (PC_MOBILE_TARGET)	파워링크, 파워 컨텐츠, 쇼핑 캠페인
노출 제한 키워드 타겟팅 (RESTRICT_KEYWORD_TARGET)	쇼핑 캠페인 (제외 키워드)
검색어 없는 경우 광고 노출 제외 타겟팅 (NON_SEARCH_KEYWORD_TARGET)	쇼핑 캠페인 (제외 키워드)
성별 타겟팅 (GENDER_TARGET)	플레이스

타겟팅	대상 캠페인	등록 가능 대상
노출 제한 키워드 타겟팅 (RESTRICT_KEYWORD_TARGET)	쇼핑 캠페인	소재 (제외 키워드)
검색어 없는 경우 광고 노출 제외 타겟팅 (NON_SEARCH_KEYWORD_TARGET)	쇼핑 캠페인	소재 (제외 키워드)
광고 태그 타겟팅 (AD_TAG)	쇼핑 캠페인	소재 (태그)
요일 시간 타겟팅 (TIME_WEEKLY_TARGET)	브랜드 검색	소재
기간 타겟팅 (PERIOD_TARGET)	브랜드 검색	소재

키워드 확장 Beta 는 광고그룹의 설정을 수정하여 사용과 미사용을 적용할 수 있습니다. 광고 그룹에서 키워드 확장 Beta 와 관련된 프로퍼티는 다음과 같습니다.

키워드 확장 Beta 기능의 수정 (사용, 미사용, 입찰가 가중치 변경)은 Adgroup update (by fields) API를 이용합니다.

캠페인 유형별 등록 가능한 그룹의 유형은 아래와 같습니다.

네이버 검색광고 API에서 제공해 드리는 각 항목의 status, statusReason 은 다음과 같이 계산이 됩니다. 경우에 따라 상위 항목의 상태값을 같이 확인해야 할 필요가 있습니다.

문자열 코드와 숫자형 코드는 아래와 같이 연결이 됩니다.

• 캠페인 유형

• 광고그룹 유형

• 비즈채널 유형

• 광고소재 유형

확장소재 코드와 숫자형 코드는 아래와 같이 연결이 되며, 캠페인별로 사용가능한 확장소재 유형도 명시하였습니다.

• 확장소재 유형

• 쇼핑검색의 노출 제외 키워드는 아래링크의 Target API를 이용 합니다.

• http://naver.github.io/searchad-apidoc/#/tags/Target

• targetTp값으로 RESTRICT_KEYWORD_TARGET, NON_SEARCH_KEYWORD_TARGET 값을 입력합니다.

• ownerId에 광고그룹의 ID를 입력 합니다.

• 광고그룹은 쇼핑 캠페인에 속한 광고그룹에 유효합니다.

  {
  	"ownerId": "grp-a001-02-XXXXXX",
  	"targetTp": "RESTRICT_KEYWORD_TARGET",
  	"nccTargetId": "tgt-a001-02-XXXXX",
  	"target": [{"keyword": "대출"}, {"keyword": "꽃배달"}],
  	"delFlag": false,
  	"regTm": "2023-01-13T02:03:03.000Z",
  	"editTm": "2023-01-13T02:03:03.000Z"
  }

• ownerId에 소재의 ID를 입력 합니다.

• 소재는 쇼핑 캠페인에 속한 광고그룹의 소재입니다.

  {
  	"ownerId": "nad-a001-02-XXXXX",
  	"targetTp": "RESTRICT_KEYWORD_TARGET",
  	"nccTargetId": "tgt-a001-02-XXXXX",
  	"target": [{"keyword": "대출"}, {"keyword": "꽃배달"}],
  	"delFlag": false,
  	"regTm": "2023-01-13T02:03:03.000Z",
  	"editTm": "2023-01-13T02:03:03.000Z"
  }

• 위의 추가 요청에서 제거하고자 하는 키워드를 빼고 요청하시면 됩니다. (이 요청에서 키워드가 빠지면 서버에서 이미 등록된 키워드가 있을 경우 제거 합니다.)

  {
  	"nccTargetId": "tgt-a001-02-XXXX",
  	"ownerId": "grp-a001-02-XXXX",
  	"targetTp": "RESTRICT_KEYWORD_TARGET",
  	"target": [{
  		"keyword": "꽃배달",
  		"date": 1682300721
  	}],
  	"delFlag": false,
  	"regTm": "2023-01-13T02:03:03.000Z",
  	"editTm": "2023-04-24T01:45:21.000Z"
  }

• 광고주별 캠페인용 공유예산은 최대 20개까지 생성가능합니다.

• 광고주별 광고그룹용 공유예산은 최대 20개까지 생성가능합니다.

• 캠페인용 공유예산에 포함되는 캠페인의 개수는 최대 200개까지 입니다.

• 광고그룹용 공유예산에 포함되는 광고그룹의 개수는 최대 200개까지 입니다.

• 공통 부분

  {
      "nccAdId": "소재의 고유 번호(문자열)",
      "nccAdgroupId": "광고그룹의 고유 번호(문자열)",
      "customerId": 광고 계정 번호(숫자),
      "inspectStatus": "검수 상태 코드",
      "type": "광고소재 유형",
      "ad": {/* 광고소재 정보 */},
      "adAttr": {/* 광고소재 속성 */},
      "userLock": false, /* 광고주의 노출 중지 설정 여부 */
      "enable": true, /* 검색광고 외부 연동시 상태값 */
      "status": "소재의 계산된 상태 코드",
      "statusReason": "소재의 계산된 상태 이유 코드",
      "referenceKey": "검색광고 외부 연동시 키값(ex. 쇼핑의 경우 nvmid, 네이버 플레이스 고유번호 등)"
  }

• TEXT_45 파워링크 단일형 소재 ad 프로퍼티 JSON 예제

  {
    "description": "노출 광고소재의 설명 부분",
    "headline": "노출 광고소재의 제목 부분",
    "mobile": {
        "display": "http://www.naver.com(PC 표시 URL)",
        "final": "http://www.naver.com(PC 랜딩 페이지 URL)"
    },
    "pc": {
        "display": "http://www.naver.com(모바일 표시 URL)",
        "final": "http://www.naver.com(모바일 랜딩 페이지 URL)"
    }
  }

• TEXT_45 파워링크 단일형 소재 adAttr 프로퍼티 JSON 예제

  {}

• SHOPPING_PRODUCT_AD 쇼핑 검색 상품형 소재 ad 프로퍼티 JSON 예제

- SHOPPING_PRODUCT_AD 쇼핑 검색 상품형 소재 adAttr 프로퍼티 JSON 예제

• CONTENTS_AD_INFORMATION 파워컨텐츠 소재 ad 프로퍼티 JSON 예제

  {
      "companyName": "업체명",
      "contentImages": ["컨텐츠 이미지 목록"],
      "contentIssueDate": "컨텐츠 발행일",
      "description": "광고소재 설명",
      "headline": "광고소재 제목",
      "imageHeight": 노출용 이미지 높이(숫자),
      "imagePath": "노출용 이미지",
      "imageWidth": 노출용 이미지 너비(숫자),
      "mobile": {
          "display": "http://www.naver.com(PC 표시 URL)",
          "final": "http://www.naver.com(PC 랜딩 페이지 URL)"
      },
      "pc": {
          "display": "http://www.naver.com(PC 표시 URL)",
          "final": "http://www.naver.com(PC 랜딩 페이지 URL)"
      },
      "representImage": 대표이미지 인덱스(숫자),
      "useContentImage": "컨텐츠 이미지 사용여부(Y/N)",
      "profileImgUrlOrg": "프로필 이미지",
      "useProfileImage": "프로필 이미지 사용여부(Y/N)",
      "medicalNo": "의료 심의 번호",
      "assets": 반응형 소재에만 존재
  }

• CONTENTS_AD_INFORMATION 파워컨텐츠 소재 adAttr 프로퍼티 JSON 예제

  {}

• BRAND_SEARCH_AD 브랜드 검색 | 일반형 소재, 브랜드존 소재 ad 프로퍼티 JSON 예제

  {
      "dittoId": "광고소재 저장소 고유 번호",
      "thumbnail": "광고소재 썸네일"
  }

• BRAND_SEARCH_AD 파워컨텐츠 소재 adAttr 프로퍼티 JSON 예제

  {}

• PLACE_AD 지역소상공인 소재 ad 프로퍼티 JSON 예제

  {}

• PLACE_AD 지역소상공인 소재 adAttr 프로퍼티 JSON 예제

  {}

• CATALOG_AD 쇼핑 검색 카탈로그형 소재 ad 프로퍼티 JSON 예제

  {
      "imagePath": "이미지 패스",
      "catalogType": "MAKER",
      "imageHeight": "이미지 높이",
      "imageWidth": "이미지 너비",
      "imageColorCode": "컬러 코드"
  }

• CATALOG_AD 쇼핑 검색 카탈로그형 소재 adAttr 프로퍼티 JSON 예제

  {
      "bidAmt": 입찰가(숫자, 그룹 입찰가 사용시 무시됨),
      "useGroupBidAmt": 그룹 입찰가 사용 여부(boolean)
  }

• LOCAL_AD 플레이스 검색 소재 ad 프로퍼티 JSON 예제

  {
      "description": "광고소재 설명",
      "images": [이미지 목록],
      "info": {
          "address": "주소",
          "localCategoryName": "업종명",
          "name": "업체 이름",
          "openingHours": [
              "매일 11:30~22:00",
              "매일 14:30~17:30 Break time"
          ],
          "sid": "네이버 플레이스 고유번호"
      },
      "medicalNo": "의료심의 번호"
  }

• LOCAL_AD 플레이스 검색 소재 adAttr 프로퍼티 JSON 예제

  {}

• SHOPPING_BRAND_IMAGE_THUMBNAIL_AD 쇼핑 검색 이미지 섬네일형 소재 ad 프로퍼티 JSON 예제

  {
      "description": "광고소재의 설명 문구",
      "extraDescription": "광고소재의 추가 설명 문구",
      "headline": "광고소재의 제목 문구",
      "image": "이미지 패스",
      "landingUrl": "랜딩 페이지 URL",
      "logoImage": "로고 이미지 패스"
  }

• SHOPPING_BRAND_IMAGE_THUMBNAIL_AD 쇼핑 검색 이미지 섬네일형 소재 adAttr 프로퍼티 JSON 예제

  {}

• SHOPPING_BRAND_IMAGE_BANNER_AD 쇼핑 검색 이미지 배너형 소재 ad 프로퍼티 JSON 예제

  {
      "description": "광고소재의 설명 문구",
      "headline": "광고소재의 제목 문구",
      "image": "이미지 패스",
      "logoImage": "로고 이미지 패스"
  }

• SHOPPING_BRAND_IMAGE_BANNER_AD 쇼핑 검색 이미지 배너형 소재 adAttr 프로퍼티 JSON 예제

  {}

• BRAND_SEARCH_NEW_AD 브랜드 검색 신제품 검색형 소재 ad 프로퍼티 JSON 예제

  {
      "dittoId": "소재 저장소 고유 번호",
      "thumbnail": "소재 썸네일",
      "productReleaseDate": "제품 출시일"
  }

• BRAND_SEARCH_NEW_AD 브랜드 검색 신제품 검색형 소재 ad 프로퍼티 JSON 예제

  {}

• RSA_AD 파워링크 반응형 소재 ad 프로퍼티 JSON 예제

  {
    "description": "노출 광고소재의 설명 부분",
    "headline": "노출 광고소재의 제목 부분",
    "mobile": {
        "display": "http://www.naver.com(PC 표시 URL)",
        "final": "http://www.naver.com(PC 랜딩 페이지 URL)"
    },
    "pc": {
        "display": "http://www.naver.com(모바일 표시 URL)",
        "final": "http://www.naver.com(모바일 랜딩 페이지 URL)"
    }
  }

• RSA_AD 파워링크 반응형 소재 adAttr 프로퍼티 JSON 예제

  {}

• RSA_AD 파워링크 반응형 소재 assets 프로퍼티 JSON 예제

  {
      "nccAssetId": "애셋 고유 번호",
      "customerId": 광고 계정 번호,
      "assetType": "애셋 유형 코드",
      "assetData": {
          "text": "애셋 데이터"
      },
      "inspectStatus": "검수 상태 코드",
      "nccAdId": "광고소재 고유번호",
      "linkType": "링크 유형"
  }