API Description
Competitor SEO/PPC Research
Competitor SEO/PPC research API allows to get competitor and keyword statistics from organic and paid search results in a convenient form.
To access the section, you should have an active subscription or positive account balance.
Errors
| HTTP code | Error message |
| 403 | License expired |
Domain overview (all databases)
Description
The method allows to get data on all databases related to the domain.
Request format
GET https://api4.seranking.com/research/overview?domain=seranking.comRequest parameters
| Name | Required | Description |
| domain | Yes | Domain |
Result
If successful, the server returns a list of available databases and the total number of keywords in each database.
Example
[{ "source": "us", "year_month": "2018-10", "organic": { "count": 790, "traffic": 3149, "cost": 23167.97 }, "adv": { "count": 140, "traffic": 2968, "cost": 17795.26 } }]
Response parameters
| Name | Description |
| source | Alpha-2 code of the country you’re checking |
| year_month | Year and month of database data |
| organic | Organic traffic data |
| adv | Paid traffic data |
| count | Total number of keywords |
| traffic | Traffic forecast |
| cost | Cost estimate |
Errors
| HTTP code | Error message |
| 400 | Invalid domain |
Domain overview (selected database)
Description
This method returns keyword statistics for organic or paid traffic for the selected database.
Request format
GET https://api4.seranking.com/research/{source}/overview/?domain=domain.com
Request parameters
| Name | Required | Description |
| source | Yes | Alpha-2 code of the country you’re checking |
| domain | Yes | Domain |
| with_subdomains | No | 1 – take subdomains into account (by default)0 – not take subdomains into account |
Result
If successful, the server returns keyword statistics for organic or paid traffic for the selected database.
Example
{
"organic": {
"keywords_new_count": 182,
"keywords_up_count": 292,
"keywords_equal_count": 55,
"keywords_lost_count": 282,
"top11_20": 127,
"top51_100": 331,
"keywords_down_count": 558,
"top1_5": 25,
"top21_50": 270,
"top6_10": 52,
"count": 790,
"traffic": 3149,
"cost": 23167.97
},
"adv": {
"keywords_new_count": 91,
"keywords_up_count": 17,
"keywords_equal_count": 18,
"keywords_lost_count": 62,
"top11_20": 0,
"top1_2": 53,
"top51_100": 0,
"keywords_down_count": 76,
"top1_5": 121,
"top21_50": 0,
"top3_5": 68,
"top6_8": 19,
"top9_11": 0,
"top6_10": 19,
"count": 140,
"traffic": 2968,
"cost": 17795.26
}
}
Response parameters
| Name | Description |
| organic | Organic traffic data |
| adv | Paid traffic data |
| count | Total number of keywords |
| traffic | Traffic forecast |
| cost | Cost estimate |
| top1_5 | Total number of keywords ranked 1-5 |
| top6_10 | Total number of keywords ranked 6-10 |
| top11_20 | Total number of keywords ranked 11-20 |
| top1_2 | Total number of keywords ranked 1, 2 (for paid traffic) |
| top3_5 | Total number of keywords ranked 3, 4, 5 (for paid traffic) |
| top6_8 | Total number of keywords ranked 6, 7, 8 (for paid traffic) |
| top9_11 | Total number of keywords ranked 9, 10, 11 (for paid traffic) |
| keywords_new_count | Total number of keywords |
| keywords_lost_count | Total number of keywords dropped from SERPs |
| keywords_equal_count | Ranking positions are unchanged |
| keywords_up_count | Ranking position rise |
| keywords_down_count | Ranking position drop |
Errors
| HTTP code | Error message |
| 400 | Invalid domain |
| 404 | Invalid source |
Domain overview (worldwide)
Description
The method allows you to get the domain’s worldwide statistics for the current month.
Request format
GET https://api4.seranking.com/research/worldwide-overview?domain=seranking.com&fields=price,traffic,keywords,positions_diff,positions_tops&show_zones_list=0¤cy=USDRequest parameters
| Name | Required | Description |
| domain | Yes | Domain |
| currency | No | ISO 4217 currency code. Default value: USD |
| fields | No | Comma-separated list of expected fields. Default value: price,traffic,keywords. List of field values: price – show traffic price valuetraffic – show traffic valuekeywords – show keywords statspositions_diff – shows position changes fieldspositions_tops – shows position tops |
| show_zones_list | No | Boolean value to determine if the response should include stats for each zone or only worldwide. Default value: ‘0’ |
Result
If successful, the server returns organic and adv stat lists. The lists include worldwide and statistics per zone (if show_zones_list is 1).
Example:
{
"organic": [
{
"source": "worldwide",
"country": "Worldwide",
"keywords_count": 823967,
"traffic_sum": 273150,
"price_sum": 241482.11,
"positions_new_count": 56042,
"positions_up_count": 56326,
"positions_down_count": 49834,
"positions_lost_count": 47169,
"positions_equal_count": 876005,
"positions_tops": { "top1_5": 91520, "top6_10": 95652, "top11_20": 165641, "top21_50": 332015, "top51_100": 353061 }
}
],
"adv": [
{
"source": "worldwide",
"country": "Worldwide",
"keywords_count": 4947,
"traffic_sum": 4369,
"price_sum": 6509.45,
"positions_new_count": 333,
"positions_up_count": 7,
"positions_down_count": 4,
"positions_lost_count": 1742,
"positions_equal_count": 5645,
"positions_tops": { "top1_2": 4905, "top3_5": 1046, "top6_8": 38, "top9_11": 0 }
}
]
}
Domain overview (history)
Description
The method allows to get historical data on parameters (number of keywords, clicks, cost) for organic or paid traffic.
Request format
GET https://api4.seranking.com/research/{source}/overview/history/?domain=domain.com&type=organic
Request parameters
| Name | Required | Description |
| source | Yes | Alpha-2 code of the country you’re checking |
| domain | Yes | Domain |
| type | No | organic – organic traffic data (default)adv – paid traffic data |
Result
If successful, the server returns historical data on certain parameters for organic or paid traffic.
Example:
[{ "keywords_count": 51, "traffic_sum": 184, "price_sum": 1095.87, "year": 2016, "month": 9, "top1_2": 13, "top3_5": 18, "top6_8": 20, "top9_11": 0 }]
Response parameters
| Name | Description |
| keywords_count | Number of keywords |
| traffic_sum | Traffic forecast |
| price_sum | Cost estimate |
| year | Year |
| month | Month |
| top1_5 | Total number of keywords ranked 1-5 |
| top6_10 | Total number of keywords ranked 6-10 |
| top11_20 | Total number of keywords ranked 11-20 |
| top21_50 | Total number of keywords ranked 21-50 |
| top51_100 | Total number of keywords ranked 51-100 |
| top1_2 | Total number of keywords ranked 1, 2 (for paid traffic) |
| top3_5 | Total number of keywords ranked 3, 4, 5 (for paid traffic) |
| top6_8 | Total number of keywords ranked 6, 7, 8 (for paid traffic) |
| top9_11 | Total number of keywords ranked 9, 10, 11 (for paid traffic) |
Errors
| HTTP code | Error message |
| 400 | Invalid domain |
| 404 | Invalid source |
Domain keywords
Description
This method allows to get a list of keywords for a domain.
Request format
GET https://api4.seranking.com/research/{source}/keywords/?domain=domain.com&type=organic&order_field=position&order_type=desc&cols=position,prev_pos
Request parameters
| Name | Required | Description |
| source | Yes | Alpha-2 code of the country you’re checking |
| domain | Yes | Domain |
| type | No | organic – organic traffic data (default)adv – paid traffic data |
| order_field | No | Sort field (traffic by default) |
| order_type | No | asc or desc (by default) |
| page | No | Results page (by default – 1) |
| limit | No | Number of elements (by default – 100, max. 1000) |
| cols | No | List of return values (comma-separated) |
| pos_change | No | Position change filter. up – position growthdown – position dropnew – new in the SERPlost – dropped out of the SERPdiff – positions have changedsame – positions have not changed |
| filter[volume][from] | No | Specifies the minimum search volume value.Type: int |
| filter[volume][to] | No | Specifies the maximum search volume value.Type: int |
| filter[difficulty][from] | No | Specifies the minimum search difficulty value.Type: int |
| filter[difficulty][to] | No | Specifies the maximum search difficulty value.Type: int |
| filter[keyword_count][from] | No | Specifies the minimum search keyword count value.Type: int |
| filter[keyword_count][to] | No | Specifies the minimum search keyword count value.Type: int |
| filter[multi_keyword_included] | No | Specifies keyword text included in the search based on the JSON structure (more information in the Text search JSON structure section). Type: json |
| filter[multi_keyword_excluded] | No | Specifies keyword text excluded from the search based on the JSON structure (more information in the Text search JSON structure section). Type: json |
| filter[url] | No | Specifies text search in URL based on the JSON structure (more information in the Text search JSON structure section). The structure should have only one element in the base array, so no OR logic.Type: json |
| filter[intents] | No | List of keyword search intents separated by a comma. Example I, N, T, C, L, where: I – InformationalN – NavigationalT – TransactionalC – CommercialL – Local Type: string |
| filter[competition][from] | No | Specifies the minimum search competition value.Type: float |
| filter[competition][to] | No | Specifies the maximum search competition value.Type: float |
| filter[cpc][from] | No | Specifies the minimum search CPC value.Type: float |
| filter[cpc][to] | No | Specifies the maximum search CPC value.Type: float |
| filter[traffic][from] | No | Specifies the minimum search traffic value.Type: int |
| filter[traffic][to] | No | Specifies the maximum search traffic value.Type: int |
| filter[position][from] | No | Specifies the minimum search position value.Type: int |
| filter[position][to] | No | Specifies the maximum search position value.Type: int |
| filter[characters_count][from] | No | Specifies the minimum search keyword character count value.Type: int |
| filter[characters_count][to] | No | Specifies the maximum search keyword character count value.Type: int |
Result
If successful, the server returns a list of keywords for the specified domain and its parameters.
Example
[
{
keyword: "seranking.com",
position: 1,
prev_pos: 1,
volume: "10",
cpc: "0.00",
competition: "0.00",
url: "https://seranking.com/",
kei: 1.136,
total_sites: 88,
traffic: 3,
traffic_percent: "11.11%",
price: 0,
},
]
Response parameters
| Name | Description |
| keyword | Keyword |
| position | Position |
| prev_pos | Position in the previous month |
| volume | Volume |
| cpc | CPC |
| competition | Competition |
| url | URL |
| kei | KEI |
| total_sites | Total number of sites for query |
| traffic | Traffic |
| traffic_percent | Traffic share |
| price | Cost |
For paid traffic (type=adv), you get information about the ad in addition to the parameters above.
Example
[
{
"keyword": "nyc hotels",
"position": 4,
"prev_pos": 4,
"volume": "550000",
"cpc": "3.75",
"competition": "0.16",
"url": "https://www.booking.com/city/us/new-york.html",
"kei": 355.464,
"total_sites": 851000000,
"traffic": 11000,
"traffic_percent": "0.96%",
"price": 41250,
"block": "top",
"snippet_num": 579,
"snippets_count": 1,
"snippet_title": "Hotels in New York, NY | Lowest Price Guarantee.",
"snippet_description": "Book your Hotel in New York NY online. No reservation costs. Great rates. 24/7 Customer Service. Hotels. Secure Booking. Villas. Hostels. No Booking Fees. Best Price Guarantee.",
"snippet_display_url": "www.booking.com/city/us/new-york.html"
}
]
| block | top | bottom – ad type |
| snippet_num | Ad number |
| snippets_count | Number of ads |
| snippet_title | Ad title |
| snippet_description | Ad text |
| snippet_display_url | Displayed ad URL |
Errors
| HTTP code | Error message |
| 400 | Incorrect order |
| 400 | Row limit exceeded |
| 400 | Invalid domain |
| 400 | Invalid source |
Text search JSON structure
The text search structure allows for the creation of complex text searches by providing a JSON string in the format array<array<object>>. The first layer of the array corresponds to elements separated by logical OR, while the second layer corresponds to elements with logical AND. Each object within the array has the following structure:
{"type":"begins","value":"google"}
| Name | Description |
| object.value | Contains the text value to be searched. |
| object.type | Specifies the type of search to be performed. |
List of Possible object.type variants:
| Name | Description |
| begins | The searched text should start with the specified value. |
| contains | The searched text should contain the specified value anywhere within the text. |
| ends | The searched text should end with the specified value. |
| exact | The searched text should exactly match the specified value. |
Paid ads for keyword
Description
The method allows to get an overview of paid ads for a keyword.
Request format
GET https://api4.seranking.com/research/{source}/advertising/?keyword=seo
Request parameters
| Name | Required | Description |
| keyword | Yes | Keyword |
| from | No | Year and month of the beginning of the period (2017-01) |
| to | No | Year and month of the end of the period (2018-12) |
| page | No | Results page (by default – 1) |
| limit | No | Number of elements (by default – 100, maximum 100) |
Result
If successful, the server returns an overview of paid ads for the specified keyword.
Example
[
{
domain:"hotels.com",
ads_count: 19,
keywords_count: 78972,
traffic_sum: 3565364,
price_sum: 10411189,
snippets:{
'2018 - 11': {
position:2,
snippet_title: "Booking | Hotels.com",
snippet_description: "Stay 10 nights & get 1 free! Redeem your reward night anytime, anywhere. Last Minute Hotel Deals. Exclusive Deals. Photos & Reviews. Price Guarantee. Earn Free Hotel Nights. Guest Reviews. No Cancellation Fees. Travel Guides. Luxury Hotels. Budget Hotels.",
snippet_display_url: "www.hotels.com/",
snippet_count: "1",
url: "https://www.hotels.com/"
},
},
},
]
Response parameters
| Name | Description |
| domain | Domain |
| ads_count | Number of ads |
| keywords_count | Number of keywords |
| traffic_sum | Traffic |
| price_sum | Budget |
| snippets | List of ads of a domain |
| snippet_num | Ad number |
| snippets_count | Number of ads |
| snippet_title | Ad title |
| snippet_description | Ad text |
| snippet_display_url | Displayed ad URL |
| url | Link |
Errors
| HTTP code | Error message |
| 400 | Row limit exceeded |
| 400 | Invalid domain |
| 400 | Invalid source |
Paid ads for domain
Description
The method allows to get an overview of paid ads for a domain.
Request format
GET https://api4.seranking.com/research/{source}/advertising/?domain=booking.com
Request parameters
| Name | Required | Description |
| domain | Yes | Domain |
| from | No | Year and month of the beginning of the period (2017-01) |
| to | No | Year and month of the end of the period (2018-12) |
| page | No | Results page (by default – 1) |
| limit | No | Number of elements (by default – 100, maximum 100) |
Result
If successful, the server returns an overview of paid ads for the specified domain.
Example
[{ keyword: "locanda vivaldi venice",ads_count: 24,competition: "0.39",cpc: "5.64",volume: "100",snippets: {2017-01: {position: "2",snippet_title: "Locanda Vivaldi, Venice - Booking.com",snippet_description: "Book at Locanda Vivaldi, Venice. No reservation costs. Great rates Amenities: Free Wifi, Non Smoking Rooms, 24 Hour Front Desk, Air Conditioning",snippet_display_url: "www.booking.com/hotel/it/locanda-vivaldi.en.html?a",snippet_count: "1",snippet_num: 125,url: "http://www.booking.com/hotel/it/locanda-vivaldi.en.html?aid=311088"}]
Response parameters
| Name | Description |
| keyword | Keyword |
| ads_count | Number of ads in total |
| competition | Competition |
| cpc | CPC |
| volume | Volume |
| snippets | List of ads of a domain |
| snippets_count | Number of ads of a domain |
| snippet_title | Ad title |
| snippet_description | Ad text |
| snippet_display_url | Displayed ad URL |
| url | Link |
Errors
| HTTP code | Error message |
| 400 | Row limit exceeded |
| 400 | Invalid keyword |
| 400 | Invalid source |
Competitors
Description
The method allows to get a list of competitor domains (maximum 500).
Request format
GET https://api4.seranking.com/research/{source}/competitors?domain=booking.com&type=adv
Request parameters
| Name | Required | Description |
| domain | Yes | Domain |
| type | No | organic – organic traffic data (default)adv – paid traffic data |
| big_players | No | 0 – hide major players (by default)1 – show major players |
| stats | No | 0 – only the list of domains and the number of common keywords (by default)1 – extra parameters |
Result
If successful, the server returns a list of competitor domains.
Example
[ { "domain": "tripadvisor.com", "common_keywords": 1076}]
..stats =1
[{ "domain": "tripadvisor.com", "common_keywords": 1076, "total_keywords": 2084, "traffic_sum": 291, "price_sum": 40.12 }]
Response parameters
| Name | Description |
| domain | Competitor domain |
| common_keywords | Keywords used both by the analyzed site and its competitors |
| total_keywords | The total number of keywords for which competitors rank for on Google’s top 100 |
| traffic_sum | Estimated traffic volume for a site with existing keywords. It’s calculated by the formula of the expected CTR (click-through rate), volume and current positions |
| price_sum | Estimated monthly cost of selected ads based on the number of keywords, their cost and traffic |
Errors
| HTTP code | Error message |
| 400 | Invalid domain |
| 400 | Invalid source |
Domain comparison
Description
The method allows to get a list of keywords for two domains.
Request format
GET https://api4.seranking.com/research/{source}/competitors/compare?domain=booking.com&compare=google.com&type=advRequest parameters
| Name | Required | Description |
| domain | Yes | Domain |
| compare | Yes | Competitor domain |
| type | No | organic – organic traffic data (default)adv – paid traffic data |
| page | No | Results page (by default – 1) |
| limit | No | Number of elements (by default – 100, max. 1000) |
| cols | No | List of return values (comma-separated) |
| diff | No | 0 – common keywords for domain and compare domains (by default)1 – keywords for compare domain that are missing for domain |
Result
If successful, the server returns a list of keywords for two domains.
Example
[
{
"keyword": "haworth hotel holland mi",
"volume": 10,
"cpc": "3.01",
"competition": "0.38",
"kei": 1.064,
"total_sites": 94,
"position": 4,
"url": "https://www.booking.com/hotel/us/haworth-inn-center.html",
"price": 2.44,
"traffic": 0.81,
"compare_position": 5,
"compare_url": "https://www.hotels.com/ho576868/haworth/",
"compare_price": 1.84,
"compare_traffic": 0.61
}
]Response parameters
| Name | Description |
| keyword | Analyzed keyword |
| kei | KEI (Keyword Effectiveness Index) |
| competition | Competition |
| cpc | CPC (Cost per Click) |
| volume | Monthly number of Google searches that occur for the specified keyword |
| total_sites | Total number of sites for the query |
| position | Position |
| url | URL of the page that is ranked on Google for the specified keyword |
| price | Cost |
| traffic | Traffic |
| compare_position | Position of the compared domain |
| compare_url | Page URL of the compared domain |
| compare_price | Traffic cost of the compared domain |
| compare_traffic | Traffic of the compared domain |
Errors
| HTTP code | Error message |
| 400 | Invalid domain |
| 400 | Invalid source |