Keyword Ads V4 (SerpstatKeywordProcedure.getAdKeywords)

The SerpstatKeywordProcedure.getAdKeywords returns paid keywords and ads copies that pop up for the queried keyword in paid search results. The data set is similar to the Keyword research — PPC research — Keywords report.

General request parameters and instructions for using Serpstat API

Request parameters
Parameter	Description	Type	Optional	Default value	Value Options
id	A request id: the response contains the same id. Enter any number (number) or text (string) value	int/string	no		1, test
method	API method name	string	no		SerpstatKeywordProcedure.getAdKeywords
params	The object with parameters {...}, it lists all the following parameters and arrays [...]	array	no
keyword	Keyword to search for	string	no		iphone
se	ID of the search base to be searched	string	no		g_us
domains	Domains list	array	yes	[ ]	["apple.com","verizon.com"]
minusKeywords	Negative keywords	array	yes	[]	["app", "apple"]
filters	Filter conditions	json object	yes		{"queries_from": 10} {"queries_to": 100}
sort	Order of sorting the results in the format: {{{field}}: {{order}}} field — field to sort by: * keyword_length * position * type * cost * concurrency * found_results * region_queries_count * region_queries_count_wide order — sort direction (asc — ascending, desc — descending)	json object	yes	{"position": "asc", "region_queries_count":"desc"}	{"cost": "asc"}
page	Page number in response	int	yes	1	"page": "5"
size	Number of results per page in response	int	yes	100	"size": "10" min: 1, max: 1000

To filter the results, use the following parameters:

Parameter	Description	Possible values
queries_from	Min volume of monthly searches	0-100000000
queries_to	Max volume of monthly searches	0-100000000
position_from	Min position	1-100
position_to	Max position	1-100
cost_from	Min CPC	0-200
cost_to	Max CPC	0-200
concurrency_from	Min value of competitor’s keyword in the PPC	0-100
concurrency_to	Max value of competitor’s keyword in the PPC	0-100
results_from	Min result value	0-100000000
results_to	Max result value	0-100000000
length_from	Min value of a keyword’s length	0-100000000
length_to	Max value of a keyword’s length	0-100000000

Response parameters
Parameter	Description
id	Response id corresponds the request id
result	Contains the answer
data	Array with data
keyword	Keyword which domain's ad is displayed in SERP
keyword_length	Number of words divided by space in a keyword
domain	Domain
subdomain	Subdomain of the domain
url	URL where the ad leads
title	Ad title
text	Ad text
position	Ad position
type	Ad placement type in relation to SERP (1 - above; 2 - under; 3 - side)
cost	Cost per click, $
Cost per click, $	Keyword competition in the PPC (0-100%)
found_results	Number of results found for the keyword
region_queries_count	Search volume in selected region
region_queries_count_wide	Search volume (broad match)
types	List of special elements shown in SERP (for example, video, carousel or map)
geo_names	List of toponyms in the array (if toponyms are present in the keywords)
difficulty	The assessment of the level of competition for a keyword to advance in organic search in the top-10 (from 0 to 100%)
summary_info	Object with data
page	Page number
total	Number of paid search results for the keyword
left_lines	API credits remaining

Credits: the number of charged credits corresponds to the number of results obtained upon request. Part of the API response, for which 1 credit is charged:

{
    "keyword": "upgrade iphone x to xs",
    "keyword_length": 5,
    "domain": "apple.com",
    "subdomain": "www.apple.com",
    "url": "https://www.apple.com/iphone/",
    "title": "Trade in for iPhone 12 - Apple Official Site",
    "text": "Get $90 - $515 off iPhone 12 when you trade in an iPhone 7 or newer. Terms apply. A14 Bionic Chip. 5G speed. Ceramic Shield. Super Retina XDR display. Services: Free no-contact delivery, Finance with Apple Card, 3% cash back w/Apple Card, Prepaid mail-in kit.",
    "position": 2,
    "type": "1",
    "cost": 0,
    "concurrency": 50,
    "found_results": 325000000,
    "region_queries_count": 10,
    "region_queries_count_wide": 0,
    "types": [
        "carousel",
        "also_asks",
        "video",
        "ads_top"
        ],
    "geo_names": [],
    "difficulty": null
},

Example

Request data:

{
 "id": "1",
 "method": "SerpstatKeywordProcedure.getAdKeywords",
 "params": {
   "keyword": "iphone",
   "se": "g_us",
   "domains": ["apple.com","verizon.com"],
   "filters": {"position_from": "2", "position_to":"3"},
   "sort" : {"region_queries_count":"asc"},
   "page": "1",
   "size": "10"
    }
}

Response data:

{
    "id": "1",
    "result": {
        "data": [
            {
                "keyword": "upgrade iphone x to xs",
                "keyword_length": 5,
                "domain": "apple.com",
                "subdomain": "www.apple.com",
                "url": "https://www.apple.com/iphone/",
                "title": "Trade in for iPhone 12 - Apple Official Site",
                "text": "Get $90 - $515 off iPhone 12 when you trade in an iPhone 7 or newer. Terms apply. A14 Bionic Chip. 5G speed. Ceramic Shield. Super Retina XDR display. Services: Free no-contact delivery, Finance with Apple Card, 3% cash back w/Apple Card, Prepaid mail-in kit.",
                "position": 2,
                "type": "1",
                "cost": 0,
                "concurrency": 50,
                "found_results": 325000000,
                "region_queries_count": 10,
                "region_queries_count_wide": 0,
                "types": [
                    "carousel",
                    "also_asks",
                    "video",
                    "ads_top"
                ],
                "geo_names": [],
                "difficulty": null
            },
            {
                "keyword": "iphone 7128gb price",
                "keyword_length": 3,
                "domain": "apple.com",
                "subdomain": "www.apple.com",
                "url": "https://www.apple.com/iphone/",
                "title": "iPhone - Apple Official Site",
                "text": "Blast past fast. iPhone 12 now in purple. Pre-order on 4.23. Save up to $320 on iPhone 12 after trade-in with T-Mobile. Terms apply. Water resistant. Retina display. Wide camera. Privacy built in. Services: Online personal session, Chat for shopping help.",
                "position": 2,
                "type": "3",
                "cost": 0,
                "concurrency": 0,
                "found_results": 1170000,
                "region_queries_count": 10,
                "region_queries_count_wide": 0,
                "types": [
                    "a_box_fsnippet",
                    "kn_graph_brand",
                    "also_asks",
                    "shopping_top",
                    "ads_bot"
                ],
                "geo_names": [],
                "difficulty": null
            }
        ],
        "summary_info": {
            "page": 1,
            "total": 178,
            "left_lines": 998625
        }
    }
}