{ "openapi": "3.0.1", "info": { "title": "Competitor Keyword Research API - SpyFu SEO, PPC, Ad History", "description": "Competitor keyword research with the SpyFu API: organic and PPC keywords any domain ranks for or buys, SEO and PPC competitors, ad copy history, top pages, monthly domain traffic stats, keyword volume, CPC, difficulty and Google top 100 SERP. Bring your own key.", "version": "0.1", "x-build-id": "48FGZu3JG9TgqNqgQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~ppc-competitor-keyword-research-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-ppc-competitor-keyword-research-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~ppc-competitor-keyword-research-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-ppc-competitor-keyword-research-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~ppc-competitor-keyword-research-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-ppc-competitor-keyword-research-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "What to get", "enum": [ "seoKeywords", "ppcKeywords", "newPpcKeywords", "domainAds", "seoCompetitors", "ppcCompetitors", "topPages", "domainStats", "domainStatsHistory", "domainAdHistory", "keywordResearch", "keywordMetrics", "keywordSerp", "keywordAdHistory" ], "type": "string", "description": "Domain modes take domains: the organic keywords a domain ranks for (with gains, losses and new rankings), the PPC keywords it buys, the ads it shows, its SEO and PPC competitors, its top pages, its monthly SEO and PPC stats, and its ad history. Keyword modes take keywords: keyword research, metrics for a keyword list, the Google top 100 and the advertisers and ads for a keyword.", "default": "seoKeywords" }, "domains": { "title": "Domains", "type": "array", "description": "Domain modes only. Domains to analyse, one per line, such as nike.com. A scheme, www. and any path are removed, except for Domain organic keywords, PPC keywords and Top organic pages, which also read a URL, subdomain or path such as nike.com/running/.", "items": { "type": "string" } }, "keywords": { "title": "Keywords", "type": "array", "description": "Keyword modes only. Keywords to look up, one per line, up to 200 characters each.", "items": { "type": "string" } }, "countryCode": { "title": "Country", "enum": [ "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" ], "type": "string", "description": "The Google country version SpyFu reads, such as US for google.com or DE for google.de. Search volume, rankings and ads all come from that country.", "default": "US" }, "seoSearchType": { "title": "SEO keyword analysis", "enum": [ "MostValuable", "NewlyRanked", "GainedRanks", "LostRanks", "GainedClicks", "LostClicks", "JustMadeIt", "JustFellOff" ], "type": "string", "description": "Domain organic keywords only. Which SpyFu keyword analysis to run; the movement analyses compare with the previous month.", "default": "MostValuable" }, "compareDomain": { "title": "Compare with domain", "type": "string", "description": "Domain organic keywords only. A second domain, such as a competitor; each row then also carries that domain's rank, rank change and URL (yourRank, yourRankChange, yourUrl)." }, "topPagesType": { "title": "Top pages type", "enum": [ "MostTraffic", "New" ], "type": "string", "description": "Top organic pages only.", "default": "MostTraffic" }, "keywordSearchType": { "title": "Keyword research type", "enum": [ "PhraseMatch", "Questions", "AlsoBuysAdsFor", "AlsoRanksFor", "Transactions" ], "type": "string", "description": "Keyword research only. Phrase match finds thematically related keywords, Questions finds question keywords, Also buys ads for finds what the seed keyword's advertisers also buy, Also ranks for finds what its top ranking sites also rank for, and Transactional finds keywords with buying intent.", "default": "PhraseMatch" }, "historyMonths": { "title": "Months of stats", "minimum": 0, "maximum": 240, "type": "integer", "description": "Domain SEO and PPC stats only. 0 returns the latest month; a higher number returns that many recent months, one row each.", "default": 0 }, "keywordFilter": { "title": "Keyword contains", "type": "string", "description": "Top organic pages and Domain ad history only. Only pages or ads for keywords containing this text." }, "serpDepth": { "title": "SERP depth", "minimum": 1, "maximum": 105, "type": "integer", "description": "Keyword SERP top 100 only. How many ranking results to read per keyword (1 to 105).", "default": 100 }, "includeTerms": { "title": "Keyword must contain", "type": "array", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research. Only keywords that contain these terms (all of them, or any with the next option).", "items": { "type": "string" } }, "matchAnyTerm": { "title": "Match any term", "type": "boolean", "description": "With Keyword must contain: keep keywords containing any of the terms instead of all of them.", "default": false }, "excludeTerms": { "title": "Exclude terms", "type": "array", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research. Leave out keywords containing these terms, such as brand names.", "items": { "type": "string" } }, "volumeMin": { "title": "Minimum search volume", "minimum": 0, "type": "integer", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research and Keyword metrics. Only keywords with at least this monthly Google search volume." }, "volumeMax": { "title": "Maximum search volume", "minimum": 0, "type": "integer", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research and Keyword metrics. Only keywords with at most this monthly Google search volume." }, "difficultyMin": { "title": "Minimum keyword difficulty", "minimum": 0, "maximum": 100, "type": "integer", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research and Keyword metrics. Only keywords with a ranking difficulty of at least this (0 to 100)." }, "difficultyMax": { "title": "Maximum keyword difficulty", "minimum": 0, "maximum": 100, "type": "integer", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research and Keyword metrics. Only keywords with a ranking difficulty of at most this (0 to 100)." }, "cpcMin": { "title": "Minimum CPC (USD)", "minimum": 0, "type": "number", "description": "Domain organic keywords, PPC keywords, Keyword research and Keyword metrics. Only keywords with a cost per click of at least this." }, "cpcMax": { "title": "Maximum CPC (USD)", "minimum": 0, "type": "number", "description": "Domain organic keywords, PPC keywords, Keyword research and Keyword metrics. Only keywords with a cost per click of at most this." }, "cpcMatchType": { "title": "CPC match type", "enum": [ "Broad", "Exact", "Phrase" ], "type": "string", "description": "Which match type's cost per click the CPC range reads. Sent only with a CPC range.", "default": "Broad" }, "rankMin": { "title": "Best rank", "minimum": 1, "maximum": 100, "type": "integer", "description": "Domain organic keywords only. Only rankings at this Google position or lower down." }, "rankMax": { "title": "Worst rank", "minimum": 1, "maximum": 100, "type": "integer", "description": "Domain organic keywords only. Only rankings at this Google position or higher up, such as 10 for page one." }, "excludeHomepageKeywords": { "title": "Exclude homepage keywords", "type": "boolean", "description": "Domain organic keywords and Paid search ads only. Leave out keywords the homepage ranks for.", "default": false }, "questionsOnly": { "title": "Questions only", "type": "boolean", "description": "PPC keywords, Keyword research and Keyword metrics only. Keep only question keywords.", "default": false }, "transactionalOnly": { "title": "Transactional intent only", "type": "boolean", "description": "PPC keywords, Keyword research and Keyword metrics only. Keep only keywords with buying intent.", "default": false }, "includeAdult": { "title": "Include adult keywords", "type": "boolean", "description": "Domain organic keywords, Most successful PPC keywords, New PPC keywords, Paid search ads and Keyword research and Keyword metrics. SpyFu leaves out adult keywords by default; tick to keep them.", "default": false }, "seoSortBy": { "title": "Sort SEO keywords by", "enum": [ "default", "SearchVolume", "KeywordDifficulty", "Rank", "RankChange", "SeoClicks", "SeoClicksChange", "PercentMobileSearches", "PercentDesktopSearches", "PercentNotClicked", "PercentPaidClicks", "PercentOrganicClicks", "BroadCostPerClick", "ExactCostPerClick", "PhraseCostPerClick", "BroadMonthlyCost", "ExactMonthlyCost", "PhraseMonthlyCost", "TotalMonthlyClicks", "PaidCompetitors", "RankingHomepages" ], "type": "string", "description": "Domain organic keywords only. Provider default is search volume.", "default": "default" }, "keywordSortBy": { "title": "Sort keywords by", "enum": [ "default", "SearchVolume", "LiveSearchVolume", "RankingDifficulty", "TotalMonthlyClicks", "PercentMobileSearches", "PercentDesktopSearches", "PercentSearchesNotClicked", "PercentPaidClicks", "PercentOrganicClicks", "BroadCostPerClick", "PhraseCostPerClick", "ExactCostPerClick", "BroadMonthlyClicks", "PhraseMonthlyClicks", "ExactMonthlyClicks", "BroadMonthlyCost", "PhraseMonthlyCost", "ExactMonthlyCost", "PaidCompetitors", "RankingHomepages" ], "type": "string", "description": "PPC keywords and Keyword research only.", "default": "default" }, "adSortBy": { "title": "Sort ads by", "enum": [ "default", "SearchVolume", "KeywordDifficulty", "AdPosition", "AdCount", "DateSearched" ], "type": "string", "description": "Paid search ads only.", "default": "default" }, "competitorSortBy": { "title": "Sort competitors by", "enum": [ "default", "Rank", "CommonTerms", "Domain" ], "type": "string", "description": "SEO and PPC competitors only. Provider default is rank.", "default": "default" }, "adHistorySortBy": { "title": "Sort ad history by", "enum": [ "default", "Best", "Worst", "KeywordAsc", "KeywordDesc", "SearchDateId" ], "type": "string", "description": "Domain ad history only.", "default": "default" }, "sortOrder": { "title": "Sort order", "enum": [ "Descending", "Ascending" ], "type": "string", "description": "Keyword, ad, competitor and top page lists.", "default": "Descending" }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most rows this run returns and charges for. SpyFu also bills your account per row returned (0.20 to 5.00 USD per 1,000 rows by endpoint), so keep this modest.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 600, "type": "integer", "description": "Pacing. SpyFu limits each endpoint per second (2 a second for top pages, 5 to 1,000 for others); a rate limit answer is waited out and retried.", "default": 120 }, "apiKey": { "title": "API key (Secret Key)", "type": "string", "description": "Your own SpyFu Secret Key, from your SpyFu account (spyfu.com/account/api, under API Usage). Stored as a secret and sent only as the api_key parameter to api.spyfu.com; it is never logged. You can instead set the DATA_API_KEY environment secret." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }