Advertisers

Query advertisers

Returns the advanced public advertisers query surface. This endpoint supports the current richer advertiser discovery filters through a structured public camelCase contract while keeping the response aligned with the standard public advertiser summary shape. categoryIds uses linked websites' google_categories; pageNiches remains an advanced legacy page-niche filter. Empty JSON bodies are valid and use defaults.

post/v1/advertisers/query

Request

  • Base URL: https://api.trendtrack.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.trendtrack.io/v1/advertisers/query
  • Auth: HTTP bearer

Request body

searchstring[]
searchType'brand' | 'domain' | 'adCopy' | 'websiteCopy' | 'urlContains'

Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search.

keywordMode'any' | 'all'
sortBy'relevance' | 'newest' | 'activeAds' | 'newAds' | 'euAdsShare' | 'reach' | 'reach14d' | 'followers'
order'asc' | 'desc'
offsetnumber
limitnumber
minFbPageCreationDatestring
maxFbPageCreationDatestring
minActiveAdsnumber
maxActiveAdsnumber
adsTimePeriod'current' | 'last24h' | 'last7d' | 'last14d' | 'last30d'
minFacebookLikesnumber
maxFacebookLikesnumber
minInstagramFollowersnumber
maxInstagramFollowersnumber
minAdsLaunchednumber
maxAdsLaunchednumber
adsLaunchedPeriod'last24h' | 'last7d' | 'last14d' | 'last30d' | 'last90d'
minReachnumber

Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

maxReachnumber

Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

reachPeriod'last24h' | 'last7d' | 'last14d' | 'last30d' | 'last90d' | 'total'
minSpendPerPagenumber

Minimum estimated spend per page. Converted internally through CPM and reach/impressions fields.

maxSpendPerPagenumber

Maximum estimated spend per page. Converted internally through CPM and reach/impressions fields.

spendPerPagePeriod'last24h' | 'last7d' | 'last14d' | 'last30d' | 'last90d' | 'total'
cpmnumber

CPM used to convert spend filters into reach/impressions-based ES ranges.

minReachPerPagenumber

Minimum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

maxReachPerPagenumber

Maximum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

reachPerPagePeriod'last24h' | 'last7d' | 'last14d' | 'last30d' | 'last90d' | 'total'
adLanguagestring[]
technologiesstring[]
mainCountriesstring[]

Primary countries to match.

countryFilterMode'reach' | 'adCount'

Enum value accepted by this request. Allowed values: reach, adCount.

ageRangesstring[]
pageTypePublicApiAdvertisersPageType[]

Enum value accepted by this request. Allowed values: influencer, brand.

categoryIdsnumber[]

Google category facet ids matched through linked websites' website_overview.google_categories.

minPartnershipPercentagenumber
shopifyLinked'yes' | 'no' | 'all'
gender'male' | 'female' | 'all'

Example request

{
  "search": [
    "acme"
  ],
  "limit": 20,
  "minFbPageCreationDate": "2024-01-01",
  "maxFbPageCreationDate": "2024-12-31",
  "adLanguage": [
    "en",
    "fr"
  ],
  "technologies": [
    "shopify",
    "woocommerce"
  ],
  "adCountries": {
    "include": [
      "FR",
      "DE"
    ],
    "exclude": [
      "US"
    ]
  },
  "mainCountries": [
    "FR",
    "US"
  ],
  "adsGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "period": "last7d",
            "operator": "gte",
            "value": 40
          }
        ]
      }
    ]
  },
  "pageReachGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "period": "last7d",
            "operator": "gte",
            "value": 50
          }
        ]
      }
    ]
  },
  "ageRanges": [
    "18-24",
    "25-34"
  ],
  "pageType": [
    "brand"
  ],
  "categoryIds": [
    254
  ],
  "pageNiches": {
    "main": [
      254
    ],
    "among": [
      268
    ],
    "exclude": [
      987
    ]
  }
}

Response

Paginated advertisers query response. The response also includes the X-Request-Id header.

requestIdstring required

Request identifier mirrored in the X-Request-Id response header.

Example response

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "61554990830184",
      "platform": "facebook",
      "facebookPageId": "61554990830184",
      "name": "Example Brand",
      "logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "profile": {
        "likes": 125000,
        "instagramFollowers": 89000,
        "createdAt": "2019-01-04T00:00:00.000Z"
      },
      "advertising": {
        "activeAds": 12,
        "reach30d": 452000
      },
      "lastAds": [
        {
          "id": "facebook:123456789",
          "mediaUrl": "https://medias.trendtrack.io/facebook/media/ad-1.mp4",
          "thumbnailUrl": "https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"
        }
      ],
      "mainLandingPages": [
        {
          "landingPage": "https://example.com/products/summer",
          "screenshotUrl": "https://medias.trendtrack.io/landing-pages/summer.jpg"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "total": 128
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.