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:
http://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. | |
| 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"] }' http://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:
http://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. | |
| 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"] }' http://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:
http://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. | |
| 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"] }' http://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:
http://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. | |
| 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"] }' http://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:
http://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. | |
| 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" }' http://api.semstorm.com/api-v3/explorer/explorer-domains/visibility.json?services_token=__ACCESS_TOKEN__
Output:
{ "example.com": {"2017-05-11": {"visibility": 123, "keywords": 123, "keywords_top": 123, "traffic": 123}, (...) } }