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. | 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
}
}
}