taskType ADS com platform meta_ad_library e uma palavra-chave em query ou o ID da página do Facebook de um anunciante em pageId. Uma busca custa 0.5 crédito a cada 30 anúncios retornados. Para encontrar o ID da página de um anunciante pelo nome, envie action advertisers.
Requisição
GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas. Uma busca de 30 anúncios costuma terminar em poucos segundos, e uma de 500 anúncios em cerca de um minuto.
Parâmetros
action:search(padrão), ouadvertisers, que encontra anunciantes pelo nome.query: uma palavra-chave. Encontra as palavras do texto de um anúncio em qualquer ordem. Obrigatório sempageId.pageId: o ID numérico da página do Facebook de um anunciante, como266556540473351. Lista os anúncios desse anunciante e, comquery, busca entre eles.country: onde os anúncios foram veiculados, como código de país de duas letras, ouALLpara todos os países. PadrãoUS.activeStatus:active(padrão),inactiveouall.limit: de 1 a 500 anúncios. Padrão 30.cursor: onextCursorde uma resposta anterior, para ler os anúncios seguintes.searchType:keyword_unordered(padrão) oukeyword_exact_phrase.adType:all(padrão),political_and_issue_ads,housing_ads,employment_adsoufinancial_products_and_services_ads.mediaType:all(padrão),image,meme,image_and_meme,videoounone.publisherPlatforms: um ou mais defacebook,instagram,audience_network,messenger,whatsappethreads, como array ou texto separado por vírgulas.contentLanguages: um ou mais códigos de idioma de duas letras.startDate,endDate:YYYY-MM-DD. Mantém os anúncios exibidos entre as duas datas.sortBy:impressions_high_to_low(padrão) oumost_recent.impressions_low_to_highexigeadTypepolitical_and_issue_ads, os únicos anúncios que a biblioteca ordena assim.
400 VALIDATION_ERROR, e details indica o campo.
Ler mais anúncios
Uma resposta com mais anúncios a ler traznextCursor. Envie-o como cursor com a mesma busca para receber os próximos anúncios, de novo até limit. As posições continuam da resposta anterior, e nextCursor é null quando a biblioteca não tem mais.
query, pageId, country, activeStatus ou filtro é recusado com 400 VALIDATION_ERROR, enquanto limit pode mudar. O cursor cresce com os anúncios lidos antes dele, até cerca de 14 KB após mil anúncios; guarde-o como texto sem limite de tamanho. A biblioteca às vezes lista um anúncio duas vezes, então um anúncio pode voltar numa resposta seguinte; libraryId distingue as repetições.
Encontrar um anunciante
action advertisers retorna as páginas do Facebook dos anunciantes cujo nome corresponde a query, como a busca da biblioteca as sugere. Envie o pageId escolhido para buscar os anúncios desse anunciante.
position, pageId, name, category, likeCount, verified (o selo azul da Meta), country (o país da página quando a Meta o informa, como a página britânica de uma marca global), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified e libraryUrl, que abre os anúncios dele na Biblioteca de Anúncios. keywords lista as buscas que a biblioteca sugere para o nome. A biblioteca busca o nome como a página o escreve: Shokz encontra as páginas da Shokz, e 샥즈 não encontra nenhuma. Um nome que nenhuma página usa termina com advertisers vazio. Uma busca de anunciantes aceita só query e country, e custa 0.5 crédito.
Exemplo de resposta
Campos do resultado
- A resposta repete
platform,action,country,queryoupageId,activeStatuse os filtros recebidos. totalCounté a contagem de anúncios correspondentes da própria biblioteca, que a arredonda em buscas grandes.returnedCountconta os anúncios emads,hasMoreétruequando a biblioteca tem mais, quenextCursorlê, elibraryUrlabre a mesma busca na Biblioteca de Anúncios.- Cada anúncio tem
position,libraryId,libraryUrl,isActive,startDateeendDate(dias em UTC),platforms,versions(quantos anúncios usam este criativo e este texto),format(IMAGE,VIDEO,CAROUSEL,DCO,DPA,MULTI_IMAGESe outros),body,title,caption,linkUrl,linkDescription,ctaText,ctaTypeecategories(as categorias do anúncio segundo a biblioteca, comoPOLITICALouEMPLOYMENT). - O anunciante é
pageId,pageName,pageProfileUrl,pageProfilePictureUrl,pageLikeCountepageCategories. Anúncios sobre temas sociais, eleições ou política acrescentambyline, quem pagou o anúncio, edisclaimerLabel, e uma parceria paga acrescenta a página do parceiro embrandedContent. - A mídia é
images(url,resizedUrl),videos(hdUrl,sdUrl,previewImageUrl) ecards, os cartões de um anúncio em carrossel ou de catálogo, cada um comtitle,body,linkUrl,caption,linkDescription,ctaText,ctaType,imageUrl,resizedImageUrlevideo. Os outros textos, links, imagens e vídeos de um anúncio dinâmico ficam emextraTexts,extraLinks,extraImageseextraVideos. - As URLs de mídia são links da CDN da Meta que expiram em poucos dias. Salve os arquivos de que precisar.
- Anúncios de catálogo (
DPA,DCO) mantêm no texto os marcadores da biblioteca, como{{product.name}}. spend,currency,impressionsereachsó aparecem onde a biblioteca os divulga: anúncios sobre temas sociais, eleições ou política, e anúncios exibidos na UE.- Uma busca sem anúncios correspondentes termina com
adsvazio etotalCount0.
Preço
Uma busca reserva ao começar 0.5 crédito a cada 30 anúncios pedidos emlimit e custa 0.5 crédito a cada 30 anúncios retornados, com mínimo de 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com limit 500 reserva 8.5 créditos. Uma busca de anunciantes custa 0.5 crédito. Só as requisições concluídas são cobradas.