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:

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

Other info

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 operandequal, it finds only keyword which is exact as given value.
For operandcontains, it finds all keywords which have given value in its name.
For operandsynonym, it finds all keywords which have given value or its synonyms in its name. This option is for explorer only.
For operandregexp, 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 operandequal it finds only keywords which have competition equals to given value. Value must be int.
For operandbetween 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 operandless it finds only keywords which have competition less then given value. Value must be int.
For operandmore 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 operandequal it finds only keywords which have search volume equals to given value. Value must be int.
For operandbetween 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 operandless it finds only keywords which have search volume less then given value. Value must be int.
For operandmore 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 operandbetween 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 operandless it finds only keywords which have CPC less then given value. Value must be int.
For operandmore 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 operandequal it finds only keywords which have position change equals to given value. Value must be int.
For operandbetween 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 operandless it finds only keywords which have position change less then given value. Value must be int.
For operandmore 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 operandequal it finds only keywords which points to exact subdomain as given value.
For operandcontains 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 operandequal it finds only keywords which traffic for domain equals to given value. Value must be int.
For operandbetween 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 operandless it finds only keywords which have traffic for domain less then given value. Value must be int.
For operandmore 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 operandequal it finds only keywords which have position equals to given value. Value must be int.
For operandbetween 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 operandless it finds only keywords which have position less then given value. Value must be int.
For operandmore 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 operandequal 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

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.