Ads examples
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 — Ads examples report.
General request parameters and instructions for using Serpstat API
Search databases available
|
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 (there are both Google and Yandex databases available, for example: g_us or y_157). |
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}}} |
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 |
| filter | Fillter conditions | array | yes |
"right_spelling": true; "right_spelling": false minus_domain : www.domain.com subdomain : blog.domain.com url (exact_url) : https://www.apple.com/airpods/ types : "carousel", "also_asks" keyword_length : num "region_queries_count": "1000"; "region_queries_count_wide": "1000"; "position": 1 "cost": "10"; "concurrency": "7"; "difficulty": 3; |
|
| 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
},{
"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"
}
}{
"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
}
}
}