Ads

Search interests, places and languages on Meta Ads and Google Ads via API

One route resolves a term into the ids an ad set's targeting expects, so you do not have to know the id up front. It works for interests, places and behaviors, with the customer's account connected and no Meta app review.

The request

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

What you can do

  • Search interests by term with type=interest and use the id in targeting.interests.
  • Search places with type=geo, narrowing by country with country_code.
  • Browse all behaviors with type=behavior, without needing q.
  • See the estimated audience size in audience_size, as a range from lower to upper.
  • Limit the number of results with limit, from 1 to 200.
  • On Google Ads, search places with type=geo (subtype is the kind of place and path its full name) and languages with type=language, both with q.

Rules and limits

  • q is required for interest and geo. Only behavior lists everything without a term, and country_code only takes effect on geo.
  • Each result has the same shape for all three types, with id, name, type, subtype, path, description, country_code and audience_size. For geo the id is the place's key.
  • interest and behavior go in targeting.interests. For geo, only a country fits in targeting.countries: city, region and neighborhood go in through facebook_ads.targeting.raw.geo_locations, and the subtype says which.
  • The response is not paginated: at most 200 items come back per search.
  • Cached for 600 s per connection. meta.cached and meta.cached_at say whether it came from the cache, and refresh=true bypasses it.
  • On Google Ads, type takes only geo and language, and the id is Google's location or language constant.
  • On Google Ads, the results do not feed creation yet: campaigns and groups are created without location, language or audience targeting.

Main fields

FieldTypeRequiredDescription
customer_integrationstringYesThe uuid of the customer's connection. It defines the ad account. Always goes in the query.
typestringYesWhat to search: interest, geo or behavior. On Google Ads: geo or language.
qstringNoThe search term. Required for interest and geo. behavior lists everything without q.
country_codestringNoTwo-letter country code. Only takes effect on geo.
limitintegerNoMaximum results, from 1 to 200.
refreshbooleanNoBypasses the 600 s cache and fetches again from the platform.
subtypestringNoIn the response, geo only: country, region, city, neighborhood or zip. It says which field the result goes in.
audience_sizeobjectNoIn the response: the estimated range of people (lower and upper). It is a range, and geo has none.

Who it is for

  • Audience picker in your SaaS

    You type a term, show the interest options with audience size and build the ad set with the chosen ids.

  • City targeting

    An agency searches the customer's city with type=geo, reads the subtype and puts the id in the right place in the targeting.

  • AI agent that builds audiences

    An agent receives "people who like running", searches the interest, picks the closest result and creates the ad set.

Works with

  • Meta Ads
  • Google Ads

Frequently asked questions

Do I need to know the interest id beforehand?

No. This route exists for that: you search the term with type=interest and q, and get the id targeting expects.

Can I target by city?

Yes, but city, region and neighborhood do not go in targeting.countries. They go through facebook_ads.targeting.raw.geo_locations, and the result's subtype says which one it is. Only a country goes in targeting.countries.

Is the search paginated?

No. At most 200 items come back per search, controlled by limit. Refine the term if you need more precision.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.