Saltar para o conteúdo principal
Pesquise na Biblioteca de Anúncios da Meta em JSON pela API de tarefas assíncronas. Envie 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

Envie a tarefa e depois consulte 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), ou advertisers, que encontra anunciantes pelo nome.
  • query: uma palavra-chave. Encontra as palavras do texto de um anúncio em qualquer ordem. Obrigatório sem pageId.
  • pageId: o ID numérico da página do Facebook de um anunciante, como 266556540473351. Lista os anúncios desse anunciante e, com query, busca entre eles.
  • country: onde os anúncios foram veiculados, como código de país de duas letras, ou ALL para todos os países. Padrão US.
  • activeStatus: active (padrão), inactive ou all.
  • limit: de 1 a 500 anúncios. Padrão 30.
  • cursor: o nextCursor de uma resposta anterior, para ler os anúncios seguintes.
  • searchType: keyword_unordered (padrão) ou keyword_exact_phrase.
  • adType: all (padrão), political_and_issue_ads, housing_ads, employment_ads ou financial_products_and_services_ads.
  • mediaType: all (padrão), image, meme, image_and_meme, video ou none.
  • publisherPlatforms: um ou mais de facebook, instagram, audience_network, messenger, whatsapp e threads, 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) ou most_recent. impressions_low_to_high exige adType political_and_issue_ads, os únicos anúncios que a biblioteca ordena assim.
Um valor que a biblioteca não consegue pesquisar é recusado com 400 VALIDATION_ERROR, e details indica o campo.

Ler mais anúncios

Uma resposta com mais anúncios a ler traz nextCursor. 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.
Um cursor só vale para a busca que o retornou: outro 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.
Cada anunciante tem 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, query ou pageId, activeStatus e os filtros recebidos.
  • totalCount é a contagem de anúncios correspondentes da própria biblioteca, que a arredonda em buscas grandes. returnedCount conta os anúncios em ads, hasMore é true quando a biblioteca tem mais, que nextCursor lê, e libraryUrl abre a mesma busca na Biblioteca de Anúncios.
  • Cada anúncio tem position, libraryId, libraryUrl, isActive, startDate e endDate (dias em UTC), platforms, versions (quantos anúncios usam este criativo e este texto), format (IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES e outros), body, title, caption, linkUrl, linkDescription, ctaText, ctaType e categories (as categorias do anúncio segundo a biblioteca, como POLITICAL ou EMPLOYMENT).
  • O anunciante é pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount e pageCategories. Anúncios sobre temas sociais, eleições ou política acrescentam byline, quem pagou o anúncio, e disclaimerLabel, e uma parceria paga acrescenta a página do parceiro em brandedContent.
  • A mídia é images (url, resizedUrl), videos (hdUrl, sdUrl, previewImageUrl) e cards, os cartões de um anúncio em carrossel ou de catálogo, cada um com title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl e video. Os outros textos, links, imagens e vídeos de um anúncio dinâmico ficam em extraTexts, extraLinks, extraImages e extraVideos.
  • 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, impressions e reach só 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 ads vazio e totalCount 0.

Preço

Uma busca reserva ao começar 0.5 crédito a cada 30 anúncios pedidos em limit 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.

Relacionado