Sign in

v1

latestOpenAPI 3.1.02026-07-24490622.0 KB
Ad History Research API

Get Domain Ad History by Date

Returns one row per keyword, search date, and ad variation for a domain. Use the date bounds and paging fields to pull a controlled slice while still seeing the total matching result size.

Visualize this API live on SpyFu

get/v2/domain/getDomainAdHistoryByDate

Query parameters

domainstring required
Example:example.com

Advertiser's root domain.

keywordFilterstring
Example:paint

Only include keywords containing this text.

minSearchDateIdinteger
Example:20240101

Earliest ad capture date to include, formatted as YYYYMMDD.

maxSearchDateIdinteger
Example:20260601

Latest ad capture date to include, formatted as YYYYMMDD.

startingRowinteger
Example:1

Starting row number for pagination.

pageSizeinteger
Example:100

Number of flattened ad history rows to return per page.

keywordStartingRowinteger
Example:1

Keyword/domain document row number to start the backing query with before flattening date rows. KeywordStartingRow plus KeywordPageSize must fit within the first 10,000 keyword/domain documents.

keywordPageSizeinteger
Example:10000

Number of keyword/domain documents to fetch before flattening date rows. KeywordStartingRow plus KeywordPageSize must fit within the first 10,000 keyword/domain documents.

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 market to search. Specifically, this maps to the Google domain version to query against (e.g., google.com for US, google.de for Germany, etc.). <a href='https://developer.spyfu.com/reference/adhistoryapi_getdomainadhistorybydate_get#/'>All Countries</a>

Response

Successfully retrieved flattened domain ad history rows and result-size metadata for the requested date range.

totalMatchingResultsinteger

Total flattened keyword/date/ad rows found in the fetched keyword window after the date and keyword filters are applied.

totalMatchingResultsIsPartialboolean

True when more keyword/domain documents exist outside this response's backing query window, so totalMatchingResults is only the flattened count for this keyword window.

resultCountinteger

Number of flattened keyword/date/ad rows returned in this response.

startingRowinteger

Starting row number used for this page.

pageSizeinteger

Requested maximum number of rows returned in this page.

hasMoreResultsboolean

True when more flattened rows are available after this page.

totalMatchingKeywordsinteger nullable

Total keyword/domain documents matched by the backing query before flattening date rows.

keywordStartingRowinteger

Keyword/domain document row number used to start the backing query.

keywordPageSizeinteger

Requested maximum number of keyword/domain documents fetched by the backing query.

resultWindowKeywordCountinteger

Number of keyword/domain documents returned by the backing query for this response.

hasMoreKeywordResultsboolean

True when more keyword/domain documents are available after this backing query window.

Example response

{
  "totalMatchingResults": 1240,
  "resultCount": 100,
  "startingRow": 1,
  "pageSize": 100,
  "hasMoreResults": true,
  "totalMatchingKeywords": 85,
  "keywordStartingRow": 1,
  "keywordPageSize": 10000,
  "resultWindowKeywordCount": 85,
  "results": [
    {
      "keyword": "paint sprayer",
      "termId": 123456789,
      "searchDateId": 20240101,
      "position": 1,
      "title": "Paint Supplies and Tools",
      "body": "Shop paint sprayers, rollers, brushes, and supplies.",
      "domainName": "example.com",
      "fullUrl": "https://example.com/paint/tools?source=ads",
      "adId": 987654
    }
  ]
}