메인 콘텐츠로 건너뛰기
LinkedIn 광고 라이브러리를 비동기 task API로 읽어 경쟁사가 전문가를 대상으로 어떤 광고를 하는지 JSON으로 받습니다. ADS는 자기 엔진입니다. taskType ADS에 platform linkedin_ad_library를 보내고, action으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
  • search(기본값)는 query의 키워드, advertiserName의 광고주 이름, payer의 광고비를 낸 주체, 또는 이들의 조합으로 광고를 나열합니다. 광고마다 광고주, 형식, 제목, 문구, 미디어가 있고, 응답 끝에는 받은 광고를 요약한 summary가 붙습니다.
  • ad는 광고 하나를 엽니다. 광고주, 광고비를 낸 주체, 랜딩 페이지와 함께, 라이브러리가 공개하는 경우 게재 기간, 노출 수, 도달한 국가, 타기팅을 돌려줍니다.
라이브러리에는 광고주 조회가 없으므로 action advertisers는 400 VALIDATION_ERROR로 거절합니다. 경쟁사는 검색의 advertiserName으로 찾습니다. 검색은 받은 광고 30개마다 0.5크레딧입니다. ad는 0.5크레딧입니다.

요청

task를 제출한 뒤 GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task. 라이브러리가 읽는 속도를 제한하므로 광고 120개 검색은 약 30초가 걸립니다.

경쟁사 광고 분석

요청 세 개로 경쟁사 분석을 마칩니다.
  1. 경쟁사 이름을 advertiserName에 넣어 search를 보내 광고를 나열합니다. advertiserName은 이름의 일부와 맞으므로 광고마다 advertiserName을 확인합니다. query를 더해 광고를 한 주제로 좁히고, sortBy oldest로 가장 오래된 광고부터 봅니다.
  2. 광고의 libraryId로 ad를 보내 광고비를 낸 주체, 랜딩 페이지를 받고, EU에 노출된 광고는 게재 기간, 노출 수, 타기팅도 받습니다.
  3. payer로 search를 보내 에이전시나 회사가 어느 페이지에서 내든 비용을 낸 광고를 나열합니다.

입력

  • action: search(기본값), ad.
  • query: 광고 문구의 키워드. search에는 query, advertiserName, payer 중 하나가 필요합니다.
  • advertiserName: 이름. 광고주 이름의 일부와 맞춥니다(예: samsung).
  • payer: 광고비를 낸 주체의 이름. 이름의 일부와 맞춥니다(예: Starcom).
  • libraryId: 광고의 숫자 ID(예: 1638962914). ad에 필수입니다.
  • country: 광고가 게재된 국가의 2글자 코드, 또는 모든 국가를 뜻하는 ALL(기본값).
  • startDate, endDate: YYYY-MM-DD. 함께 보내며 최근 1년 안이어야 합니다. 두 날짜 사이에 노출된 광고를 남깁니다.
  • sortBy: newest(기본값), oldest.
  • limit: 광고 1-120개. 기본값은 30입니다.
  • cursor: 이전 응답의 nextCursor. 그 뒤의 광고를 이어서 받습니다.
search는 libraryId를 뺀 위의 모든 필드를 읽고, ad는 libraryId만 읽습니다. Meta 광고 라이브러리 필터(pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms, contentLanguages), 라이브러리가 검색할 수 없는 값, 액션이 읽지 않는 필드는 400 VALIDATION_ERROR로 거절하고, details가 그 필드를 알려 줍니다.

광고 더 받기

받을 광고가 더 있으면 응답에 nextCursor가 붙습니다. 같은 검색에 이 값을 cursor로 보내면 다음 광고를 다시 limit만큼 받습니다. 라이브러리에 광고가 더 없으면 nextCursor는 null입니다. 커서는 그 커서를 돌려준 검색에서만 씁니다. query, advertiserName, payer, country, 날짜 범위나 sortBy가 다르면 400 VALIDATION_ERROR로 거절하고, limit은 바꿔도 됩니다.

