SpyFu · Schema
SpyFu Ad History API Schemas
JSON Schema definitions for SpyFu Ad History API API responses
SEOPPCCompetitive IntelligenceKeyword ResearchAd HistoryBacklinksDomain AnalyticsSERP
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "SpyFu Ad History API Schemas",
"description": "JSON Schema definitions for SpyFu Ad History API API responses",
"definitions": {
"AdHistoryApi_GetDomainAdHistory_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Domain Ad History",
"description": "Response wrapper containing domain ad history results with pagination metadata.",
"type": "object",
"properties": {
"resultCount": {
"description": "Number of results returned",
"type": "integer",
"format": "int32",
"examples": [
100
],
"readOnly": true
},
"results": {
"description": "Array of ads with their associated keywords found for the specified domain.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"keywords": {
"description": "List of keywords that triggered this ad to appear in search results.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"examples": [
[
"running shoes",
"athletic shoes",
"sports footwear"
]
]
},
"position": {
"description": "The ad's position on the search results page when it was captured (1 = top position).",
"type": "integer",
"format": "int32",
"examples": [
1
]
},
"searchDateId": {
"description": "Date when this ad was captured by SpyFu's crawling system, formatted as YYYYMMDD (e.g., 20231215 = December 15, 2023).",
"type": "integer",
"format": "int32",
"examples": [
20231215
]
},
"title": {
"description": "The headline text of the ad as it appeared in search results.",
"type": [
"string",
"null"
],
"examples": [
"Best Running Shoes 2024 - Free Shipping"
]
},
"body": {
"description": "The description text of the ad providing additional details about the offer.",
"type": [
"string",
"null"
],
"examples": [
"Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order."
]
},
"url": {
"description": "The landing page URL that the ad directed users to when clicked.",
"type": [
"string",
"null"
],
"examples": [
"https://example.com/running-shoes"
]
},
"adId": {
"description": "Unique identifier for this specific ad in SpyFu's database.",
"type": "integer",
"format": "int32",
"examples": [
12345678
]
}
},
"additionalProperties": false,
"description": "Represents an ad with associated keywords that triggered it to appear in search results."
},
"readOnly": true
}
},
"additionalProperties": false
},
"AdHistoryApi_GetTermAdHistory_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Keyword Ad History",
"description": "Response wrapper containing term ad history results with pagination metadata.",
"type": "object",
"properties": {
"resultCount": {
"description": "Number of results returned",
"type": "integer",
"format": "int32",
"examples": [
100
],
"readOnly": true
},
"results": {
"description": "Array of ads found for the specified keyword with associated landing pages and advertiser information.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"domainName": {
"description": "The domain name of the advertiser who placed this ad.",
"type": [
"string",
"null"
],
"examples": [
"example.com"
]
},
"urls": {
"description": "List of landing page URLs that this ad directed users to when clicked.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"examples": [
[
"https://example.com/running-shoes",
"https://example.com/athletic-footwear"
]
]
},
"position": {
"description": "The ad's position on the search results page when it was captured (1 = top position).",
"type": "integer",
"format": "int32",
"examples": [
1
]
},
"searchDateId": {
"description": "Date when this ad was captured by SpyFu's crawling system, formatted as YYYYMMDD (e.g., 20231215 = December 15, 2023).",
"type": "integer",
"format": "int32",
"examples": [
20231215
]
},
"title": {
"description": "The headline text of the ad as it appeared in search results.",
"type": [
"string",
"null"
],
"examples": [
"Best Running Shoes 2024 - Free Shipping"
]
},
"body": {
"description": "The description text of the ad providing additional details about the offer.",
"type": [
"string",
"null"
],
"examples": [
"Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order."
]
},
"adId": {
"description": "Unique identifier for this specific ad in SpyFu's database.",
"type": "integer",
"format": "int32",
"examples": [
12345678
]
}
},
"additionalProperties": false,
"description": "Represents ad data for a specific keyword with associated advertiser information and landing pages."
},
"readOnly": true
}
},
"additionalProperties": false
},
"AdHistoryApi_GetTermAdHistoryWithStats_GET": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Get Keyword Ad History With Stats",
"description": "Response wrapper containing comprehensive term ad history statistics including advertiser analysis and top-performing ads.",
"type": "object",
"properties": {
"resultCount": {
"description": "Number of results returned",
"type": "integer",
"format": "int32",
"examples": [
100
],
"readOnly": true
},
"domains": {
"description": "Array of domains (advertisers) that have purchased ads for the specified keyword, ranked by performance metrics.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"ads": {
"description": "Collection of ads this domain has purchased for the specified keyword.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"searchDateId": {
"description": "Date when this ad was captured by SpyFu's crawling system, formatted as YYYYMMDD (e.g., 20231215 = December 15, 2023).",
"type": "integer",
"format": "int32",
"examples": [
20231215
]
},
"position": {
"description": "The ad's position on the search results page when it was captured (1 = top position).",
"type": "integer",
"format": "int32",
"examples": [
1
]
},
"title": {
"description": "The headline text of the ad as it appeared in search results.",
"type": [
"string",
"null"
],
"examples": [
"Best Running Shoes 2024 - Free Shipping"
]
},
"body": {
"description": "The description text of the ad providing additional details about the offer.",
"type": [
"string",
"null"
],
"examples": [
"Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order."
]
},
"domainName": {
"description": "The domain name of the advertiser who placed this ad.",
"type": [
"string",
"null"
],
"examples": [
"example.com"
]
},
"fullUrl": {
"description": "The complete landing page URL that the ad directed users to when clicked.",
"type": [
"string",
"null"
],
"examples": [
"https://example.com/running-shoes?utm_source=google&utm_campaign=shoes"
]
},
"term": {
"description": "The search keyword that triggered this ad to appear in search results.",
"type": [
"string",
"null"
],
"examples": [
"running shoes"
]
},
"adCount": {
"description": "The number of times this specific ad variation was observed during the capture period.",
"type": "integer",
"format": "int32",
"examples": [
45
]
},
"isLeaderboardAd": {
"description": "Indicates whether this ad appeared in the top ad positions (leaderboard) rather than sidebar positions.",
"type": "boolean",
"examples": [
true
]
}
},
"additionalProperties": false,
"description": "Represents a single ad from SpyFu's historical advertising database with complete ad copy and metadata."
}
},
"budget": {
"description": "Estimated monthly advertising budget this domain spends on the specified keyword.",
"type": "number",
"format": "double",
"examples": [
15000.5
]
},
"coverage": {
"description": "Percentage of time this domain appears in ads for the specified keyword (0-100).",
"type": "number",
"format": "double",
"examples": [
73.2
]
},
"domainName": {
"description": "The domain name of the advertiser.",
"type": [
"string",
"null"
],
"examples": [
"example.com"
]
},
"percentageLeaderboard": {
"description": "Percentage of time this domain's ads appear in top positions (leaderboard) rather than sidebar positions.",
"type": "number",
"format": "double",
"examples": [
85.7
]
},
"totalAdsPurchased": {
"description": "Total number of ads this domain has purchased across all keywords in SpyFu's database.",
"type": "integer",
"format": "int32",
"examples": [
2847
]
},
"adCount": {
"description": "Number of ads this domain has purchased specifically for the requested keyword.",
"type": "integer",
"format": "int32",
"examples": [
45
]
}
},
"additionalProperties": false,
"description": "Represents an advertiser (domain) that purchases ads for a specific keyword, including their ad performance metrics and budget estimates."
}
},
"topAds": {
"description": "Array of the most successful ads for the specified keyword, ranked by performance and frequency metrics.",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"adId": {
"description": "Unique identifier for this specific ad in SpyFu's database.",
"type": "integer",
"format": "int32",
"examples": [
12345678
]
},
"averagePosition": {
"description": "Average position where this ad appeared on search results pages across all observations.",
"type": "number",
"format": "double",
"examples": [
2.4
]
},
"averageAdCount": {
"description": "Average total number of ads per capture period.",
"type": "number",
"format": "double",
"examples": [
2.1
]
},
"body": {
"description": "The description text of the ad providing additional details about the offer.",
"type": [
"string",
"null"
],
"examples": [
"Discover premium running shoes with advanced cushioning technology. Shop now and save 20% on your first order."
]
},
"title": {
"description": "The headline text of the ad as it appeared in search results.",
"type": [
"string",
"null"
],
"examples": [
"Best Running Shoes 2024 - Free Shipping"
]
},
"fullUrl": {
"description": "The complete landing page URL that the ad directed users to when clicked.",
"type": [
"string",
"null"
],
"examples": [
"https://example.com/running-shoes?utm_source=google&utm_campaign=shoes"
]
},
"leaderboardCount": {
"description": "Number of times this ad appeared in top ad positions (leaderboard) rather than sidebar positions.",
"type": "integer",
"format": "int32",
"examples": [
42
]
},
"percentageLeaderboard": {
"description": "Percentage of time this ad appeared in top ad positions versus sidebar positions.",
"type": "number",
"format": "double",
"examples": [
73.5
]
},
"percentageAdsServed": {
"description": "Percentage of total ad impressions this specific ad variation represented for the advertiser.",
"type": "number",
"format": "double",
"examples": [
28.7
]
}
},
"additionalProperties": false,
"description": "Represents a top-performing ad with aggregated performance metrics across multiple observations."
}
}
},
"additionalProperties": false
}
}
}