API da biblioteca de anúncios do Meta (/api/v1/adlibrary)
Isso complementa o Referência da API. Usar GET /api/v1/adlibrary (ou o apelido antigo GET /api/adlibrary) com o seu Chave da API para pesquisar anúncios do Meta (Facebook/Instagram) de forma programática.
Nota sobre o caminho:
/api/v1/adlibraryé canônico;/api/adlibraryé um serviço com medição de tráfego também conhecido como. Os exemplos a seguir utilizam/api/v1/...para chamadas programáticas. Marcas rastreadas por meio de uma chave de API (GET /api/v1/marcas) e guias de detalhes da marca na sessão estão documentados em Marcas e acompanhamento de marcas.
Ferramenta MCP (Meta Ads)
pesquisar_anúncios_no_Facebook— mesmo fluxo subjacente queGET /api/v1/adlibrary(palavra-chave, país, página, ordenação).descobrir produtos vencedores— Visualização de produtos vencedores com base na biblioteca de anúncios (aplica filtros de pontuação de vencedor e de página do produto para a descoberta de produtos).pacote_de_inspiração_criativa— lista de finalistas elaborada pela adlibrary, incluindo ganchos, páginas de destino e mix de mídia.resumo_da_concorrência— resumo rápido da concorrência a partir da biblioteca de anúncios + sinais da loja/rastreador.scan_ad— Analisador de ID de anúncio/URL com hook + avaliação de escalabilidade com base nos sinais disponíveis.
Para o MCP ordenar por em pesquisar_anúncios_no_Facebook e descobrir produtos vencedores, use:
relevância, data encontrada, visto pela última vez, adspend, de maior duração, alcance, valor do conjunto de anúncios, coerência, visitas mensais, pageactiveads.
Aliases criado, data, recente, início do último anúncio, e primeiro_anúncio_iniciado são normalizados automaticamente pelo MCP.
Configuração: MCP. Parâmetros: MCP · Referência de ferramentas. Para marcas_acompanhadas, consulte Marcas.
Autenticação e medição compartilhadas (/api/v1/adlibrary, /api/v1/marcas)
Ambos /api/v1/adlibrary e /api/v1/marcas compartilham as mesmas regras de medição e autenticação. Marca detalhe rotas sob /api/marcas/* são válidas apenas para a sessão — consulte Marcas.
- Chave da API:
Chave X-API,Autorização: ao portador, ou?api_key=(ver Referência da API). - Sessão: Se o visitante já estiver conectado, as mesmas rotas podem ser executadas sem uma chave; o usuário ativo ainda deve passar pela verificação de acesso à API descrita abaixo.
- Plano: A conta deve incluir Acesso à API. Caso contrário
403. - Créditos / limite de taxa: Créditos mensais de API e 60 solicitações por minuto por usuário. Quando esgotado,
429com um erro JSON e opcionalcréditosobjeto.
Quando você usa uma chave de API sem uma sessão de navegador ativa, o servidor ainda associa a chave à sua conta para essa solicitação, de modo que o comportamento seja idêntico ao do painel.
GET /api/v1/adlibrary — Lista de anúncios de sucesso do Meta / Facebook
Alias: GET /api/adlibrary — mesma medição e parâmetros.
Equivalente na interface do usuário: A chamada de visualizações de anúncios do Meta no aplicativo /api/fb-ads (ou /api/fb-ads-winning) com o mesmo formato de consulta. Para a integração, copie uma solicitação ativa da guia “Rede” do seu navegador e substitua o caminho por /api/v1/adlibrary (ou /api/adlibrary), mantendo as mesmas chaves e valores da consulta.
Proteção de entrada (chaves de consulta obrigatórias)
O endpoint só retorna sua carga JSON principal quando todas as chaves a seguir estiverem presentes na string de consulta (é permitido usar uma string vazia):
palavra-chave de pesquisa, palavra-chave, min, países, de, para, classificação, filtro de mídia, página, máximo, rolar, dimensionamento, nichos, desde a última vez que foi visto, tolastseen, status ativo
Se algum estiver faltando, a resposta não será a carga útil habitual da lista (evite isso nos clientes).
Além disso, o portão interno requer julgamento definido na consulta ou a autenticado / chave de API resolvida sessão. Com uma Chave X-API, você atende automaticamente aos requisitos da sessão. Caso contrário, a resposta é:
{"error":"logged_out"}
Todos de consulta#
Tudo o que se segue é lido a partir do cadeia de consulta (com o mesmo formato que /api/fb-ads (no aplicativo).
isset gate (deve estar presente; uma string vazia é aceitável)
A mesma lista que Guarda de entrada acima:
palavra-chave de pesquisa, palavra-chave, min, máximo, países, de, para, classificação, filtro de mídia, página, rolar, dimensionamento, nichos, desde a última vez que foi visto, tolastseen, status ativo.
Altamente recomendado em todas
O manipulador lê site, idiomas, filtro de tipo de página, direção da ordenação, aplicativos, e temas sem passar por isso isset lista. Espelhar o painel e enviar pelo menos site=Todos, idiomas=Todos, pagetypefilter= (vazio = todos os tipos de página), sortdirection=desc, aplicativos=Todos, temas=Todos para que o comportamento corresponda à interface do usuário e as chaves opcionais estejam sempre definidas.
Autenticação / sessão /
| Parâmetro | Função |
|---|---|
| (nenhuma) | Com Chave X-API, a solicitação é executada com os dados da sua conta (o mesmo que estar conectado). |
julgamento |
Se definido (por exemplo, trial=true), aplicam-se as regras de localização de vencedores anônimos; combinadas com filtros na página ≠ 0, podem retornar {"message":"need_account"}. |
Paginação, cursor,
| Parâmetro | Notas |
|---|---|
página |
Índice de páginas com base em 0. |
rolar |
Cursor de paginação profunda a partir da pesquisa; vazio na primeira solicitação, depois copiar o rolar valor da resposta JSON anterior. |
próxima vez que for à lixeira |
Unix segundos; usado quando ordenação=data encontrada (a primeira página costuma usar um carimbo de data e hora de referência da interface do usuário). |
token_de_pesquisa |
Opcional [a-zA-Z0-9_-]+; gravatas anúncios por marca limitar a uma guia/pesquisa na sessão. |
por palavra-chave#
| Parâmetro | Valores permitidos / típicos |
|---|---|
palavra-chave |
Texto livre; codificado como URL; convertido para letras minúsculas no servidor. |
palavra-chave de pesquisa |
'', Todos, URL de destino, nome da página, texto do anúncio, nome do produto (deve estar neste conjunto quando palavra-chave (não está vazio). |
Anúncios ativos, dimensionamento, mídia, tipo de página, AdScore,
| Parâmetro | Valores (correspondentes aos filtros de anúncios Meta no aplicativo) |
|---|---|
status ativo |
String verdadeiro ou falso (apenas ativos vs. incluir inativos). |
dimensionamento |
'' (nenhum), sem redução de escala, ampliando, redução de escala. |
filtro de mídia |
'' / omitir efeito = todos os formatos; caso contrário vídeos, imagens, carrossel, dco (corresponde a formato_de_exibição (em ES). |
filtro de tipo de página |
'' = todos; produtos, coleções, funis, nofunnels. |
filtro de pontuação de anúncios |
'' = nenhum; vencedor (Fundada), dimensionamento (Tem potencial), testes (Não definido). Requer o plano correspondente dentro do aplicativo. |
baixo número de visualizações |
'' = mostrar tudo; ocultar = excluir linhas com número muito baixo de impressões (comportamento idêntico ao do filtro do painel). |
| Parâmetro | Valores |
|---|---|
direção da ordenação |
asc ou desc (se estiver vazio, o padrão é desc). |
classificação |
'' (Nenhuma → ordem aleatória quando não estiver em modo aleatório), trending, valor do conjunto de anúncios, visto pela última vez, data encontrada, adspend, de maior duração, alcance, dias correndo. dias correndo pode não aplicar um ramo de classificação específico (funciona como None, a menos que o produto mude). |
Gasto, alcance (com janela), tráfego, dias em exibição, preço, texto, duração do vídeo, anúncios ativos na
| Parâmetro | Notas |
|---|---|
minadspend, gasto máximo |
Números inteiros / cadeias numéricas. maxadspend=999999 é considerado como “sem limite máximo” para a verificação adspend. adspend eficaz adspend pode exigir um plano de assinatura superior no aplicativo. |
período de investimento em publicidade |
todos, 7, 30, 90 — janela para adspend (valores inválidos → todos). |
minreach, maxreach |
Números inteiros. Pode exigir um plano de assinatura superior no aplicativo. |
intervalo de tempo |
O mesmo conjunto permitido que período de investimento em publicidade. |
mintraffic, maxtraffic |
Pode ser necessário um plano superior dentro do aplicativo. |
mindays, dias máximos |
Filtro de intervalo de dias consecutivos; pode exigir um plano superior no aplicativo. |
preço mínimo, preço máximo |
|
comprimento do mincópio, comprimento máximo da cópia |
|
duração mínima do vídeo, duração máxima do vídeo |
|
minactiveads, maxactiveads |
Limite do estilo “Anúncios ativos na página” (o fluxo de teste pode inserir minactiveads (no lado do servidor). |
Datas (cadeias de caracteres, normalmente D-m-a)
| Parâmetro | Significado |
|---|---|
de, para |
Anúncio criação (começou). |
desde a última vez que foi visto, tolastseen |
Visto pela última vez (atualizado em). |
origem do produto, product_to |
Janela de criação de produtos. |
página de, página |
Janela de criação de página. |
Intervalos de datas abertos são normalizados no servidor (por exemplo, apenas de definir → para pode ser definido para corresponder de).
Catálogo: países, lojas, nichos, idiomas, aplicativos, temas,
| Parâmetro | Formato |
|---|---|
países |
Todos ou separados por vírgulas ISO 3166-1 alfa-2 códigos (por exemplo, EUA, Reino Unido). |
site |
Todos ou códigos de loja separados por vírgulas (por exemplo, SH = Shopify — consulte o filtro do site no painel). |
nichos |
Todos ou segmentos separados por vírgulas (códigos predefinidos, /Caminho/... caminhos do catálogo de nichos ou IDs numéricos — normalizados no lado do servidor). Se a lista contiver compras, o servidor acrescenta produto. |
idiomas |
Todos ou códigos de idioma separados por vírgulas (como no painel de controle #idioma). |
aplicativos |
Todos ou separados por vírgulas numérico IDs de aplicativos (os mesmos valores do filtro de aplicativos integrados). |
temas |
Todos ou sequências de temas separadas por vírgulas (descubra através de GET /api/themes). |
excluir países, excluir sites, excluir idiomas, excluir nichos, excluir aplicativos |
Os mesmos padrões separados por vírgulas do lado da inclusão; nichos normalizados como nichos. |
Links diretos, reprodução aleatória,
| Parâmetro | Notas |
|---|---|
página a partir da URL |
Facebook page_id — restringe os anúncios a uma única página. |
ID do produto |
ID do produto no Shopify. |
embaralhar |
Qualquer valor não vazio que seja verdadeiro → modo aleatório (classificação aleatória; janela padrão "última vista" opcional). |
anúncios por marca |
1, 2, 3, 5, 10 apenas — número máximo de anúncios por marca quando a lógica de aleatorização/limite por marca é aplicada. |
Validação /
Inválido min ou máximo (fora do intervalo 0…90000000) pode resultar em {"error":"value_not_in_range_1"} ou _2, ou um formato que não seja JSON falso corpo em casos extremos.
Descobrindo o que é válido nichos e temas (não há chave de API nessas rotas)
As integrações devem obter os valores permitidos a partir do JSON de descoberta, e não por suposição:
| Ponto final | Objetivo |
|---|---|
GET /api/niche-counts |
Devoluções { "niches": [ { "code": "…", "count": N }, … ], "total_with_niche": … } criado a partir do mesmo índice de anúncios do Meta que o produto utiliza. Use o código cadeias de caracteres (separadas por vírgulas em nichos / excluir nichos) como o conjunto de referência que realmente aparece nos dados dos anúncios. Opcional: refresh=1 ignora o cache do disco para uma solicitação. |
GET /api/themes |
Retorna um objeto JSON com um temas lista (principais valores + contagens, armazenada em cache por cerca de 1 hora). Consulta opcional: q — se o comprimento for ≥ 2, pesquisa de subcadeia para preenchimento automático. Opcional: limite (padrão 200, máximo 500). Usar o tema retornado nomes/chaves exatamente como temas= valores separados por vírgulas em /api/adlibrary. |
Atalhos predefinidos para nichos (”chips” da interface do usuário): O aplicativo também oferece funcionalidades voltadas para o usuário códigos de duas letras (por exemplo, CG, POR, SP) no filtro de nicho. Esses são segmentos válidos em nichos= da mesma forma que o navegador os envia.
Segmentos de nicho por categoria / numéricos: Os valores são resolvidos usando o catálogo de nichos do servidor (caminhos como /Roupas/... e numérico IDs (mapeamento para nomes canônicos na pesquisa). Se um segmento for desconhecido, ele pode ser transmitido tal como está — prefira /api/contagem-de-nichos em vez de inventar desculpas.
Nota: /api/contagem-de-nichos e /api/temas são descoberta auxiliares e não consomem créditos da API da biblioteca de anúncios do Meta da mesma forma /api/adlibrary É verdade. Sua implantação ainda pode exigir autenticação ou outras políticas antes dessas rotas.
Portas de recursos (atualização JSON)
Para contas que não possuem o nível de produto exigido, determinados filtros ou modos de classificação retornam 200 com um pequeno corpo JSON (a solicitação de atualização é na banda(nem sempre um erro HTTP 403):
| Resposta | Condição (simplificada) |
|---|---|
{"upgrade":"standard_adspend"} |
Filtro de gastos com publicidade utilizado, ou adspend com publicidade |
{"upgrade":"standard_reach"} |
Filtro de alcance ou classificação=alcance |
{"upgrade":"standard_traffic"} |
Filtro de tráfego |
{"upgrade":"standard_daysrunning"} |
Filtro de dias consecutivos ou ordenação=dias em execução |
{"upgrade":"standard_adscore"} |
filtro de pontuação de anúncios conjunto |
Outras dignas de nota#
{"message":"need_account"}— Anônimojulgamentosolicitações que excedem o limite de uso permitido (restrições da versão de teste).- Resposta de sucesso: objeto JSON contendo
dados(anúncios), opcionalmensagem(dicas de filtragem legíveis por humanos),totalquando calculado na primeira página e nos campos de crédito do plano gratuito, quando aplicável.