Below documentation describes Monitoring functionallity in SEMSTORM API v3. It is divided into sections describing each part of Monitoring.
We encourage to use SEMSTORM PHP SDK library which delivers simple and ready-to-use functionallity for SEMSTORM API.
Take into consideration that SEMSTORM PHP SDK library is under Apache License 2.0, it is distributed without any warranties, and support is not included. If you encounter any problems please leave a ticket to let us know.
Tags are obsolete. Tags functionallity is disabled, their endpoint is closed and any usage of them is impossible.
Advanced filters. Some of requests have optional "advanced filters" parameter. Those filters allows user to create advanced and precise reports/queries. Those filters are sent in request as simple array, but which must be build properly. For details about usage of filters see this documentation. Currently requests using advanced filters are: Campaign get data.
Every functionallity contains examples in curl and PHP. In PHP case, it is assumed that user have properly installed SEMSTORM PHP SDK library which can be fount here. For curl -as any other than prepared sdk library- remember that SEMSTORM API guarantee compatibility only for JSON formatted data.
include_once __DIR__ . '/autoload.php';
use SemstormApi\Semstorm;
use SemstormApi\Monitoring\MonitoringCampaign;
Semstorm::init( __ACCESS_TOKEN__ );
$monitoringCampaign = new MonitoringCampaign();
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| domain | POST | string | yes | - | Campaign domain value. |
| title | POST | string | no | Campaign title. Default: domain value. | |
| type | POST | string | yes | - | Campaign type. Possible values: "seo", "ads". |
| data | POST | array | no | Campaign additional data. Default: empty array. |
| Data array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| company_map_title | string | no | Company map title property. Default: no parameter. | ||
| domains* | array | no | Website addresses (strings) if multiple exists. Default: no parameter. * - this value is available only for "ads" type. | ||
| trademarks* | array | no | Trademarks list (strings). Default: no parameter. * - this value is available only for "ads" type. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | integer | Id of newly created campaign. |
Description:
Creates new campaign.
Error:
Request: "domain", or "type" field is empty.
Limit: creating campaign require at least one free campaign limit.
examples/Monitoring/CampaignCreate.php
curl -X POST -d '{ "domain": "example.com" }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign.json?services_token=__ACCESS_TOKEN__
{ "id": __ID__ }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/{_CAMPAIGN_ID_} [GET]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| _CAMPAIGN_ID_ | url | integer | yes | - | Campaign id to retrieve. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | integer | Campaign id. |
| result["title"] | string | Campaign title. |
| result["domain"] | string | Campaign domain. |
| result["status"] | string | Campaign status. |
| result["access"] | string | User access type. |
| result["type"] | string | Campaign type. |
| result["created_time"] | string | Campaign create timestamp. |
| result["changed_time"] | string | Campaign last modification timestamp. |
| result["groups"] | array | Campaign groups ids. |
Description:
Get data about campaign.
Error:
Request: campaign with given id not exist for current user.
examples/Monitoring/CampaignRetrieve.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_CAMPAIGN_ID_.json?services_token=__ACCESS_TOKEN__
{"id": _CAMPAIGN_ID_, "domain":"example.com", "status":"active", "access_type":"owner", "created_time":"1460375898", "changed_time":"1460375898", "groups":[__GROUP_ID__, __GROUP_ID__ (...) ]}
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/{_CAMPAIGN_ID_} [PUT]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| _CAMPAIGN_ID_ | url | integer | yes | - | Campaign id to update. |
| domain | POST | string | no | Campaign domain value. Default: current domain. | |
| title | POST | string | no | Campaign title. Default: current title. | |
| data | POST | array | no | Campaign additional data. Default: current array. |
| Data array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| company_map_title | string | no | Company map title property. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | bool | Value is true on success. |
Description:
Change data of campaign.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: campaign with given id not exist for current user.
examples/Monitoring/CampaignUpdate.php
curl -X PUT -d '{ "domain": "example.com" }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_ID_.json?services_token=__ACCESS_TOKEN__
[ true ]
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with campaign ids. For backwards compatibility works also as integer for one campaign. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_] | mixed | True if change status for given campaign was success, or error message if failed. |
Description:
Change status of campaign to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: campaign with given id not exist for current user.
Limit: activating campaign require at least one free campaign limit, and that much keywords as it have.
examples/Monitoring/CampaignStart.php
curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start.json?services_token=__ACCESS_TOKEN__
{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/stop [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with campaign ids. For backwards compatibility works also as integer for one campaign. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_] | mixed | True if change status for given campaign was success, or error message if failed. |
Description:
Change status of campaign to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: campaign with given id not exist for current user.
examples/Monitoring/CampaignStop.php
curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/stop.json?services_token=__ACCESS_TOKEN__
{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/delete [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with campaign ids. For backwards compatibility works also as integer for one campaign. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_] | mixed | True if change status for given campaign was success, or error message if failed. |
Description:
Change status of campaign to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Campaign with given id not exist for current user.
examples/Monitoring/CampaignDelete.php
curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/delete.json?services_token=__ACCESS_TOKEN__
{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/restore [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with campaign ids. For backwards compatibility works also as integer for one campaign. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_] | mixed | True if change status for given campaign was success, or error message if failed. |
Description:
Change status of campaign from delete to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Campaign with given id not exist for current user.
examples/Monitoring/CampaignRestore.php
curl -X POST -d '{ "id": [ __CAMPAIGN_ID_1__, __CAMPAIGN_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/restore.json?services_token=__ACCESS_TOKEN__
{ __CAMPAIGN_ID_1__: 1, __CAMPAIGN_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-list [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| type | POST | array | no | seo |
Array with types of campaigns to retrieve. Proper values are "seo", "ads". Works also for string as one type. |
| pager | POST | array | no | Pager settings. See below for structure details. | |
| filters | POST | array | no | Filters. See below for structure details. |
| Pager array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| items_per_page | integer | no | 25 |
Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000. | |
| page | integer | no | 0 |
Page number to retrieve, starting from 0. |
| Fitlers array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| engine | mixed | no | All |
Engine id (int) or "All" (string) for all engines. | |
| status | array | no | Array with statuses (strings), possible values: "active", "stop", "delete". Default: all statuses. | ||
| bookmark | mixed | no | All |
0 - non bookmarked campaigns. 1 - bookmarked campaigns. 'All' - both. | |
| title | string | no | Title or part of title to filter. Default: empty string. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["count"] | int | Number of all campaigns (for better pagination). |
| result["campaigns"] | array | Array with campaigns. |
| result["campaigns"][]["id"] | int | Campaign id. |
| result["campaigns"][]["access"] | string | User access type. |
| result["campaigns"][]["status"] | string | Campaign status, possible values: "active", "stop", "delete". |
| result["campaigns"][]["domain"] | string | Campaign domain. |
| result["campaigns"][]["type"] | string | Campaign type, possible values: "seo", "ads", "trash". |
Description:
Get campaigns set selected by pager.
Error:
Throttling: Possible throttle prevention.
examples/Monitoring/CampaignList.php
curl -X POST -d '{ "pager": { "items_per_page":10, "page":1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-list.json?services_token=__ACCESS_TOKEN__
{ "campaigns"[ (...) ], "count":27 }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | integer | yes | - | Campaign id to retrieve. |
| domains | POST | mixed | no | Array of domains or string with one domain. Default: campaign domain. | |
| type | POST | string | no | organic |
Type of data to retrieve, valid values are "organic", "paid" and "maps". |
| datemin | POST | string | no | Report start date in format YYYYmmdd eg. 20160901. Default: day 2 weeks ago. | |
| datemax | POST | string | no | Report end date in format YYYYmmdd eg. 20170530. Default: yesterday. | |
| gap | POST | string | no | daily |
Date gap to aggregate data by, possible values are "daily", "weekly", "monthly". |
| filters | POST | array | no | Advanced filters, for more details see "Advanced filters" section here. Default: empty array. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with query results divided by groups ids. |
| result[_GROUP_ID_] | array | Array with group data divided by domains. |
| result[_GROUP_ID_][_DOMAIN_] | array | Array with domain data divided by keywords ids. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_] | array | Keyword data and info. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"] | array | Array with keyword info. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["title"] | string | Keyword title. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["volume"] | integer | Keyword volume. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["keyword"]["cpc"] | string | Keyword CPC. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"] | array | Array with keyword data divided by date (date format depends on date gap). |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_] | array | Array with keyword data divided by engine. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_] | array | Array with keyword data divided by device. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_] | array | Array with keyword data divided by location. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_] | array | Array with keyword data. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_]["position"] | number | Domain position on given keyword with parameters and date specified in result keys. If date gap is set to daily it will be integer, otherwise it is average. |
| result[_GROUP_ID_][_DOMAIN_][_KEYWORD_ID_]["data"][_DATE_][_ENGINE_][_DEVICE_][_LOCATION_]["url"] | string | Domain destination url on given keyword with parameters and date specified in result keys. |
Description:
Get details about campaign keywords. It is data from "Daily rank tracking" tab in Monitoring/Keywords page in system.
In filters array you (optionally) specify your filters. It should be exact filters which are set in url when browsing monitoring page. Try this in system to see proper syntax.
For PHP library users: filters in input can be set using SemstormFilters class, which makes it a lot simplier. For details about SemstormFilters class see examples/Explorer/FiltersExplain.php and examples/Explorer/FiltersUsage.php files.
Error:
Throttling: Possible throttle prevention.
examples/Monitoring/CampaignData.php
curl -X POST -d '{"id": _ID_, "datemin": "20160901", "datemax": "20170530", "gap": "monthly", "domains": ["example.com", "example2.pl"] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-access [POST]
| Input | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with campaigns access informations, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_]["access"] | string | Your access level, possible values are: "owner", "manager", "readonly". |
| result[_CAMPAIGN_ID_]["owner"] | string | Owner e-mail address. |
Endpoint: /monitoring/monitoring-campaign/get-access [POST]
Description:
Returns information about campaigns you have access to, with type of access and infrmation about owner (e-mail address).
Existing permissions are:
"owner" - this account can modify everything in campaign, add and remove roles. Its reserved for account which created campaign, and is persistent.
"manager" - this account can do everything as "owner" but this role can be removed.
"readonly" - account with that permission can only see campaign and its statistics, and cannot do any changes.
Error:
none.
examples/Monitoring/CampaignGetAccess.php
curl -X POST http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-access.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/set-access [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| __CAMPAIGN_ID__ | POST | array | yes | - | Array with access modifications for given campaign. |
| Campaign array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| set | array | no | Array with accesses to set for given campaign (add or modify existing). Default: empty array. | ||
| remove | array | no | Array with accesses to remove for given campaign. Default: empty array. |
| Set array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| string | yes | - | User e-mail for whom access will be set. | ||
| permission | string | yes | - | Permission level to set, possible values are: "readonly", "manager". |
| Remove array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| string | yes | - | User e-mail for whom access will be removed. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with access modifications results, keyed by campaigns ids. |
| result[_CAMPAIGN_ID_]["set"][_USER_MAIL_] | bool | True if change was successful, false otherwise. |
| result[_CAMPAIGN_ID_]["remove"][_USER_MAIL_] | bool | True if removal was successful, false otherwise. |
Description:
Set access to campaigns, you need to have proper access level to modify permissions in campaigns.
This api endpoint is limited to one request per 10 seconds.
By this api call you can alter maximum 3 accounts at once. That means "set" array shouldn't have more than 3 records. There is no limit in removing access.
Proper permissions to give and take are "readonly" and "manager". One more permission named "owner" is reserved for account which created campaign and cannot be modified.
If you will try to grant permission by entering e-mail on which there is no registered account in SEMSTORM system, then the invitation e-mail to craete account will be send.
Error:
Request: too fast requesting, if any campaign id invalid (user might not have permissions) or if access updating failed. Access updating will fail if: you try to modify permissions in campaign you have "readonly" access, you try to remove or change permission level of the owner of campaign, one or more e-mail address is invalid.
Throttling: this request is specially limited to one per 10 seconds.
examples/Monitoring/CampaignSetAccess.php
curl -X POST -d '{ "__CAMPAIGN_ID__": { "set": [ (...) ], "remove": [ (...) ] }}' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/set-access.json?services_token=__ACCESS_TOKEN__
{ "result": { "__CAMPAIGN_ID__": { "set": [ (...) ], "remove": [ (...) ] } } }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| campaign_id | POST | integer | yes | - | Campaign id in which create group. |
| title | POST | string | yes | - | Group title. |
| engine | POST | integer | yes | - | Engine id - it must be set in pair with proper country id (see here). |
| country | POST | integer | yes | - | Country id - it must be set in pair with proper engine id (see here). |
| location | POST | string | no | Location name. If not specified then location will be saved as empty and not used. | |
| devices | POST | array | yes | - | Array with at least one device name (strings). |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages. |
| result["id"] | string | Id of newly created group. |
Description:
Create new group in specified campaign.
Error:
Request: any of required fields missing, campaign id invalid (user might not have permissions), engine-country invalid combination, devices array invalid.
examples/Monitoring/GroupCreate.php
curl -X POST -d '{ "campaign_id":__ID__, "title":"New group", "engine": 2, "country": 168, "location": "warszawa", "devices": ["mobile"] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group.json?services_token=__ACCESS_TOKEN__
{ "id": "12345" }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/{_GROUP_ID_} [GET]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| _GROUP_ID_ | url | integer | yes | - | Group id to retrieve. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | integer | Group id. |
| result["title"] | string | Group title. |
| result["status"] | string | Group status. |
| result["created_time"] | string | Group create timestamp. |
| result["changed_time"] | string | Group last modification timestamp. |
| result["keywords"] | array | Group keywords ids. |
| result["engine"] | integer | Engine id. |
| result["country"] | integer | Country id. |
| result["location"] | string | Location name. |
| result["devices"] | array | Array of devices (strings). |
Description:
Get data about group.
Error:
Request: group id invalid (user might not have permissions).
examples/Monitoring/GroupRetrieve.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-group/_GROUP_ID_.json?services_token=__ACCESS_TOKEN__
{"id": _ID_, "title": "Group title", "status": "active", "created_time": "1415794727", "changed_time": "1415794727", "keywords": [ __KEYWORD_ID__, __KEYWORD_ID__, __KEYWORD_ID__, (...) ], "engine": "2", "country": "168","location": "warszawa","devices": ["desktop"]}
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/{_GROUP_ID_} [PUT]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| _GROUP_ID_ | url | integer | yes | - | Group id to update. |
| title | POST | string | no | Group title. Default: current title. | |
| engine | POST | integer | no | Country id - it must be set in pair with proper engine id (see here). Default: current engine. | |
| country | POST | integer | no | Country id - it must be set in pair with proper engine id (see here). Default: current country. | |
| location | POST | string | no | Location name. When not specified location will be saved as empty and not used. Default: current location. | |
| devices | POST | array | no | Array with at least one device name (strings). Default: current devices. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | bool | Value is true on success. |
Description:
Change data of group
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it..
To set "location" parameter to empty pass there empty string. This will be interpreted as no location specified.
Error:
Request: group with given id not exist for current user, engine-country invalid combination, devices array invalid.
Limit: updating group can change keywords usage. Eg. when changing from one device to both all keywords in group will be counted twice.
examples/Monitoring/GroupUpdate.php
curl -X PUT -d '{"title": "new name", "engine": 2, "country": 168, "location": "łódź", "devices": ["mobile", "desktop"]}' http://api.semstorm.com/api-v3/monitoring/monitoring-group/_ID_.json?services_token=__ACCESS_TOKEN__
[ true ]
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/start [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with group ids. For backwards compatibility works also as integer for one group. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by groups ids. |
| result[_GROUP_ID_] | mixed | True if change status for given group was success, or error message if failed. |
Description:
Change status of group to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: group with given id not exist for current user.
Limit: activating group require that much keywords as it have.
examples/Monitoring/GroupStart.php
curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/start.json?services_token=__ACCESS_TOKEN__
{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/stop [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with group ids. For backwards compatibility works also as integer for one group. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by groups ids. |
| result[_GROUP_ID_] | mixed | True if change status for given group was success, or error message if failed. |
Description:
Change status of group to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: group with given id not exist for current user.
examples/Monitoring/GroupStop.php
curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/stop.json?services_token=__ACCESS_TOKEN__
{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/delete [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with group ids. For backwards compatibility works also as integer for one group. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by groups ids. |
| result[_GROUP_ID_] | mixed | True if change status for given group was success, or error message if failed. |
Description:
Change status of group to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: group with given id not exist for current user.
examples/Monitoring/GroupDelete.php
curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/delete.json?services_token=__ACCESS_TOKEN__
{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/restore [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with group ids. For backwards compatibility works also as integer for one group. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by groups ids. |
| result[_GROUP_ID_] | mixed | True if change status for given group was success, or error message if failed. |
Description:
Change status of group to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: group with given id not exist for current user.
examples/Monitoring/GroupRestore.php
curl -X POST -d '{ "id": [ __GROUP_ID_1__, __GROUP_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/restore.json?services_token=__ACCESS_TOKEN__
{ __GROUP_ID_1__: 1, __GROUP_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/get-list [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| campaign_id | POST | integer | yes | - | Campaign id from which retrieve groups. |
| pager | POST | array | no | Pager settings. See below for structure details. |
| Pager array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| items_per_page | integer | no | 25 |
Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000. | |
| page | integer | no | 0 |
Page number to retrieve, starting from 0. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["count"] | int | Number of all groups (for better pagination). |
| result["groups"] | array | Array with groups. |
| result["groups"][]["id"] | integer | Group id. |
| result["groups"][]["title"] | string | Group title. |
| result["groups"][]["keywords_count"] | integer | Group keywords count (important its not number of keywords in group but evaluated 'cost' counted in limit, so if you have two devices set in group keywords_count will be doubled beacuse each keyword will be scanned twice). |
| result["groups"][]["status"] | string | Group status. |
| result["groups"][]["engine"] | integer | Engine id. |
| result["groups"][]["country"] | integer | Country id. |
| result["groups"][]["location"] | string | Array with groups. |
| result["groups"][]["devices"] | array | Array of devices (strings). |
Description:
Gets list of campaign groups.
Error:
Request: campaign with given id not exist for current user.
examples/Monitoring/GroupList.php
curl -X POST -d '{ "campaign_id": 7189, "pager": { "items_per_page": 10, "page": 1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/get-list.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]
Description:
Simpliest way to retrieve keywords data is by using "group"-"entity" filter with group id. See example for details.
Error:
Throttling: Possible throttle prevention.
examples/Monitoring/GroupData.php
curl -X POST -d '{ "id": __CAMPAIGN_ID_1__, "filters": {"type": "include", "field": "group_nid_mv", "op": "entity", "value": [ [__GROUP_ID_1__: __GROUP_ID_1__] ]}, (...) }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-data.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/create-multiple [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| campaign_id | POST | string | yes | - | Campaign id in which create groups. |
| groups | POST | array | yes | - | Array with groups data to create. It can be assoc array, then keys will be preserved in results for easiest results reading. |
| Groups array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| <group-distinguisher> | array | yes | - | Array with single group data to create. |
| Group array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| title | string | yes | - | Group title. | |
| engine | integer | yes | - | Engine id - it must be set in pair with proper country id (see here). | |
| country | integer | yes | - | Country id - it must be set in pair with proper engine id (see here). | |
| location | string | no | Location name. If not specified then location will be saved as empty and not used. | ||
| devices | array | yes | - | Array with at least one device name (strings). |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | array | Array with information about creating each group, indexed same way as input. |
| result["id"][<group-distinguisher>] | mixed | True if creation of group was success, or error message if failed. |
Description:
Create multiple groups in campaign. Its behavior is very similar to creating one group, except it takes array with groups params to create multiple groups.
"Groups" variable can be assoc array, instead of normal array - in that case returning information about each group creation will preserve keys so you can easily determine which output is for which group.
Error:
Request: campaign with given id not exist for current user, any groups data invalid.
examples/Monitoring/GroupCreateMultiple.php
curl -X POST -d '{ "campaign_id": 1234, "groups": { "new group 1": (...), "new group 2": (...) } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/create-multiple.json?services_token=__ACCESS_TOKEN__
{ "id":{ "new group 1": 123456, "new group 2": 123457 } }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-group/update-multiple [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| groups | POST | array | yes | - | Array with groups data, keyed by groups ids. |
| Groups array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| _GROUP_ID_ | array | yes | - | Array with single group data to update. |
| Group array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| title | string | no | Group title. | ||
| engine | integer | no | Country id - it must be set in pair with proper engine id (see here). Default: current engine. | ||
| country | integer | no | Country id - it must be set in pair with proper engine id (see here). Default: current country. | ||
| location | string | no | Location name. When not specified location will be saved as empty and not used. Default: current location. | ||
| devices | array | no | Array with at least one device name (strings). Default: current devices. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | array | Array with information about creating each group, keyed by groups ids. |
| result["id"][_GROUP_ID_] | mixed | True if updating of group was success, or error message if failed. |
Description:
Update multiple groups in campaign. Its behavior is very similar to updating one group, except it takes array with groups params to update multiple groups.
Error:
Request: group with given id not exist for current user, any group data invalid.
examples/Monitoring/GroupUpdateMultiple.php
curl -X POST -d '{ "groups": { "__GROUP_ID_1__": {(...)}, "__GROUP_ID_2__": {(...)} } }' http://api.semstorm.com/api-v3/monitoring/monitoring-group/update-multiple.json?services_token=__ACCESS_TOKEN__
{ "id":{ __GROUP_ID_1__: true, __GROUP_ID_2__: true } }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| group_id | POST | integer | yes | - | Group id in which create keywords. |
| keywords | POST | array | yes | - | Array of keywords to add (strings). It can be assoc array, then keys will be preserved in results for easiest results reading. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | array | Array with information about creating each keyword, indexed same way as input. |
| result["id"][] | mixed | True if creation of keyword was success, or error message if failed. |
Description:
Create new keywords in group.
Error:
Request: group with given id not exist for current user.
examples/Monitoring/KeywordCreate.php
curl -X POST -d '{ "group_id": _ID_, "keywords": [ "keyword 1", "keyword 2", "keyword 3", (...)] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword.json?services_token=__ACCESS_TOKEN__
{ "id": [ "12345", "12346", "12347", (...) ] }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/{_KEYWORD_ID_} [GET]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| _KEYWORD_ID_ | url | integer | yes | - | Keyword id to retrieve. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["id"] | string | Keyword id. |
| result["title"] | string | Keyword title. |
| result["status"] | string | Keyword status. |
| result["group_id"] | string | Group id in which keyword is. |
Description:
Get data about keyword.
Error:
Request: keyword with given id not exist for current user.
examples/Monitoring/KeywordCreate.php
curlhttp://api.semstorm.com/api-v3/monitoring/monitoring-keyword/_KEYWORD_ID_.json?services_token=__ACCESS_TOKEN__
{ "id": "_ID_", "title": "keyword 1", "status": "active", "group_id": "_GROUP_ID_" }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/start [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with keyword ids. For backwards compatibility works also as integer for one keyword. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | mixed | True if change status for given keyword was success, or error message if failed. |
Description:
Change status of keywords to active.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: keyword with given id not exist for current user.
Limit: activating keyword require at least one free keyword limit.
examples/Monitoring/KeywordCreate.php
curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/start.json?services_token=__ACCESS_TOKEN__
{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/stop [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with keyword ids. For backwards compatibility works also as integer for one keyword. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | mixed | True if change status for given keyword was success, or error message if failed. |
Description:
Change status of keywords to stop.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: keyword with given id not exist for current user.
examples/Monitoring/KeywordStop.php
curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/stop.json?services_token=__ACCESS_TOKEN__
{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/delete [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with keyword ids. For backwards compatibility works also as integer for one keyword. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | mixed | True if change status for given keyword was success, or error message if failed. |
Description:
Change status of keywords to delete.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: keyword with given id not exist for current user.
examples/Monitoring/KeywordDelete.php
curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/delete.json?services_token=__ACCESS_TOKEN__
{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/restore [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | mixed | yes | - | Array with keyword ids. For backwards compatibility works also as integer for one keyword. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | mixed | True if change status for given keyword was success, or error message if failed. |
Description:
Change status of keywords from deleted to stoped.
This call is in critical section, which means it locks access to entity it operates on for the execution time. When locked no other critical actions may take place. Also this call may fail if anything else locked current entity before it.
Error:
Request: keyword with given id not exist for current user.
examples/Monitoring/KeywordRestore.php
curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, __KEYWORD_ID_2__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/restore.json?services_token=__ACCESS_TOKEN__
{ __KEYWORD_ID_1__: 1, __KEYWORD_ID_2__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/change-group [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| group_id | POST | integer | yes | - | Destined group id to where keywords will be moved. |
| id | POST | array | yes | - | Array with keywords ids. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | mixed | True if moving of keyword was success, or error message if failed. |
Description:
Takes keywords and move them to specified group. Each keyword can be from different group/campaign as long as you have access to edit those.
Error:
Request: group with given id not exist for current user. Any of keyword id is invalid. Limits exceeded - this is possible eg. if you move keywords from group with one device to other with two.
examples/Monitoring/KeywordChangeGroup.php
curl -X POST -d '{ "group_id": __GROUP_ID__, "id": [ __KEYWORD_ID__, __KEYWORD_ID__, (...) ] }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/change-group.json?services_token=__ACCESS_TOKEN__
{ __KEYWORD_ID__: 1, __KEYWORD_ID__: 1, (...) }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-list [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| campaign_id | POST | integer | yes | - | Array with group ids. For backwards compatibility works also as integer for one group. |
| pager | POST | array | no | Pager settings. See below for structure details. | |
| filters | POST | array | no | Filters. See below for structure details. |
| Pager array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| items_per_page | integer | no | 25 |
Page size (how many campaigns are in one page). Possible values are: 1, 5, 10, 25, 50, 100, 500, 1000. | |
| page | integer | no | 0 |
Page number to retrieve, starting from 0. |
| Fitlers array | |||||
|---|---|---|---|---|---|
| parameter | type | required | default | description | |
| keyword | string | no | Keyword title or part of keyword title to filter. Default: empty string. | ||
| group_name | string | no | Group name or part of group name to filter. Default: empty string. | ||
| status | array | no | Array with statuses (strings), possible values: "active", "stop"". Default: empty array. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by groups ids. |
| result["count"] | integer | Number of all keywords (for better pagination). |
| result["keywords"] | array | Array with keywords. |
| result["keywords"][]["id"] | integer | Keyword id. |
| result["keywords"][]["title"] | string | Keyword title. |
| result["keywords"][]["status"] | string | Keyword status, possible values: "active", "stop", "delete". |
| result["keywords"][]["group_id"] | integer | Group id in which keyword is. |
| result["keywords"][]["group_status"] | string | Group status in which keyword is. |
Description:
Gets list of campaign keywords.
Important! If you put "delete" into status filter, you will see only deleted keywords, and other statuses will be ignored.
Use "active" and "stop" separately from "delete" filter.
Error:
Request: campaign with given id not exist for current user.
examples/Monitoring/KeywordList.php
curl -X POST -d '{ "campaign_id": _ID_, "pager": { "items_per_page": 25, "page": 1 } }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-list.json?services_token=__ACCESS_TOKEN__
{ "count": 123, "keywords": [ (...)] }
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/get-data [POST]
Description:
Simpliest way to retrieve keywords data is by using "keyword"-"equals" filter with keyword full name. See example for details.
Error:
Throttling: Possible throttle prevention.
examples/Monitoring/KeywordData.php
curl -X POST -d '{ "id": __CAMPAIGN_ID_1__, "filters": {"type": "include", "field": "keyword", "op": "equal", "value": [ "kredyt" ]}, (...) }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-data.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-details [POST]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| id | POST | array | yes | - | Array with keyword ids. For backwards compatibility works also as integer for one keyword. |
| type | POST | string | no | heatmap |
Type of data to retrieve, valid values are "heatmap", "competitors" and "top50". Type "heatmap" and "competitors" returns same data, just refers to other visual representation in system panel. |
| datemin | POST | string | no | Report start date in format YYYYmmdd eg. 20160901. Default: day 2 weeks ago. | |
| datemax | POST | string | no | Report end date in format YYYYmmdd eg. 20170530. Default: yesterday. | |
| gap | POST | string | no | daily |
Date gap to aggregate data by, possible values are "daily", "weekly", "monthly". |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result | array | Array with results and/or error messages, keyed by keywords ids. |
| result[_KEYWORD_ID_] | array | Array with keyword data, keyed by device name. |
| result[_KEYWORD_ID_][_DEVICE_] | array | Array with device data, keyed by domain. |
| result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_] | array | Array with domain data, keyed by date. |
| result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_] | array | Domain data on given keyword, device and date specified in result keys. |
| result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["position"] | number | Domain position. If date gap is set to daily it will be integer, otherwise it is average value. |
| result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["position_change"]* | number | Domain position change. * - this value is available only for type "top50". |
| result[_KEYWORD_ID_][_DEVICE_][_DOMAIN_][_DATE_]["url"]* | string | Domain url. * - this value is available only for type "top50". |
Description:
Retrieve details about keywords. Each of keyword (idetified by keyword id) can have few results, depending on group device count it is in.
Output differs depends on chosen "type".
Error:
Throttling: Possible throttle prevention.
examples/Monitoring/KeywordList.php
curl -X POST -d '{ "id": [ __KEYWORD_ID_1__, (...) ], "params": { "type": "competitors", (...) } }' http://api.semstorm.com/api-v3/monitoring/monitoring-keyword/get-details.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint: http://api.semstorm.com/api-v3/monitoring/monitoring-tables/{_TABLE_NAME_} [GET]
| Parameters PHP CURL | |||||
|---|---|---|---|---|---|
| method | type | required | default | description | |
| url | string | yes | - | Name of table to retrieve. |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result[_TABLE_NAME_] | array | Content of given table. |
Description:
This endpoint is used to retrieve information about current API params.
Currently there are two tables possible to retrieve: "engines" which contains full set of engine-country ids collection, and "devices" which is lsit of possible devices names.
Error:
Wrong table name.
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-tables/engines [GET]
| Input | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["engines"][]["name"] | string | Engine name. |
| result["engines"][]["id"] | integer | Engine id. |
| result["engines"][]["countries"] | array | Countries list for given engine. |
| result["engines"][]["countries"][]["name"] | string | Country name. |
| result["engines"][]["countries"][]["id"] | integer | Country id. |
Description:
Return table containing all possible engines and countries variations.
Error:
None.
examples/Monitoring/TablesEngines.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-tables/engines.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Endpoint:
http://api.semstorm.com/api-v3/monitoring/monitoring-tables/devices [GET]
| Input | |||||
|---|---|---|---|---|---|
| parameter | method | type | required | default | description |
| Output RESULT | ||
|---|---|---|
| method | type | description |
| result["devices"] | array | Array with proper devices names (strings). |
Description:
Return table containing proper devices names.
Error:
None.
PHP example code:
examples/Monitoring/TablesDevices.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-tables/devices.json?services_token=__ACCESS_TOKEN__
{"devices": [ "mobile", "desktop" ]}
Passing invalid token (or not passing at all) in request will result in authorization error.
examples/Monitoring/ErrorAuthorization.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/_ID_.json?services_token=this-is-wrong-access-token
[ "Unauthorised access." ]
When error occurs you can check "message" in "error" variable returned from server.
examples/Monitoring/ErrorSimple.php
curl http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/123456.json?services_token=__ACCESS_TOKEN__
{"error": { "message": "(404) No entry for given id." }
In some requests errors returns more information. For example bulk operations returns array with information which operations succeded and which failed.
examples/Monitoring/ErrorBulk.php
curl -X POST -d '{ "id": [_CAMPAIGN_ID_1_, _CAMPAIGN_ID_2_, (...)] }' http://api.semstorm.com/api-v3/monitoring/monitoring-campaign/start.json?services_token=__ACCESS_TOKEN__
(see php example for example result)
Error with code 503 in most cases will concern throttle prevention. If error message will contain "Throttle prevention. Data may be incomplete(...)" that means system was overloaded and refused to sustain connection.
This is temporary problem, you can retry your request after few secons - just remember that very large request will require more time to wait.
If problem sustains it propably means you are requesting too big set of data at once. Try split it into few smaller requests.
There is no example of this error, as it happens occasionaly for big set of data.
There is no example of this error, as it happens occasionaly for big set of data.
{ "params": {(...)}, "error": { "message": "(503) Service unavailable. Throttle prevention. Data may be incomplete. Try again later.", "result": {(...)} } }


Mxit - The First Mobile Messenger
I started my career as developer in 2012 at Mxit, which was one of the first mobile messaging apps in the world - it started gaining traction here around 2004/2005. The head of mobile development there, a brilliant programmer named Jaco, suggested I join the J2ME team, their flagship client - a wonderful and exciting challenge for me coming straight out of university.
Mxit, spanning over 10 years of existence, reached more than 100 million people worldwide.
They operated way before Whatsapp became a household name but unfortunately due to various reasons Mxit didn't make it and officially switched off their servers somewhere in 2015.
Here's a good article about the rise and fall of Mxit. This article also includes information about Mxit version 7, a project in which I was closely involved in its development and design (specifically the J2ME, Blackberry and Android apps), together with a great team of coders and led by two people who I see as visionaries in their fields, Phil Barrett, expert in all things UX-related, and the product owner at that time, Andy Volk, who is now Google's Head of Ecosystem in Sub-Saharan Africa. The iOS version of Mxit 7 was also spectacular, led by Peter Matthaei, later founder of the app Namola, which made national news recently.
My time there was invaluable for me: regardless of the development experience, it taught me how a successful medium-to-large software business operates on all levels, and I progressed my way from J2ME to Blackberry and ultimately to my love, Android.
At one stage I was team leader of 3 different development teams which also gave me experience in dealing with different developers and their styles, as well as managing tasks.
Click the animation if you want to view the full picture.


Scottish Fairy and Folk Tales, by George Douglas, [1901], at sacred-texts.com
THERE came a woman of peace (a fairy) the way of the house of a man in the island of Pabaidh, and
she had the hunger of motherhood on her. He gave her food, and that went well with her. She stayed that night. When she went away she said to him, "I am making a desire that none of the people of this island may go in childbed after this." None of these people, and none others that would make their dwelling in the island, ever departed in childbed from that time.
121:2 Campbell, Popular Tales of the West Highlands.