serpstatr (version 0.3.0)

sst_rt_competitors: Get the data on competitors in search results

Description

This method method returns the competing in top20 search results domains that rank for at least two keywords that are added the project.

Usage

sst_rt_competitors(
  api_token,
  project_id,
  region_id,
  date_from = Sys.Date() - 8,
  date_to = Sys.Date() - 1,
  domains = NULL,
  sort = "sum_traffic",
  sort_range = "top1",
  order = "desc",
  page = 1,
  size = 100,
  return_method = "list"
)

Value

Returns traffic and keywords distributions, average positions of the domains by date.

Arguments

api_token

(required) Serpstat API token from your profile.

project_id

(required) The ID of your project in Serpstat. You can find this ID in the URL of any rank tracker report. As an example, in https://serpstat.com/rank-tracker/keywords/12345/positions?get_params the ID would be 12345.

region_id

(required) The ID of a region returned by sst_rt_project_regions.

date_from

(optional) The date string in 'YYYY-MM-DD' format to specify the initial date of retrieved data. Default value is current date minus 8 days.

date_to

(optional) The date string in 'YYYY-MM-DD' format to specify the final date of retrieved data. Must not exceed date_from + 30 days. Default value is yesterday.

domains

(optional) A vector of domain names for which the data should be retrieved. By default the data is retrieved for all domains that rank for at least two keywords that are added to the project.

sort

(optional) Must be one of 'sum_traffic' (default, domain search traffic distribution), 'keywords_count' (number of keywords), 'avg_position' (average domain position), 'position_ranges' (ranges of positions), 'ads_count' (number of ads in search engine results).

sort_range

(optional) The subcategory of ranges of positions to sort by. Must be one of 'top1', 'top3', 'top5', 'top10', 'top20', 'top101' to sort by the number of keywords in specific positions range; or 'keywords_count_top', 'keywords_count_bottom' to sort by the number of keywords in search ads blocks; or 'avg_position_top', 'avg_position_bottom' to sort by the average position in search ads blocks.

order

(optional) The sorting order. Must be one of string 'desc' (default) for descending sorting or 'asc' for ascending sorting.

page

(optional) Response page number if there are many pages in response. The default value is 1.

size

(optional) Response page size. Must be one of 20, 50, 100, 200, 500.The default value is 100.

return_method

(optional) Accepted values are 'list' (default) to return data object as list or 'df' to return data object as data.frame.

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

if (FALSE) {
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
project_id <- 12345
region_id  <- sst_rt_competitors(
  api_token  = api_token,
  project_id = project_id
  )$data$regions[[1]]$id
sst_rt_competitors(
  api_token     = api_token,
  project_id    = project_id,
  region_id     = region_id,
  date_from     = '2020-12-01',
  date_to       = '2020-12-30',
  domains       = c('serpstat.com', 'serpstatbot.com'),
  sort          = 'sum_traffic',
  sort_range    = 'top1',
  order         = 'desc',
  page          = 1,
  size          = 20,
  return_method = 'list'
)
}