SEMSTORM - Explorer

Explorer API

This document contains basic information how to use SEMSTORM Explorer API v3.

SEMSTORM PHP SDK library is under Apache License 2.0, This means that library is distributed without any warranties. What is more, support is not included. If you encounter any problems, please leave us a ticket.

Documentation

Keywords

Get keywords data

Endpoint:
https://api.semstorm.com/api-v3/explorer/explorer-keywords/get-data [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domains POST array yes - Up to 5 domains to retrieve competitors. Array of strings, keys are ignored. Domains can be encoded in IDN format.
logic_conjunction POST string no or Used when more than one domain is provided, defines if . Possible values: "or", "and".
result_type POST string no organic Result type, whether retrieve organic or paid data. Possible values: "organic", "paid".
keywords_type POST string no In organic keywords by default all keywords are returned. Setting this param will change keywords type, similar to page tabs in system. Possible values: "all", "new", "up", "down", "lost".
sorting POST array no Sorting settings. For more help about sorting see here.
pager POST array no Pager settings.
version POST integer no SEMSTORM database version. Default to newest version.
Sorting array
parameter type required default  description
field string no volume Field to sort by. Its raw field name, so its important to define it properly. Proper values are: "volume", "keyword", "url:X", "position:X", "position_c:X", "traffic:X", "traffic_c:X", "competitors", "cpc". Dynamic index here points to domain, counted from 0. For more help about sorting see here.
sort string no desc Direction of sorting. Value "desc" stands for descending order, and "asc" for ascending order. Possible values are "desc", "asc".
Pager array
parameter type required default  description
items_per_page int no 25 Numbers of items per page. Possible values are 10, 25, 50.
page int no 0 Page number to retrieve counted from 0.
Output   RESULT 
method type description
result array Array with keywords data.
result[]["keyword"] string Keyword.
result[]["position"] array Array of integers - position of domains on given keyword.
result[]["position_c"] array Array of integers - position change of domains on given keyword.
result[]["url"] array Array of strings - urls on which keyword points in SERP.
result[]["traffic"] array Array of integers - traffic index of domains on given keyword.
result[]["traffic_c"] array Array of integers - traffic index change of domains on given keyword.
result[]["volume"] int Keyword volume.
result[]["competitors"] int Keyword competitors.
result[]["cpc"] float Keyword CPC.
result[]["trends"] string Keyword trends as list separated by comma.

Description:
Retrieve keywords data for selected domain or domains.

Error:
Request: "domains" array is empty.

PHP example code:
Curl:

curl -X POST -d '{ "domains": ["example.com"] }' https://api.semstorm.com/api-v3/explorer/explorer-keywords/get-data.json?services_token=__ACCESS_TOKEN__

Output:

[ {"keyword": "example", "position": {"example.com": 3}, "position_c": {"example.com": -1}, (...)}, (...) ]

Get keywords basic stats

Endpoint:
https://api.semstorm.com/api-v3/explorer/explorer-keywords/basic-stats [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domains POST array yes - Up to 5 domains to retrieve stats. Array of strings, keys are ignored. Domains can be encoded in IDN format.
logic_conjunction POST string no or Used when more than one domain is provided, defines whether include all keywords from all domains or only those which are common for all provided domains. Possible values: "or", "and".
filters POST array no Filters. For more help about filters see here.
version POST integer no SEMSTORM database version. Default to newest version.
Output   RESULT 
method type description
result array Array with stats, keyed by domain.
result[_DOMAIN_]["keywords"] string Keywords count.
result[_DOMAIN_]["keywords_top"] string Top 10 keywords count.
result[_DOMAIN_]["traffic"] string Traffic value.
result[_DOMAIN_]["traffic_potential"] string Potential traffic value.
result[_DOMAIN_]["search_volume"] string Search volume.
result[_DOMAIN_]["search_volume_top"] string Top 10 search volume.

Description:
Retrieve summary data for domain or domains.

Error:
Request: "domains" array is empty.

PHP example code:
Curl:

curl -X POST -d '{ "domains": ["example.com"] }' https://api.semstorm.com/api-v3/explorer/explorer-keywords/basic-stats.json?services_token=__ACCESS_TOKEN__

Output:

{ "example.com": { "keywords": 5, "keywords_top": 1, "traffic": 2, "traffic_potential": 181, "search_volume": 580, "search_volume_top": 50 }}

Get keywords position distribution

