Como Usar a API da Biblioteca de Anúncios do Facebook (Meta)

A API da Biblioteca de Anúncios do Facebook/Meta, que chamamos de API da Biblioteca de Anúncios do Facebook, é uma interface publicamente disponível que oferece aos desenvolvedores acesso a anúncios publicados no Facebook, Instagram e outras plataformas da Meta (por exemplo, WhatsApp e Threads). É através desta API que você pode pesquisar anúncios por palavra-chave, ID da página, país ou tipo de anúncio, e recuperar metadados como criativos de anúncios, faixas de gastos, impressões, plataformas de editor e muito mais.

Esta API é particularmente útil para pesquisa de transparência, auditorias de marketing, análise competitiva, análise de criativos de anúncios ou para construir ferramentas em torno de dados de anúncios de mídias sociais. Se você deseja monitorar anúncios ativos, estudar anúncios políticos ou de questões sociais (anúncios SIEP) ou analisar estratégias de marketing, a API da Biblioteca de Anúncios do Facebook oferece uma porta poderosa para dados de anúncios.

Por Que Usar a API da Biblioteca de Anúncios do Facebook e o Que Ela Permite Fazer?

Algumas das principais capacidades da API da Biblioteca de Anúncios do Facebook:

1. Pesquisar por palavras-chave, IDs de página, país, tipo de anúncio — você pode refinar anúncios pelo que eles contêm, quem os publicou, onde são exibidos e qual o tipo de campanha.
2. Filtrar por status: ativo/inativo, faixas de gastos, impressões — útil quando você quer apenas anúncios ativos ou aqueles acima/abaixo de certos limites de gastos.
3. Recuperar metadados de anúncios — incluindo campos como page_name, ad_snapshot_url, spend, impressions, publisher_platforms (Facebook/Instagram) e outros.
4. Suporte para cobertura de dados ampla e de longo prazo — por exemplo, globalmente para anúncios SIEP, e para muitas regiões para anúncios gerais (sujeito às políticas de região da Meta a partir de 2025)
5. Acesso gratuito a dados públicos — sem custo inicial para recuperar dados de anúncios públicos, desde que você tenha a configuração de acesso adequada.

Em resumo — a API oferece uma forma estruturada e programável de explorar e coletar dados de anúncios em escala.

Guia Passo a Passo: Como Começar a Usar a API da Biblioteca de Anúncios do Facebook

Passo 1: Verifique Sua Conta e Identidade do Facebook/Meta

• Faça login/crie sua conta do Facebook (pessoal ou comercial).
• Certifique-se de que sua conta esteja verificada (a Meta às vezes exige verificação de identidade para acesso à API). (Verificação da conta)
• Este passo é importante, especialmente se você planeja solicitar acesso a dados da biblioteca de anúncios através de um aplicativo.

Passo 2: Registre um Aplicativo de Desenvolvedor da Meta

• Visite Meta for Developers → “Começar” e faça login na plataforma. (Clique aqui)

• Crie um novo Aplicativo: escolha “Outro” ou um tipo genérico se você não estiver anunciando.

• Selecione que você deseja acesso às Marketing APIs / Ad-Library.

• Inicialmente, o aplicativo estará no modo de Desenvolvimento — o que é suficiente para testes básicos e uso em pequena escala.

Passo 3: Gerar um Token de Acesso

• Use o Graph API Explorer ou as ferramentas da Meta para gerar um token de acesso de usuário.
• Garanta que o token tenha as permissões necessárias (por exemplo, ads_read, possivelmente ads_archive ou outras dependendo dos requisitos da Meta). (Facebook for Developers)

Nota: tokens de acesso expiram; você pode precisar estendê-los ou gerar tokens de longa duração dependendo do seu uso.

Passo 4: Faça Sua Primeira Chamada à API

Você pode consultar o endpoint /ads_archive (a raiz da API da Biblioteca de Anúncios). Use a versão mais recente da API (por exemplo, v23.0 ou mais recente). (Facebook for Developers)

Exemplo: usando curl

curl -G \
  -d "search_terms=skincare" \
  -d "ad_reached_countries=['US']" \
  -d "ad_active_status=ACTIVE" \
  -d "fields=page_name,ad_snapshot_url,spend,impressions,publisher_platforms" \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/ads_archive"

Exemplo: usando JavaScript (fetch)

const response = await fetch(
  `https://graph.facebook.com/v23.0/ads_archive?` +
  `search_terms=skincare&ad_reached_countries=['US']&ad_active_status=ACTIVE` +
  `&fields=page_name,spend,impressions,publisher_platforms` +
  `&access_token=YOUR_ACCESS_TOKEN`
);
const data = await response.json();
console.log(data);

A resposta JSON incluirá um array de objetos de anúncio, cada um com metadados como page_name, ad_snapshot_url, faixas de gastos, faixas de impressões, plataformas de editor e potencialmente mais campos.

Passo 5: Lidando com Paginação e Grandes Resultados

