SEMSTORM API v3

SEMSTORM API v3

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

We encourage using SEMSTORM PHP SDK library which delivers simple and ready-to-use functionality for SEMSTORM API.
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.

Introduction

Get access token

The access token is the unique string that authorizes your API access.

To get your access token you need to log in and go to "Services token" section where you can generate a new token.

Do not share your access token with any third party individuals. Access token allows to obtain any information regarding your campaigns and gives access to all API functionality. It should be handled with caution like passwords.

If you suspect someone else is using your token you should revoke it and get a new one. You can regenerate your token in Services token section. Attention! After you regenerate your token it will immediately stop working, so you will have to replace it in your application right away.

API results structure

Each API call gives a response. Response structure while using SEMSTORM PHP DSK API will be a PHP array. While using cURL with .json prefix, you will receive encoded JSON string.

Every response has easy to interpret structure. A response may contain following keys:

"params": an associative array/object containing all request parameters.

"result": an associative array/object with result set (considering no errors occurred).

"error": ": an associative array/object that exists only if a request was unsuccessful; it contains information about causes of failure.

"_credits": an integer showing how much each request costs; can be zero.

"_credits_left": an integer showing how many credits are left; can be zero.

API restrictions

API has multiple limitations to maximize efficiency and data credibility.

Requests per second. Each account (access token) has a limited number of requests. When access token generates more than allowed number of requests per second, error code 503 and message "You are requesting too fast." is returned. (see below).

API throttle prevention. Retrieving big sets of data, and/or setting long date range highly increase a chance to get "Prevent throttling" error. In that case, you can try to divide request to few less and retrieve it piece by piece or wait before repeating your request. It returns error code 503 and mesasge "Throttle prevention." (see below).

Single request limits. Those limits are set to prevent large and complicated calculations as well as big data transferring, hence making it difficult for others to use API simultaneously. Mostly it applies to request like creating multiple objects, retrieve sets of data. To prevent those errors reduce the amount of data in one request. It returns error code 400 and message "Request limit.".

Error message

If an error occurs response will be sent with proper HTTP code and carry error information in its body.

If you encounter any error which is not listed as standard API error let us know.

Possible error codes:

HTTP code Message
400 (400) Wrong input. Invalid or missing input data. Mostly additional info about requirements is displayed alongside error message.
403 (403) Access denied. Action you want to perform is impossible due to protection level.
404 (404) No entry for given id. ID do not exists or is unavailable.
404 (404) Undefined action. Callback was called but cannot determine which action to take.
404 (404) Not found: Cound not find the controller. You are calling wrong endpoint or wrong method - eg. using GET request in "monitoring-campaign/get-access" endpoint.
409 (409) Other transaction in progress. Access to data temporary denied. Something else is in critical section for this part of data. Try again later.
500 (500) Program exception catched. System exception occured. Exception message is display alongside error message.
503 (503) Service temporarily unavailable. You are requesting too fast. Your request was refused beacuse you reached your requests limit, wait few seconds and try again.
503 (503) Service unavailable. Connection was disturbed. It can be system/connection temporary failure, or throttle prevention (see below)
520 (520) Something went wrong. Cant determine what, but something brokes on the way, if you see this type of error let us know.

Other info

Changes in API v3 are listed here.

Resolving problems with cURL. If you get message "Unsupported request content type..." then it means you are using invalid content type. cURL examples below use JSON input/output format and we strongly encourage using this solution, if you want to communicate by JSON as well add -H "Content-Type: application/json" in your cURL request (see here).

Variables types: Services backend is implemented in PHP, which does not require explicit type definition (see here), that is why in examples below all variables described as "int" can also be passed as a string, and also returned types can differ from described below depend on content-type, and client environment.
For example, remember that even thou every input and output described below using "array" nomenclature- when returning data in JSON you will get objects in place of assoc arrays.
If your software requires explicit variable type definition remember to cast results into proper variables.

Filters

Filters in API allows the same advanced data mining as via system panel.

Filters structure

Basically creating a filter is just defining a proper array. This array constain up to 4 properties, which are:

field (string): name of a field which a filter applies to

value (mixed): filter value, it can be eg. regex string to filter by, an array of numbers to set range between them etc.

operand (string): operand determine how to interpret filter condition, eg. "equal" will require results to have an exact value, while "less" will search everything smaller than given value. The default value is "equal" which is a proper value for all fields except cpc.

domain (string): domain which a filter applies to, it is used only in some types of filters

Depends on the filtered field some values can be optional, some not used, and some required.

Filter array