Endpoint:
https://api.semstorm.com/api-v3/explorer/explorer-keywords/position-distribution [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domains POST array yes - Up to 5 domains to retrieve data. Array of strings, keys are ignored. Domains can be encoded in IDN format.
filters POST array no Filters. For more help about filters see here.
version POST integer no SEMSTORM database version. Default to newest version.
Output   RESULT 
method type description
result array Array keyed by domain.
result[_DOMAIN_] array Array keyed by position.
result[_DOMAIN_][_POSITION_] integer Keywords count. How many keywords are visible on given position for given domain.

Description:
Retrieve number of keywords visible in each SERP position for each domain. It's same data as presented in explorer keywords page - in "Position distribution chart" on top of page.

Error:
Request: "domains" array is empty.

PHP example code:
Curl:

curl -X POST -d '{ "domains": ["example.com"] }' https://api.semstorm.com/api-v3/explorer/explorer-keywords/position-distribution.json?services_token=__ACCESS_TOKEN__

Output:

{ "example.com": { 1: 15, 2: 21, 4: 2, 5: 1 (...) }}

Competitors

Endpoint:
https://api.semstorm.com/api-v3/explorer/explorer-competitors/get-data [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domains POST array yes - Up to 5 domains to retrieve competitors. Array of strings, keys are ignored. Domains can be encoded in IDN format.
result_type POST string no organic Result type, whether retrieve organic or paid data. Possible values: "organic", "paid".
competitors_type POST string no In organic competitors by default Similar competitors are returned. Set this param to "all" to retrieve all competitors. Possible values: "all".
pager POST array no Pager settings.
version POST integer no SEMSTORM database version. Default to newest version.
Pager array
parameter type required default  description
items_per_page int no 25 Numbers of items per page possible values are 10, 25, 50.
page int no 0 Page number to retrieve counted from 0.
Output   RESULT 
method type description
result array Array with competitors.
result[]["competitor"] string Domain.
result[]["common_keywords"] int Number of keyowrds common with selected domains.
result[]["traffic"] int Domain traffic value.

Description:
Retrieve competitor for selected domain or domains.

Error:
Request: "domains" array is empty.

PHP example code:
Curl:

curl -X POST -d '{ "domains": ["example.com"] }' https://api.semstorm.com/api-v3/explorer/explorer-competitors/get-data.json?services_token=__ACCESS_TOKEN__

Output:

[ {"competitor": "example.com", "common_keywords": 123, "traffic": 123}, (...) ]

Visibility

Endpoint:
https://api.semstorm.com/api-v3/explorer/explorer-visibility/get-data [POST]

Parameters   PHP  CURL 
parameter method type required default  description
domains POST array yes - Up to 100 domains to check visibility. Array of strings, keys are ignored. Domains can be encoded in IDN format.
result_type POST string no organic Result type, whether retrieve organic or paid data. Possible values: "organic", "paid".
gap POST string no monthly Date gap. Possible values: "daily", "weekly", "monthly".
date POST array no Date range. Default: previous month.
version POST integer no SEMSTORM database version. Default to newest version. Makes difference only in "montly" gap.
Date array
parameter type required default  description
min string no * Lower bound of the time range to consider in format YYYYMMDD. * Default first day of previous month.
max string no * Upper bound of the time range to consider in format YYYYMMDD. * Default last day of previous month.
Output   RESULT 
method type description
result array Array with query results divided by domains given in parameters.
result[_DOMAIN_] array Array of domain results divided by dates (date format depends on date gap).
result[_DOMAIN_][_DATE_] array Array of domain results divided by dates.
result[_DOMAIN_][_DATE_]["visibility"] array Visibility of given domain in given date. This field is not returned for "monthly" gap setting.
result[_DOMAIN_][_DATE_]["keywords"] array Keywords count of given domain in given date.
result[_DOMAIN_][_DATE_]["keywords_top"] array Top 10 keywords count of given domain in given date.
result[_DOMAIN_][_DATE_]["traffic"] array Traffic of given domain in given date.

Description:
Retrieve visibility, traffic and keywords count for domains.

Error:
Request: "domains" array is empty.

PHP example code:
Curl:

curl -X POST -d '{ "domains": ["example.com"], "gap": "daily" }' https://api.semstorm.com/api-v3/explorer/explorer-visibility/get-data.json?services_token=__ACCESS_TOKEN__

Output:

{ "example.com": {"2017-05-11": {"visibility": 123, "keywords": 123, "keywords_top": 123, "traffic": 123}, (...) } }