serpstatr: Serpstat API wrapper for R.

Description

The serpstatr package currently covers only main search analytics API functions. All the names of the functions start with sst_ to reduce the name conflict with other packages.

Details

All the required arguments are checked by the API endpoint. So you would not get an error in R but the response would contain error object.

Search analytics functions

The names of these functions start with sst_sa_

• sst_sa_database_info

• sst_sa_stats

• sst_sa_domains_info

• sst_sa_domain_keywords

• sst_sa_keywords_info

• sst_sa_keywords

• sst_sa_keyword_top

Helper functions

• sst_lists_to_df

Author(s)

Maintainer: Alex Danilin alexnikdanilin@gmail.com

See Also

Useful links:

• https://serpstat.com/api/

Website audit summary

Description

Returns the basic stats for the finished audit returns, including number of checked pages, issues by priority, domain optimization score.

Usage

sst_au_get_summary(api_token, report_id = NULL)

Arguments

Value

Returns the basic metrics for audited website.

API docs

Check all the values for request and response fields here.

API credits consumption

0.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_au_get_summary(
  api_token = api_key,
  report_id = report_id
  )$data

## End(Not run)

Start a website audit

Description

Starts a project website audit with the current audit settings. Uses default audit settings if no settings were changed.

Usage

sst_au_start(api_token, project_id = NULL)

Arguments

Value

Returns the ID of the audit report.

API docs

Check all the values for request and response fields here.

API credits consumption

1 audit credit for each checked page.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_au_start(
  api_token  = api_token,
  project_id = 12345
  )$data$reportId

## End(Not run)

Backlinks summary

Description

Returns the overview of the backlinks profile for the domain.

Usage

sst_bl_domain_summary(
  api_token,
  domain,
  search_type = "domain",
  return_method = "list"
)

Arguments

Value

Returns aggregated backlinks data for the domain.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per request.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_bl_domain_summary(
  api_token     = api_token,
  domain        = 'serpstat.com',
  search_type   = 'domain',
  return_method = 'list'
)$data

## End(Not run)

Referring domains

Description

Returns the list of referring domains with main backlinks metrics for each domain.

Usage

sst_bl_referring_domains(
  api_token,
  domain,
  search_type = "domain",
  page = 1,
  size = 100,
  sort = "domain_rank",
  order = "desc",
  filter = NULL,
  return_method = "list"
)

Arguments

Value

Returns aggregated backlinks data for each referring domain.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per each domain in response.

Sorting

You can sort the response using sort argument. The sorting order is defined using order argument.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_bl_referring_domains(
  api_token        = api_token,
  domain           = 'serpstat.com',
  page             = 1,
  size             = 100,
  sort             = 'domain_rank',
  order            = 'desc',
  filter           = NULL,
  return_method    = 'list'
)$data

## End(Not run)

Make a request to Serpstat API endpoint

Description

Make a request to Serpstat API endpoint

Usage

sst_call_api_method(api_token, api_method, api_params = NULL)

Arguments

Value

The list with a response data.

Examples

api_params <- list(
  query = 'serpstat.com',
  page  = 1,
  size  = 5
  )
tryCatch({
  serpstatr:::sst_call_api_method(
    api_token  = Sys.getenv('SERPSTAT_API_TOKEN'),
    api_method = 'SerpstatLimitsProcedure.getStats',
    api_params = api_params
    )
})

Convert list of lists to data.frame

Description

API response might contain nested lists with different number of elements. This function fills missing elements and combine lists to a data.frame.

Usage

sst_lists_to_df(lists, fill = NA)

Arguments

Value

A data.frame with all missing values filed with specified value.

Examples

sst_lists_to_df(
  lists = list(
    first_list  = list(a = 1, b = 2),
    second_list = list(a = 2, c = 3)
  ),
  fill  = 'empty'
)

Create a new project

Description

Creates a new project in Serpstat.

Usage

sst_pm_create_project(api_token, domain, name, groups = NULL)

Arguments

Value

Returns the project ID for the created project.

API docs

Check all the values for request and response fields here.

API credits consumption

1 project credit.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_pm_create_project(
  api_token = api_token,
  domain    = 'serpstat.com',
  name      = 'Serpstat'
  )$data$project_id

## End(Not run)

Delete the existing project

Description

Deletes the existing project in Serpstat by project ID.

Usage

sst_pm_delete_project(api_token, project_id = NULL)

Arguments

Value

Returns the state of the deletion operation.

API docs

Check all the values for request and response fields here.

API credits consumption

returns 1 project credit.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_pm_delete_project(
  api_token  = api_token,
  project_id = 12345
  )

## End(Not run)

List existing projects

Description

Gets a list of existing projects available for the users with their basic information.

Usage

sst_pm_list_projects(api_token, page = 1, size = 100, return_method = "list")

Arguments

Value

Returns basic information on all the projects.

API docs

Check all the values for request and response fields here.

API credits consumption

0.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_pm_list_projects(
  api_token  = api_token,
  page       = 2,
  size       = 10
  )

## End(Not run)

Preprocess the API response

Description

