Ads

Buscar interesses, locais e idiomas no Meta Ads e no Google Ads pela API

Uma rota resolve um termo nos ids que a segmentação de um conjunto de anúncios espera, para você não precisar conhecer o id de antemão. Funciona para interesses, locais e comportamentos, com a conta do cliente conectada e sem passar pelo app review da Meta.

A chamada

GET /api/ads/targeting/search?customer_integration=<connection uuid>&type=interest&q=running&limit=10
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

O que dá para fazer

  • Buscar interesses por termo com type=interest e usar o id em targeting.interests.
  • Buscar locais com type=geo, filtrando por país com country_code.
  • Navegar por todos os comportamentos com type=behavior, sem precisar de q.
  • Ver o tamanho estimado do público em audience_size, como faixa de lower a upper.
  • Limitar a quantidade de resultados com limit, de 1 a 200.
  • No Google Ads, buscar locais com type=geo (subtype é o tipo do local e path o nome completo) e idiomas com type=language, os dois com q.

Regras e limites

  • q é obrigatório para interest e geo. Só behavior lista tudo sem termo, e country_code só tem efeito em geo.
  • Cada resultado vem no mesmo formato nos três tipos, com id, name, type, subtype, path, description, country_code e audience_size. Para geo o id é a chave do local.
  • interest e behavior entram em targeting.interests. Em geo, só país cabe em targeting.countries: cidade, região e bairro entram por facebook_ads.targeting.raw.geo_locations, e o subtype diz qual.
  • A resposta não é paginada: vêm no máximo 200 itens por busca.
  • Cache de 600 s por conexão. meta.cached e meta.cached_at dizem se veio do cache, e refresh=true ignora.
  • No Google Ads, type aceita só geo e language, e o id é a constante de local ou de idioma do Google.
  • No Google Ads, os resultados ainda não entram na criação: campanha e grupo nascem sem segmentação de local, idioma ou público.

Campos principais

CampoTipoObrigatórioDescrição
customer_integrationstringSimuuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query.
typestringSimO que buscar: interest, geo ou behavior. No Google Ads: geo ou language.
qstringNãoO termo buscado. Obrigatório para interest e geo. behavior lista tudo sem q.
country_codestringNãoCódigo do país com 2 letras. Só tem efeito em geo.
limitintegerNãoMáximo de resultados, de 1 a 200.
refreshbooleanNãoIgnora o cache de 600 s e busca de novo na plataforma.
subtypestringNãoNa resposta, só em geo: country, region, city, neighborhood ou zip. Diz em qual campo o resultado entra.
audience_sizeobjectNãoNa resposta: a faixa estimada de pessoas (lower e upper). É uma faixa, e geo não tem.

Para quem

  • Seletor de público no seu SaaS

    Você digita um termo, mostra as opções de interesse com o tamanho do público e monta o conjunto de anúncios com os ids escolhidos.

  • Segmentação por cidade

    Uma agência busca a cidade do cliente com type=geo, vê o subtype e coloca o id no lugar certo da segmentação.

  • Agente de IA que monta públicos

    Um agente recebe "pessoas que gostam de corrida", busca o interesse, escolhe o resultado mais próximo e cria o conjunto.

Funciona com

  • Meta Ads
  • Google Ads

Perguntas frequentes

Preciso saber o id do interesse antes?

Não. Essa rota existe para isso: você busca o termo com type=interest e q, e recebe o id que a segmentação espera.

Posso segmentar por cidade?

Sim, mas cidade, região e bairro não entram em targeting.countries. Eles vão por facebook_ads.targeting.raw.geo_locations, e o subtype do resultado diz qual é. Só país entra em targeting.countries.

A busca tem paginação?

Não. Vêm no máximo 200 itens por busca, controlados por limit. Refine o termo se precisar de mais precisão.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.