Sign in

v1

latestOpenAPI 3.1.02026-07-24490622.0 KB
Ad History Research API

Get Keyword Ad History With Stats

Returns historical ad variations and advertiser performance statistics for a specific keyword. This endpoint includes domain-level metrics alongside ad copy data, unlike the basic ad history endpoint that focuses purely on ad variations.

Visualize this API live on SpyFu

get/v2/term/getTermAdHistoryWithStats

Query parameters

termstring required
Example:running shoes

Keyword to retrieve advertising history for.

countryCode'AR' | 'AT' | 'AU' | 'BE' | 'BR' | 'CA' | 'CH' | 'DE' | 'DK' | 'ES' | 'FR' | 'IE' | 'IN' | 'IT' | 'JP' | 'MX' | 'NL' | 'NO' | 'NZ' | 'PL' | 'PT' | 'SE' | 'SG' | 'TR' | 'UA' | 'UK' | 'US' | 'ZA'
Example:US

Country code to filter results by geographic market.

pageSizeinteger
Example:5

Number of ad history records to return per page.

startingRowinteger
Example:1

Starting row number for pagination.

Response

Successfully retrieved ad history data with advertiser statistics for the specified keyword. Returns a paginated list of ads with performance metrics and domain-level data.

resultCountinteger

Number of results returned

Example response

{
  "resultCount": 100,
  "domains": [
    {
      "ads": [
        {
          "searchDateId": 20231215,
          "position": 1,
          "title": "Best Running Shoes 2024 - Free Shipping",
          "body": "Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order.",
          "domainName": "example.com",
          "fullUrl": "https://example.com/running-shoes?utm_source=google&utm_campaign=shoes",
          "term": "running shoes",
          "adCount": 45,
          "isLeaderboardAd": true
        }
      ],
      "budget": 15000.5,
      "coverage": 73.2,
      "domainName": "example.com",
      "percentageLeaderboard": 85.7,
      "totalAdsPurchased": 2847,
      "adCount": 45
    }
  ],
  "topAds": [
    {
      "adId": 12345678,
      "averagePosition": 2.4,
      "averageAdCount": 2.1,
      "body": "Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order.",
      "title": "Best Running Shoes 2024 - Free Shipping",
      "fullUrl": "https://example.com/running-shoes?utm_source=google&utm_campaign=shoes",
      "leaderboardCount": 42,
      "percentageLeaderboard": 73.5,
      "percentageAdsServed": 28.7
    }
  ]
}