Every API call returns a JSON object. This object is transformed to a list. Depending on return_method parameter the data element of this list will be a list or data.frame.

Usage

sst_return_check(response_content, return_method)

Arguments

Value

response_content with a data object as list or data.frame.

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"
)

Arguments

Value

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

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

## Not run: 
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'
)

## End(Not run)

Get ranking history for the domain or URL in selected search region

Description

This method method returns the rankings for specified domain is selected search region.

Usage

sst_rt_positions_history(
  api_token,
  project_id,
  region_id,
  date_from = Sys.Date() - 8,
  date_to = Sys.Date() - 1,
  keywords = NULL,
  url = NULL,
  sort = "keyword",
  order = "desc",
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns positions of selected domain in search engine results in selected region with corresponding URLs for these positions.

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
project_id <- 12345
region_id  <- sst_rt_project_regions(
  api_token  = api_token,
  project_id = project_id
  )$data$regions[[1]]$id
sst_rt_positions_history(
  api_token     = api_token,
  project_id    = project_id,
  region_id     = region_id,
  date_from     = '2020-12-01',
  date_to       = '2020-12-30',
  keywords      = c('seo', 'ppc', 'serpstat'),
  url           = 'serpstat.com',
  sort          = 'keyword',
  order         = 'desc',
  page          = 1,
  size          = 100,
  return_method = 'list'
)

## End(Not run)

Get all regions for the project

Description

In Serpstat you are able to track ranking of your website in multiple regions. This method returns all the regions in your Serpstat project. You will need the results of this method to get rankings in selected region.

Usage

sst_rt_project_regions(api_token, project_id, return_method = "list")

Arguments

Value

Returns the regions of the project with their ID, state (active or not) and other region attributes.

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
project_id <- 12345
sst_rt_project_regions(api_token = api_token, project_id = project_id)

## End(Not run)

Get search results history in search region by keywords

Description

This method returns top 100 search results in Google.

Usage

sst_rt_serp_history(
  api_token,
  project_id,
  region_id,
  date_from = Sys.Date() - 8,
  date_to = Sys.Date() - 1,
  keywords = NULL,
  sort = "keyword",
  order = "desc",
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns the search engine results for specific dates and region including positions and URLs.

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
project_id <- 12345
region_id  <- sst_rt_project_regions(
  api_token  = api_token,
  project_id = project_id
  )$data$regions[[1]]$id
sst_rt_serp_history(
  api_token     = api_token,
  project_id    = project_id,
  region_id     = region_id,
  date_from     = '2020-12-01',
  date_to       = '2020-12-30',
  keywords      = c('seo', 'ppc', 'serpstat'),
  sort          = 'keyword',
  order         = 'desc',
  page          = 1,
  size          = 100,
  return_method = 'list'
)

## End(Not run)

List all Serpstat databases

Description

In every request to get data from search analytics API you must set se parameter to specify from what country do you want to get the data. This method returns all acceptable values for se parameter with corresponding country names.

Usage

sst_sa_database_info(api_token, return_method = "list")

Arguments

Value

Returns country name, se parameter value and local search engine domain name for each country.

API docs

Check all the values for request and response fields here.

API credits consumption

0

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_database_info(api_token)$data

## End(Not run)

Domain history

Description

Returns historical metrics for the domain with about two weeks between measurements.

Usage

sst_sa_domain_history(
  api_token,
  domain,
  se,
  sort = NULL,
  filters = NULL,
  page = 1,
  size = 100,
  during_all_time = TRUE,
  return_method = "list"
)

Arguments

Value

Returns a number of metrics for each date for the domain.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per date in the response.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Filtering

To filter the results you can use filters argument. It must be a list of named elements. The name of the element must match one of the filtering parameters. See API docs for more details. For example, filters = list(queries_from = 0, queries_to = 10) would narrow the results to include only the keywords that have a search volume between 0 and 10.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_domain_history(
  api_token     = api_token,
  domain        = 'serpstat.com',
  se            = 'g_us',
  sort          = list(date = 'desc'),
  filters       = list(traff_from = 20000),
  page          = 2,
  size          = 10,
  return_method = 'df'
)$data

## End(Not run)

Domain organic keywords

Description

Returns up to 60 000 organic keywords from selected region for the domain with a number of metrics for each keyword.

Usage

sst_sa_domain_keywords(
  api_token,
  domain,
  se,
  url = NULL,
  keywords = NULL,
  minusKeywords = NULL,
  sort = NULL,
  filters = NULL,
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns a number of metrics for each keyword.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per keyword in response.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Filtering

To filter the results you can use filters argument. It must be a list of named elements. The name of the element must match one of the filtering parameters. See API docs for more details. For example, filters = list(queries_from = 0, queries_to = 10) would narrow the results to include only the keywords that have a search volume between 0 and 10.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_domain_keywords(
  api_token     = api_token,
  domain        = 'serpstat.com',
  se            = 'g_us',
  sort          = list(keyword_length = 'desc'),
  url           = 'https://serpstat.com/',
  keywords      = list('google'),
  minusKeywords = list('download'),
  filters       = list(queries_from = 0,
                       queries_to   = 10),
  page          = 2,
  size          = 10,
  return_method = 'df'
)$data

## End(Not run)

Domain competitors in organic search

Description

Returns organic competitors for the domain with their key metrics.

Usage

sst_sa_domain_organic_competitors(
  api_token,
  domain,
  se,
  sort = NULL,
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns a number of metrics for each organic competitor.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per returned page.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Filtering

To filter the results you can use filters argument. It must be a list of named elements. The name of the element must match one of the filtering parameters. See API docs for more details. For example, filters = list(queries_from = 0, queries_to = 10) would narrow the results to include only the keywords that have a search volume between 0 and 10.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_domain_organic_competitors(
  api_token     = api_token,
  domain        = 'serpstat.com',
  se            = 'g_us',
  sort          = list(relevance = 'desc'),
  page          = 2,
  size          = 20,
  return_method = 'df'
)$data

## End(Not run)

Domain top pages

Description

Returns the number of domain pages with the biggest potential traffic, number of keywords, and Facebook shares.

Usage

sst_sa_domain_top_pages(
  api_token,
  domain,
  se,
  sort = NULL,
  filters = NULL,
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns domain top pages with their metrics.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per returned page.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Filtering

To filter the results you can use filters argument. It must be a list of named elements. The name of the element must match one of the filtering parameters. See API docs for more details. For example, filters = list(queries_from = 0, queries_to = 10) would narrow the results to include only the keywords that have a search volume between 0 and 10.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_domain_top_pages(
  api_token     = api_token,
  domain        = 'serpstat.com',
  se            = 'g_us',
  sort          = list(organic_keywords = 'desc'),
  filters       = list(url_contain = 'blog'),
  page          = 2,
  size          = 50,
  return_method = 'df'
)$data

## End(Not run)

Domains summary

Description

Returns the number of keywords for each domain in SEO and PPC, online visibility and other metrics.

Usage

sst_sa_domains_info(
  api_token,
  domains,
  se,
  sort = NULL,
  return_method = "list"
)

Arguments

Value

Returns aggregated stats for each domain.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per domain in request.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_domains_info(
  api_token     = api_token,
  domains       = c('amazon.com', 'ebay.com'),
  se            = 'g_us',
  return_method = 'df'
)$data

## End(Not run)

Top for a keyword

Description

Returns a list of results (URLs) from search engine results page (SERP) including organic results, paid results and different types of SERP features.

Usage

sst_sa_keyword_top(api_token, keyword, se, top_size = 100)

Arguments

Value

Returns a list with the data about search engine results page for the keyword.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per URL in response.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_keyword_top(
  api_token = api_token,
  keyword   = 'serpstat',
  se        = 'g_us',
  top_size  = 10
)

## End(Not run)

Phrase match keywords

Description

A full-text search to find all the keywords that match the queried term with a number of metrics for each keyword like search volume, CPC and competition level.

Usage

sst_sa_keywords(
  api_token,
  keyword,
  se,
  minusKeywords = NULL,
  sort = NULL,
  filters = NULL,
  page = 1,
  size = 100,
  return_method = "list"
)

Arguments

Value

Returns a number of metrics for each keyword.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per keyword in response.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Filtering

To filter the results you can use filters argument. It must be a list of named elements. The name of the element must match one of the filtering parameters. See API docs for more details. For example, filters = list(queries_from = 0, queries_to = 10) would narrow the results to include only the keywords that have a search volume between 0 and 10.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_keywords(
  api_token     = api_token,
  keyword       = 'serpstat',
  se            = 'g_us',
  minusKeywords = c('free'),
  sort          = list(keyword_length = 'asc'),
  page          = 2,
  size          = 10,
  return_method = 'df'
)$data

## End(Not run)

Keywords summary

Description

Returns a number of metrics for each keyword like search volume, CPC and competition level.

Usage

sst_sa_keywords_info(
  api_token,
  keywords,
  se,
  sort = NULL,
  return_method = "list"
)

Arguments

Value

Returns a number of metrics for each keyword.

API docs

Check all the values for request and response fields here.

API credits consumption

1 per keyword in request.

Sorting

You can sort the response using sort argument. It must be a list with a single named element. The name of the element must match one of parameters in response. The value of the element must be asc for ascending order and desc for descending order. For example, sort = list(ads = 'desc') would sort the response by ads parameter in descending order.

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_keywords_info(
  api_token     = api_token,
  keywords      = c('seo', 'ppc', 'serpstat'),
  se            = 'g_us',
  sort          = list(cost = 'asc'),
  return_method = 'df'
)$data

## End(Not run)

Get the number of API rows left

Description

With most API request you spend some amount of API rows. The total amount of API rows available for you is based on your plan. Use this method to control the amount of API rows left.

Usage

sst_sa_stats(api_token)

Arguments

Value

Returns a number of API rows left. Also returns some additional information about user and Serpstat plugin limits.

API credits consumption

0

Examples

## Not run: 
api_token <- Sys.getenv('SERPSTAT_API_TOKEN')
sst_sa_stats(api_token)$summary_info$left_lines

## End(Not run)