Como a Biblioteca de Anúncios pode retornar muitos resultados, a API usa paginação. Prepare-se para percorrer as páginas subsequentes — examine a resposta para paging ou tokens de cursor e itere de acordo. Desenvolvedores frequentemente constroem loops em código para agregar grandes conjuntos de resultados.

Passo 6: Casos de Uso — O Que Você Pode Fazer com Estes Dados?

Aqui estão casos de uso comuns:

1. Análise competitiva — recupere anúncios da Página do Facebook de um concorrente (via ID da página) para estudar seus criativos, estimativas de gastos ou alcance de segmentação.
2. Monitoramento e pesquisa de tendências — acompanhe quais tipos de anúncios estão ativos por palavra-chave, região, tipo de mídia ou tipo de anúncio (por exemplo, político, imobiliário, questões sociais).
3. Painéis de inteligência de marketing — agregue dados (faixas de gastos, impressões, frequência de anúncios) e visualize ao longo do tempo ou em diferentes regiões.
4. Análise / inspiração de criativos de anúncios — busque e arquive criativos de anúncios (URLs de imagem/vídeo) para inspiração de produtos ou auditorias de conformidade.
5. Pesquisa acadêmica / de transparência — use dados de anúncios para estudos sobre publicidade política, campanhas de questões sociais ou tendências de mercado.

Esses casos de uso destacam o valor de ter acesso estruturado e programático aos dados de anúncios.

Testando a API da Biblioteca de Anúncios do Facebook com Apidog

Use o Apidog como um ambiente de teste para a API da Biblioteca de Anúncios do Facebook. Veja como começar a testar suas APIs no Apidog:

1. No Apidog, crie um novo endpoint de API: defina o método como GET, URL para https://graph.facebook.com/v23.0/ads_archive.

2. Em parâmetros de consulta, adicione parâmetros como search_terms, ad_reached_countries, fields e access_token.

3. Clique em “Enviar” — o Apidog buscará os dados e mostrará a resposta JSON em formato estruturado.

4. Você pode experimentar múltiplas combinações de parâmetros, testar a paginação e até salvar exemplos de respostas para documentação ou análise.

Esta abordagem é especialmente útil para exploração rápida de dados de anúncios, teste de consultas de pesquisa e construção de integrações sem escrever código completo.

Perguntas Frequentes

P1. Preciso de uma conta de Anúncios ou conta empresarial especial para usar a API da Biblioteca de Anúncios do Facebook?
Não — uma conta Meta verificada geralmente é suficiente. No entanto, você deve registrar um Aplicativo de Desenvolvedor da Meta e obter um token de acesso com as permissões apropriadas (por exemplo, ads_read, ads_archive). Alguns usuários precisam completar a verificação de identidade para acesso total.

P2. Posso obter dados para qualquer anúncio (não apenas anúncios políticos ou de questões sociais)?
Sim — a API suporta anúncios gerais (não apenas SIEP). Você pode usar ad_type=all (ou omitir o filtro) dependendo da região e disponibilidade do anúncio.

P3. Quantos anúncios posso recuperar em uma única solicitação?
Por padrão, a API retorna um número limitado de anúncios por solicitação (paginação). Para recuperar mais, você precisa iterar pelas páginas usando o cursor de paginação fornecido na resposta.

P4. Posso acessar criativos de anúncios (imagens, vídeos) via API?
Você obtém ad_snapshot_url ou campos semelhantes que levam à prévia do criativo do anúncio. No entanto, a Meta nem sempre fornece arquivos de mídia diretos — buscar imagens ou vídeos reais pode exigir passos adicionais.

P5. Existe uma maneira de automatizar a recuperação de dados e evitar problemas de expiração de token?
Sim — você pode gerar tokens de longa duração nas ferramentas de desenvolvedor da Meta ou configurar um sistema de backend que atualize os tokens periodicamente. Para recuperação de dados em grande escala, combinar o gerenciamento de tokens com loops de paginação é comum. Sempre armazene os tokens com segurança.

Conclusão

A API da Biblioteca de Anúncios do Facebook (Meta) fornece um portal poderoso e estruturado para dados de anúncios — permitindo que desenvolvedores, profissionais de marketing, pesquisadores e analistas pesquisem, coletem e analisem programaticamente campanhas de anúncios nas plataformas da Meta. Usando-a, você pode construir painéis, realizar análises competitivas, fazer pesquisas de transparência ou agregar criativos de anúncios em escala.

Ao configurar um aplicativo de desenvolvedor da Meta, obter um token de acesso adequado e fazer solicitações para o endpoint /ads_archive — opcionalmente testando através de ferramentas como o Apidog — você pode desbloquear uma vasta quantidade de dados da biblioteca de anúncios. Embora existam limitações (permissões, limites de taxa, paginação, recuperação de mídia), os benefícios geralmente superam o trabalho.

Para qualquer pessoa que precise de dados de anúncios públicos do Facebook/Meta — a API da Biblioteca de Anúncios é uma opção valiosa, oficial e flexível.