taskType ADS com platform linkedin_ad_library, e action escolhe o que ler. Para escolher entre as bibliotecas de anúncios, veja Bibliotecas de anúncios comparadas.
search(padrão) lista anúncios por uma palavra-chave emquery, pelo nome de um anunciante emadvertiserName, por quem pagou empayer, ou por uma combinação. Cada anúncio traz o anunciante, o formato, o título, o texto e a mídia, e a resposta termina com umsummarydos anúncios retornados.adabre um anúncio: o anunciante, quem pagou, a página de destino e, onde a biblioteca os publica, as datas de veiculação, as impressões, os países que ele alcançou e a segmentação.
action advertisers é recusada com 400 VALIDATION_ERROR. Encontre um concorrente com advertiserName em uma busca.
Uma busca custa 0.5 crédito a cada 30 anúncios que retorna. ad custa 0.5 crédito.
Requisição
GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas. A biblioteca limita a velocidade de leitura, então uma busca de 120 anúncios leva cerca de meio minuto.
Analise os anúncios de um concorrente
Três requisições cobrem uma análise de concorrentes:searchcom o nome do concorrente emadvertiserNamelista os anúncios dele.advertiserNamecorresponde a parte de um nome, então confiraadvertiserNameem cada anúncio. Adicionequerypara restringir os anúncios a um tema, esortByoldestpara começar pelos anúncios mais antigos.adcom olibraryIdde um anúncio retorna quem pagou, a página de destino e, nos anúncios exibidos na UE, as datas de veiculação, as impressões e a segmentação.searchcompayerlista os anúncios que uma agência ou empresa pagou, seja qual for a página que os veicula.
Parâmetros
action:search(padrão) ouad.query: Uma palavra-chave no texto do anúncio.searchprecisa dequery,advertiserNameoupayer.advertiserName: Um nome, comparado como parte do nome do anunciante, comosamsung.payer: O nome de quem pagou o anúncio, comparado como parte do nome, comoStarcom.libraryId: O ID numérico de um anúncio, como1638962914.ado exige.country: Onde os anúncios foram exibidos, como código de país de duas letras, ouALLpara todos os países (padrão).startDate,endDate:YYYY-MM-DD, enviados juntos, dentro do último ano. Mantém os anúncios exibidos entre os dois dias.sortBy:newest(padrão) ouoldest.limit: De 1 a 120 anúncios. Padrão 30.cursor: OnextCursorde uma resposta anterior, para ler os anúncios seguintes.
search lê todos os campos acima, exceto libraryId, e ad lê somente libraryId. Um filtro da Biblioteca de Anúncios da Meta (pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms ou contentLanguages), um valor que a biblioteca não consegue pesquisar ou um campo que a ação não lê é recusado com 400 VALIDATION_ERROR, e details indica o campo.
Ler mais anúncios
Uma resposta com mais anúncios para ler traznextCursor. Envie-o como cursor com a mesma busca para receber os anúncios seguintes, de novo até limit. nextCursor é null quando a biblioteca não tem mais. Um cursor só funciona com a busca que o retornou: um query, advertiserName, payer, country, intervalo de datas ou sortBy diferente é recusado com 400 VALIDATION_ERROR, enquanto limit pode mudar.
Resposta da busca
- A resposta repete
platform,action,country,query,advertiserName,payer,sortBye as datas recebidas.returnedCountconta os anúncios emads,hasMoreétruequando a biblioteca tem mais, o quenextCursorlê, elibraryUrlabre a mesma busca na Biblioteca de Anúncios.totalCounténull, porque a biblioteca não informa uma contagem. - Cada anúncio é um card:
position,libraryId,libraryUrl,advertiserName,advertiserLogoUrl,creativeType(comoSPONSORED_STATUS_UPDATEouSPONSORED_VIDEO),format,title,body,imagesevideos(o pôster do vídeo empreviewUrl), eplatforms(LINKEDIN).formatéIMAGE,VIDEO,CAROUSEL,DOCUMENT,ARTICLE,MESSAGE,JOB,SPOTLIGHTouFOLLOW_COMPANY. - Anúncios de mensagem e anúncios Thought Leader trazem
member, o remetente da mensagem ou o membro cuja publicação o anúncio promove, comnameeurl;ado retorna no mesmo formato. Nos demais anúncios,memberénull. - Um card traz os primeiros 120 caracteres do texto, e
bodyTruncatedétruequando o texto é mais longo.adretorna o texto completo. advertiserId,payer,startDate,endDate,activeDays,linkUrl,landingDomain,impressions,targeting,ctaTexteutmsãonullem um card.ados preenche onde a biblioteca os tem.isActiveénull, porque a biblioteca não informa se um anúncio ainda roda.summaryconta os anúncios desta resposta:ads,advertisers(os 10 com mais anúncios:advertiserName,ads),formatseplatforms. Os campos de data dele (oldestStartDate,newestStartDate,medianActiveDays,launchesByWeekelongestRunning) ficam vazios ounull, porque os cards não trazem datas.- Uma busca sem anúncios correspondentes termina com
adsvazio e umsummaryde0anúncios.
O que a biblioteca guarda
- O criativo, o anunciante e o pagador de cada anúncio estão disponíveis para todos os países.
- As datas de veiculação, a faixa de impressões, a participação das impressões por país e a segmentação estão disponíveis apenas para anúncios exibidos na UE.
- A biblioteca guarda os anúncios por cerca de 12 meses, e o filtro de datas aceita apenas o último ano.
Abra um anúncio
action ad abre o anúncio com o libraryId que você enviar, obtido em uma busca ou no endereço da Biblioteca de Anúncios /ad-library/detail/<libraryId>.
adtem os campos de um card de busca com o texto completo, maisadvertiserId,advertiserUrl,advertiserType(companyouperson),payer(quem pagou o anúncio),linkUrl,landingDomain,ctaText,startDate,endDate,activeDays,impressions,targetingereachedCountries.impressionsé a faixa que a biblioteca publica (min,max).targetinglista os idiomas e locais que o anunciante incluiu ou excluiu (language,location) e os parâmetros de segmentação (parameters:parameter,targeted,excluded). As datas,impressions,targetingereachedCountriessãonullem um anúncio que não foi exibido na UE, como o anúncio da Adobe1698237666. O pagador e o anunciante aparecem em todos os anúncios.videoslista cada vídeo comurl(o arquivo com o maior bitrate),files(cada mp4:url,type,bitrate) epreviewUrl. Um anúncio em carrossel acrescentacards(title,imageUrl) e um anúncio de documento acrescentadocument(o título, o número de páginas e as capas das páginas).advertiseré a página por trás do anúncio:advertiserId,advertiserName,url,typeelogoUrl.transparencyénullem um anúncio não exibido na UE. Em um anúncio exibido na UE, contémimpressions,impressionsText(o texto da biblioteca, como50k-100k) ereachByCountry, a participação das impressões em cada país (country,countryCode,share,shareText), inclusive fora da UE.variantslista as outras versões do anúncio quando a biblioteca mostra mais de uma, e énullnos demais casos.- As URLs de mídia dos criativos continuam abertas por anos. As URLs dos cards de um carrossel expiram após cerca de uma semana, e os logotipos dos anunciantes após cerca de duas semanas e meia. Salve os arquivos de que precisar.
- Um
libraryIdpara o qual a biblioteca não tem anúncio falha comPAGE_UNAVAILABLE.
Preço
Uma busca reserva 0.5 crédito a cada 30 anúncios que olimit dela pede, e cobra 0.5 crédito a cada 30 anúncios que retorna, no mínimo 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com limit 120 reserva 2 créditos. ad custa 0.5 crédito. Apenas requisições concluídas são cobradas.