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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer_integration | string | Sim | uuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query. |
| type | string | Sim | O que buscar: interest, geo ou behavior. No Google Ads: geo ou language. |
| q | string | Não | O termo buscado. Obrigatório para interest e geo. behavior lista tudo sem q. |
| country_code | string | Não | Código do país com 2 letras. Só tem efeito em geo. |
| limit | integer | Não | Máximo de resultados, de 1 a 200. |
| refresh | boolean | Não | Ignora o cache de 600 s e busca de novo na plataforma. |
| subtype | string | Não | Na resposta, só em geo: country, region, city, neighborhood ou zip. Diz em qual campo o resultado entra. |
| audience_size | object | Não | Na 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