Field value Operand value Requires Domain Value type Value description
keyword equal, contains, synonym, regexp no string Filters by keyword name (title).
For operand equal, it finds only keyword which is exact as given value.
For operand contains, it finds all keywords which have given value in its name.
For operand synonym, it finds all keywords which have given value or its synonyms in its name. This option is for explorer only.
For operand regexp, it uses a regular expression to filter keyword name.
group equal no integer This filter is for monitoring only. Filter keywords from this particular group. A value must be proper group id.
cp equal, between, less, more no mixed (see description) Filters by keyword competition. Competition is integer in range from 0 to 10.
For operand equal it finds only keywords which have competition equals to given value. Value must be int.
For operand between it finds all keywords which have competition between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have competition less then given value. Value must be int.
For operand more it finds only keywords which have competition more then given value. Value must be int.
volume equal, between, less, more no mixed (see description) Filters by keyword search volume. Search volume is a positive integer.
For operand equal it finds only keywords which have search volume equals to given value. Value must be int.
For operand between it finds all keywords which have search volume between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have search volume less then given value. Value must be int.
For operand more it finds only keywords which have search volume more then given value. Value must be int.
trends equal no mixed (see description) Filters by keyword trending month. Trending months are months where keyword is significantly popular (compared by search volume).
Value can be one month id, or array of up to 4 months ids. Ids are presented below.
Month Id
January 1
February 2
March 3
April 4
May 5
June 6
July 7
August 8
September 9
October 10
November 11
December 12
cpc between, less, more no mixed (see description) Filters by keyword CPC. CPC is a positive integer.
For operand between it finds all keywords which have CPC between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have CPC less then given value. Value must be int.
For operand more it finds only keywords which have CPC more then given value. Value must be int.
position_change equal, between, less, more yes mixed (see description) Filters by domain position change. Position change is integer in range from -50 to 50. For example if on some keyword domain was in position 5 on SERP and fall to 8, its position change value will be -3, while on the other hand if position was 35 and rose up to 22 it will be 13.
For operand equal it finds only keywords which have position change equals to given value. Value must be int.
For operand between it finds all keywords which have position change between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have position change less then given value. Value must be int.
For operand more it finds only keywords which have position change more then given value. Value must be int.
subdomain equal, contains yes string Filters by domain subdomains. As all keywords points into specific url in domain, you can filter by subdomains in those urls.
For operand equal it finds only keywords which points to exact subdomain as given value.
For operand contains it finds only keywords which points to subdomain containing given value in name.
traffic equal, between, less, more yes mixed (see description) Filters by domain traffic. Traffic is a positive integer. Remember that traffic is estimated value and it should be used as comparision between keywords/domains inside system, not as exact real value.
For operand equal it finds only keywords which traffic for domain equals to given value. Value must be int.
For operand between it finds all keywords which have traffic for domain between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have traffic for domain less then given value. Value must be int.
For operand more it finds only keywords which have traffic for domain more then given value. Value must be int.
position equal, between, less, more yes mixed (see description) Filters by domain position. Position is integer in range from 0 to 50.
For operand equal it finds only keywords which have position equals to given value. Value must be int.
For operand between it finds all keywords which have position between two given values. Value must be array with two itnegers, first one must be lower limit and second upper limit.
For operand less it finds only keywords which have position less then given value. Value must be int.
For operand more it finds only keywords which have position more then given value. Value must be int.
url equal yes string Filters by domain url. As all keywords points into specific url in domain, which you can filter by.
For operand equal it finds only keywords which points to exact url as given value.

Throttle prevention

Remember that using filters can overload request. Especially multiple filters at once, and filters which requires complex computing (such as url "contains").
That is why when working with filters you can often encounter 503 "Throttle prevention" error, which require you to delay your request for a while.
For complex requests it can (rarely) take up to few minutes.

Regular expressions

For keyword field there is possible operand "regexp" which allows you to create regular expression to filter by keywords names.
This funcionality is designed for advanced users - more information about regular expression you can find here.
In this filter you can use:

  • brackets [a-z]{4,5} (shoe|sock)
  • dot .
  • asterix *
  • question mark ?
In this filter you cannot use:
  • delimiters, and flags /regex/u
  • new line and other white characters except space \n
  • plus sign +

Examples:

  • [a-z]{4-5} .* keyword with at least two words and first word 4-5 letter long
  • .* .* .* keyword with at least 2 spaces (3 words)
  • (shoe|sock).* keyword starting with shoe or sock
  • .*shoe.* keyword containing shoe

Examples

Many examples about how to build filters can be found in /examples/filters/FiltersExplain.php

Practical usage of filters can be found in /examples/filters/MonitoringUsage.php and /examples/filters/ExplorerUsage.php

Sorting

Use sorting to retrieve desired set of results. Where possible sorting is passed along with other params as array keyed "sorting". It requires two fields inside: "field" and "sort".

Sorting array
parameter type description
field string Field to sort by.
sort string Direction of sorting. Value "desc" stands for descending order, and "asc" for ascending order. Possible values are "desc", "asc".

Possible sorting options

Sort order is always "asc" or "desc" as written above.

Sorting fields depends on endpoint, in every place where sorting is possible fields list will be provided.

Sorting with dynamic indexes

Some fields with names will have suffix ":X" which means they requires index in field name. Index points to specific criteria on sorting, when one column may occurs multiple times. Eg. "position:2" in Explorer keywords means that results will be sorted by position of third passed domain.