Keywords API | SEMSTORM

Keywords API

This document contains basic information how to use SEMSTORM Keywords 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

Retrieve report

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

Parameters   PHP  CURL 
parameter method type required default  description
keywords POST array yes - Array of strings. Those are base keywords input.
engines POST array yes - Array of strings. Those are engines to search in. See keywords-tables/engines endpoint to know how to retrieve engines with their proper country and language.
type POST string yes - Report type. Report type define what modifiers will be used in generating phrases. See keywords-tables/types endpoint to know how to retrieve possible types.
modifiers POST array no* Array of strings. Those are modifiers which will be concatenate with keywords to build phrases. * - This array is required for report type "custom".
country POST string no pl Country code which should be used in search. Remember that most engines supports only particular countries so you must set one which is possible for all engines selected. See keywords-tables/countries endpoint to know how to retrieve possible countries.
language POST string no pl Language code which should be used in search. Remember that most engines supports only particular languages so you must set one which is possible for all engines selected. See keywords-tables/languages endpoint to know how to retrieve possible languages.
location POST string no Location coordinates in "lat|lon" format, eg. "50.0861158|14.4137924" for Prague, Czech near Charles bridge see it on google maps. Coordinates does not have to be placed inside country you passed in "country" param, but then results might be vary.
Output   RESULT 
method type description
results["gathering_failures"] integer Number of requests errors while gathering results. Number of all requests vary between settings. Whenever this number is not zero best practice is to wait few minutes and try again. It is possible to receive constant number of errors in certain configurations.
results["keywords"] array Array with keywords.
results["keywords"][_KEYWORD_]["value"] string Keyword, same as key _KEYWORD_.
results["keywords"][_KEYWORD_]["engines"] array Array of string. This is engine list in which this keyword was found.
results["keywords"][_KEYWORD_]["base"] string Base keyword. This is one of keywords from input parameters.
results["keywords"][_KEYWORD_]["search"] string Search phrase. Created from "base" and "modifier".
results["keywords"][_KEYWORD_]["modifier"] string Modifier, this is addition to base keyword. Used modifiers depending on chosen type or passed modifiers array.

Description:
Retrieve report data.

Errors:
Request: "keywords" is not array.
Request: "keywords" is empty.
Request: "engines" is not array.
Request: "engines" is empty.
Request: "type" is not string.
Request: "type" is empty.
Request: "country" is not string.
Request: "language" is not string.
Request: "location" is not string.
Exception: Invalid collation of "country" and "engine".
Exception: Invalid collation of "language" and "engine".

PHP example code:
Curl:

-X POST -d '{ "keywords": [ "pizza", (...) ], "engines": [ "google" ], "type": "simple" }' https://api.semstorm.com/api-v3/keywords/keywords/get-data.json?services_token=__ACCESS_TOKEN__

Output:

"gathering_failures": 0, "keywords": { "pizza nocą": { "value": "pizza nocą", "engines": [ "google" ], "base": "pizza", "search": "pizza", "modifier": "" }, (...) }

Keywords tables

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/{_TABLE_NAME_} [GET]

Parameters   PHP  CURL 
method type required default  description
GET string yes - Name of table to retrieve.
Output   RESULT 
method type description
results[_TABLE_NAME_] array Content of given table.

Description:
This endpoint is used to retrieve information about current API params.

Errors:
Request: Wrong table name.

Table of types

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/types [GET]

Parameters   PHP  CURL 
parameter method type required default  description
Output   RESULT 
method type description
results["types"] array Array of strings which are proper type value.

Description:
Return table of possible report types.

Errors:
None.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/keywords/keywords-tables/types.json?services_token=__ACCESS_TOKEN__

Output:

(no example results)

Table of countries

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/countries [GET]

Parameters   PHP  CURL 
parameter method type required default  description
Output   RESULT 
method type description
results["countries"] array Array of countries.
results["countries"][_COUNTRY_CODE_] string Country name.

Description:
Return table of possible countries. Remember to use _COUNTRY_CODE_ not country name when passing parameter via API.

Errors:
None.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/keywords/keywords-tables/countries.json?services_token=__ACCESS_TOKEN__

Output:

(no example results)

Table of languages

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/languages [GET]

Parameters   PHP  CURL 
parameter method type required default  description
Output   RESULT 
method type description
results["languages"] array Array of languages.
results["languages"][_LANGUAGE_CODE_] string Language name.

Description:
Return table of possible languages. Remember to use _LANGUAGE_CODE_ not language name when passing parameter via API.

Errors:
None.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/keywords/keywords-tables/languages.json?services_token=__ACCESS_TOKEN__

Output:

(no example results)

Table of currencies

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/currencies [GET]

Parameters   PHP  CURL 
parameter method type required default  description
Output   RESULT 
method type description
results["currencies"] array Array of currencies.
results["currencies"][_CURRENCY_CODE_] string Currency name.

Description:
Return table of possible currencies. Remember to use _CURRENCY_CODE_ not currency name when passing parameter via API.
Info: for now there is no currency parameter usage anywhere in API. This endpoint is for future developing.

Errors:
None.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/keywords/keywords-tables/currencies.json?services_token=__ACCESS_TOKEN__

Output:

(no example results)

Table of engines

Endpoint:
https://api.semstorm.com/api-v3/keywords/keywords-tables/engines [GET]

Parameters   PHP  CURL 
parameter method type required default  description
Output   RESULT 
method type description
results["engines"] array Array of languages.
results["engines"][_ENGINE_CODE_] array Array of engine params.
results["engines"][_ENGINE_CODE_]["language"] array Array of languages possible for this engine.
results["engines"][_ENGINE_CODE_]["country"] array Array of countries possible for this engine.
results["engines"][_ENGINE_CODE_]["category"] string Engine category, informational only.

Description:
Return table of possible engines. Remember to use _ENGINE_CODE_ when passing parameter via API. When passing multiple engines to retrieve report endpoint remember that chosen language and country must bo valid for all engines you pass.

Errors:
None.

PHP example code:
Curl:

curl https://api.semstorm.com/api-v3/keywords/keywords-tables/languages.json?services_token=__ACCESS_TOKEN__

Output:

(no example results)