검색 응답 예시

  • 응답은 platform, action, country, query, advertiserName, payer, sortBy와 받은 날짜를 그대로 돌려줍니다. returnedCount는 ads의 광고 수, hasMore는 라이브러리에 광고가 더 있으면 true이며 nextCursor로 이어 받고, libraryUrl은 같은 검색을 광고 라이브러리에서 엽니다. 라이브러리가 개수를 주지 않으므로 totalCount는 null입니다.
  • 광고는 카드 하나로 오며, position, libraryId, libraryUrl, advertiserName, advertiserLogoUrl, creativeType(예: SPONSORED_STATUS_UPDATE, SPONSORED_VIDEO), format, title, body, images, videos(동영상 포스터는 previewUrl), platforms(LINKEDIN)가 있습니다. format은 IMAGE, VIDEO, CAROUSEL, DOCUMENT, ARTICLE, MESSAGE, JOB, SPOTLIGHT, FOLLOW_COMPANY 중 하나입니다.
  • 메시지 광고와 thought leader 광고에는 member가 있습니다. 메시지를 보낸 사람이나 광고가 홍보하는 게시물의 작성자이며 name과 url을 담고, ad도 같은 형태로 돌려줍니다. 다른 광고에서는 member가 null입니다.
  • 카드에는 문구의 첫 120자가 담기고, 문구가 더 길면 bodyTruncated가 true입니다. ad는 전체 문구를 돌려줍니다.
  • advertiserId, payer, startDate, endDate, activeDays, linkUrl, landingDomain, impressions, targeting, ctaText, utm은 카드에서 null입니다. ad가 라이브러리에 있는 값을 채웁니다. 라이브러리가 광고의 게재 여부를 알려 주지 않으므로 isActive는 null입니다.
  • summary는 이 응답의 광고를 셉니다. ads, advertisers(광고가 가장 많은 10곳: advertiserName, ads), formats, platforms입니다. 카드에 날짜가 없으므로 날짜 필드(oldestStartDate, newestStartDate, medianActiveDays, launchesByWeek, longestRunning)는 비어 있거나 null입니다.
  • 조건에 맞는 광고가 없는 검색은 빈 ads와 광고 0개의 summary로 완료됩니다.

라이브러리가 보관하는 범위

  • 모든 광고의 소재, 광고주, 광고비를 낸 주체를 모든 국가에서 받을 수 있습니다.
  • 게재 기간, 노출 수 범위, 국가별 노출 비중, 타기팅은 EU에 노출된 광고에서만 받을 수 있습니다.
  • 라이브러리는 광고를 약 12개월간 보관하며, 날짜 필터는 최근 1년만 받습니다.

광고 하나 열기

action ad는 보낸 libraryId의 광고를 엽니다. 검색 결과나 광고 라이브러리 주소 /ad-library/detail/<libraryId>에서 얻을 수 있습니다.
  • ad는 전체 문구를 담은 검색 카드의 필드에 advertiserId, advertiserUrl, advertiserType(company 또는 person), payer(광고비를 낸 주체), linkUrl, landingDomain, ctaText, startDate, endDate, activeDays, impressions, targeting, reachedCountries를 더합니다.
  • impressions는 라이브러리가 공개하는 범위(min, max)입니다. targeting은 광고주가 포함하거나 제외한 언어와 지역(language, location)과 타기팅 매개변수(parameters: parameter, targeted, excluded)를 나열합니다. EU에 노출되지 않은 광고(예: Adobe 광고 1698237666)는 날짜, impressions, targeting, reachedCountries가 null입니다. 광고비를 낸 주체와 광고주는 모든 광고에 있습니다.
  • videos는 동영상마다 url(비트레이트가 가장 높은 파일), files(모든 mp4: url, type, bitrate), previewUrl을 나열합니다. 캐러셀 광고는 cards(title, imageUrl)를, 문서 광고는 document(제목, 페이지 수, 페이지 표지)를 더합니다.
  • advertiser는 광고 뒤의 페이지입니다. advertiserId, advertiserName, url, type, logoUrl이 있습니다.
  • EU에 노출되지 않은 광고의 transparency는 null입니다. EU에 노출된 광고는 impressions, impressionsText(50k-100k처럼 라이브러리가 주는 텍스트), reachByCountry를 담습니다. 이 값은 EU 밖을 포함해 국가별 노출 비중(country, countryCode, share, shareText)입니다.
  • variants는 라이브러리가 두 개 이상 보여 줄 때 광고의 다른 버전을 나열하고, 그렇지 않으면 null입니다.
  • 소재의 미디어 URL은 수년간 열려 있습니다. 캐러셀 카드의 URL은 약 1주일 뒤, 광고주 로고는 약 2주 반 뒤 만료됩니다. 필요한 파일은 따로 저장합니다.
  • 라이브러리에 광고가 없는 libraryId는 PAGE_UNAVAILABLE로 실패합니다.

가격

검색은 시작할 때 limit이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, limit 120 검색은 2크레딧을 보류합니다. ad는 0.5크레딧입니다. 완료된 요청만 과금합니다.

관련 문서