Ads
Buscar intereses, lugares e idiomas en Meta Ads y Google Ads con la API
Una ruta resuelve un término en los ids que espera la segmentación de un conjunto de anuncios, para que no tengas que conocer el id de antemano. Funciona para intereses, lugares y comportamientos, con la cuenta del cliente conectada y sin pasar por el app review de Meta.
La llamada
GET /api/ads/targeting/search?customer_integration=<connection uuid>&type=interest&q=running&limit=10 Authorization: Bearer <merchant token> x-customer-token: <customer token>
Qué puedes hacer
- Buscar intereses por término con type=interest y usar el id en targeting.interests.
- Buscar lugares con type=geo, filtrando por país con country_code.
- Navegar por todos los comportamientos con type=behavior, sin necesitar q.
- Ver el tamaño estimado de la audiencia en audience_size, como rango de lower a upper.
- Limitar la cantidad de resultados con limit, de 1 a 200.
- En Google Ads, buscar lugares con type=geo (subtype es el tipo de lugar y path su nombre completo) e idiomas con type=language, los dos con q.
Reglas y límites
- q es obligatorio para interest y geo. Solo behavior lista todo sin término, y country_code solo tiene efecto en geo.
- Cada resultado viene en el mismo formato en los tres tipos, con id, name, type, subtype, path, description, country_code y audience_size. Para geo el id es la clave del lugar.
- interest y behavior entran en targeting.interests. En geo, solo un país cabe en targeting.countries: ciudad, región y barrio entran por facebook_ads.targeting.raw.geo_locations, y el subtype dice cuál.
- La respuesta no está paginada: vienen como máximo 200 ítems por búsqueda.
- Caché de 600 s por conexión. meta.cached y meta.cached_at indican si vino del caché, y refresh=true lo ignora.
- En Google Ads, type acepta solo geo y language, y el id es la constante de lugar o de idioma de Google.
- En Google Ads, los resultados todavía no entran en la creación: campaña y grupo se crean sin segmentación de lugar, idioma ni público.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| customer_integration | string | Sí | El uuid de la conexión del cliente. Define la cuenta de anuncios. Va siempre en la query. |
| type | string | Sí | Qué buscar: interest, geo o behavior. En Google Ads: geo o language. |
| q | string | No | El término buscado. Obligatorio para interest y geo. behavior lista todo sin q. |
| country_code | string | No | Código de país de 2 letras. Solo tiene efecto en geo. |
| limit | integer | No | Máximo de resultados, de 1 a 200. |
| refresh | boolean | No | Ignora el caché de 600 s y consulta de nuevo la plataforma. |
| subtype | string | No | En la respuesta, solo en geo: country, region, city, neighborhood o zip. Indica en qué campo entra el resultado. |
| audience_size | object | No | En la respuesta: el rango estimado de personas (lower y upper). Es un rango, y geo no lo tiene. |
Para quién
Selector de audiencia en tu SaaS
Escribes un término, muestras las opciones de interés con el tamaño de audiencia y armas el conjunto de anuncios con los ids elegidos.
Segmentación por ciudad
Una agencia busca la ciudad del cliente con type=geo, lee el subtype y pone el id en el lugar correcto de la segmentación.
Agente de IA que arma audiencias
Un agente recibe "personas a las que les gusta correr", busca el interés, elige el resultado más cercano y crea el conjunto.
Funciona con
Meta Ads
Google Ads
Preguntas frecuentes
¿Necesito saber el id del interés de antemano?
No. Esta ruta existe para eso: buscas el término con type=interest y q, y recibes el id que espera la segmentación.
¿Puedo segmentar por ciudad?
Sí, pero ciudad, región y barrio no entran en targeting.countries. Van por facebook_ads.targeting.raw.geo_locations, y el subtype del resultado dice cuál es. Solo un país entra en targeting.countries.
¿La búsqueda tiene paginación?
No. Vienen como máximo 200 ítems por búsqueda, controlados por limit. Afina el término si necesitas más precisión.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
