Documentation of REST API used by Wordstato.com service

Description of REST API used by the service

Short description

The API interface is used to integrate capabilities of the Wordstato.com service into our clients' personal projects. This API is intended for developers and comes with detailed documentation.

REST API of the service uses the HTTP protocol to operate and is a set of methods used to make queries and get responses for each operation. All responses arrive as JSON structures.

Authorization

The process of authorization is possible if you have a personal key (token hereinafter), which can be used to subsequently sign every request to API.

A token can be generated in the settings of your personal area in the API block.

Your token will be automatically updated if you change your user password or click "Generate new token".

Your token must be used as the value of X-Keyso-TOKEN header to perform authorized queries.

Example of a key:

X-Keyso-TOKEN: 5a2a5f0e538dd5.6691914852255446e23a9bcac46ee5255625f5d5

Main URL

All links to queries to API in this documentation include the mandatory main URL: https://api.wordstato.com/

Standard request parameters

Most reports (unless specified otherwise) support the standard request parameters:

Parameter	Type	Required	Description	Default value
current_page	integer	false	Sequential number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc – ascending, desc – descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	See details about filtering in the Data filtering section	none

Data filtering mechanism

The filtering mechanism is used together with the default request parameters

Fields which support filtration are listed in documentation of every report.

Fiesld type	Condition	Operator, format
string, integer	Strictly equal	field`=`value
string, integer	Strictly non-equal	field`!=`value
string	Like	field`LIKE`value
string	Not like	field`NOT LIKE`value
string	Starts with	field`STARTSWITH`value
string	Ends with	field`ENDSWITH`value
string, integer	Is one of	field`IN`valueA,valueB
string, integer	Is not one of	field`NOT IN`valueA,valueB
integer	Greather than	field`>`value
integer	Lesser than	field`<`value
integer	Greather or equal to	field`>=`value
integer	Lesser or equal to	field`<=`value
integer	Between	field`BETWEEN`valueA@valueB

Number of fields, which can be included in a filtration request, is not limited.

The mechanism supports AND (^) and OR (^OR) logical operators.

A filter-containing string shall be URL-encoded before sending

An example of creating an AND (^) request:

Filter out all requests that contain the word "toy" with search volume above 170,000
The filter: `wordLIKEtoy^ws>170000`
Request parameters: `filter=wordLIKEtoy%5Ews%3E170000`

An example of a request that combines AND (^) and OR (^OR):

Filter out all competitors whose domains contain "modа" or "kupi" words with similarity above 40
The filter: `nameLIKEmoda^ORnameLIKEkupi^perc>40`
Request parameters: `filter=nameLIKEmoda%5EORnameLIKEkupi%5Eperc%3E50`

Structure of a JSON response

Most reports (unless specified otherwise) contain the standard response structure:

Field	Type	Description
current_page	integer	Sequential number of a results page
per_page	integer	Number of results on one page
last_page	integer	Number of the last page
total	integer	Total number of results
data	array	Array of objects that contain a result

Response example:

            {"current_page":1,"per_page":25,"last_page":29296,"data":[{}],"total":732392}

Server response codes

HTTP Code	Description
200	Request successful
202	Request accepted from processing but not yet completed. Try again later.
401	Authorization error
429	Query limit for the current pricing plan was reached. Error details are available in the `message` field. The `Retry-After` header of a server response specified time (in seconds) for which a client is recommended to wait before trying again.
500	Internal server error. Error details are available in the `message` field

Use example

<?php
 
/*
 * Example of PHP script, with use cURL lib
 *
 */
 
$url = "https://api.wordstato.com/report/simple/context/concurents?base=gny&domain=foodband.ru&sort=cnt%7Cdesc&page=1&per_page=250";
$curl = curl_init();
$headers = array('X-Keyso-TOKEN: 5a2a5f0e538dd5.6691914852255446e23a9bcac46ee5255625f5d5');
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 15);
curl_setopt($curl, CURLOPT_TIMEOUT, 15);
$response = curl_exec($curl);
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$headerCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$responseBody = substr($response, $header_size);
curl_close($curl);

Description of REST API for simple requests

Domain Dashboard

GET `report/simple/domain_dashboard`

Request parameters:

Parameter Type Mandatory Description Default value

base

string

true

Regional database, from which samples are being taken

Possible values:

gny - Google: New York

none

domain

string

true

Domain name

none

Request example:

report/simple/domain_dashboard?base=gny&domain=dominos.com

Response structure:

Field	Type	Description
id	integer	Domain ID
name	string	Domain
adsenseid	string	Publisher identifier in Google Adsense
analytics	integer	Publisher identifier in Google Analytics
parentid	integer	Parent domain name
parentName	string	Name of Parent Domain
childsCount	integer	Number of subdomains
it1	integer	Number of keywords in Top 1
it3	integer	Number of keywords in Top 3
it5	integer	Number of keywords in Top 5
it10	integer	Number of keywords in Top 10
it50	integer	Number of keywords in Top 50
topvis	integer	By visibility
topkeys	integer	By keywords reach
pagesinindex	integer	Pages in search results
vis	integer	Estimation of a number of visits per day
adtraf	integer	Rough estimation of a number of visits score PPC
adscnt	integer	Number of ads
adkeyscnt	integer	Number of keywords in PPC
keys	array	Keywords (first 20)
concs	array	Competitors (first 20)
pages	array	Website pages (first 20)
ads	array	PPC ads (first 20)
adkeys	array	PPC website keywords (first 20)
adconcs	array	PPC competitors (first 20)
history	array	History of parameters changes

(object) keys:

Field	Type	Description
word	string	Keyword
ws	integer	Volume
pos	integer	Position in a SERP

(object) concs:

Field	Type	Description
name	string	Domain name
count	integer	Shared keywords in a domain's keywords
perc	double	% of shared keywords in a domain's keywords
vis	integer	Estimation of a number of visits per day

(object) pages:

Field	Type	Description
url	string	Page URL
it50	integer	Shared keywords in a domain's keywords

(object) ads:

Field	Type	Description
header	string	Ad's header
txt	string	Ad's text
keyscnt	integer	Number of keywords

(object) adkeys:

Field	Type	Description
word	string	Keyword
ws	integer	Volume
pos	integer	Position in a place
mincpc	double	Min CPC
maxcpc	double	Max CPC

(object) adconcs:

Field	Type	Description
name	string	Domain name
count	integer	Shared keywords in a domain's keywords
adscnt	integer	Number of PPC ads
adkeyscnt	integer	Number of keywords in PPC
vis	integer	Estimation of a number of visits per day
it50	integer	Number of keywords in Top 50	true

(array) history:

 {

            "YYYY.MM": [

            "Top 1", "Top 3", "Top 5", "Top 10", "Top 50", "Number of a website's pages", "Number of PPC ads", "Number of keywords in PPC", "Estimation of a number of visits per day"

            ],

            ...
            }

Response example:

            {"id":30998388,"name":"dominos.com","adsenseid":"","analytics":0,"parentid":0,"parentName":"","childsCount":27,"it1":4811,"it3":11036,"it5":14055,"it10":19278,"it50":41075,"topVis":147,"topKeys":6518,"pagesinindex":241,"vis":5669759,"adtraf":23567,"adcost":0,"adscnt":612,"adkeyscnt":744,"keys":[{"word":"ww dominos pizza","ws":50,"pos":1}],"concs":[{"name":"yelp.com","count":14698,"it50":10996221,"vis":929908,"perc":"0.134"}],"pages":[{"url":"/en","it50":10831}],"ads":[{"header":"Domino’s® Pizza Delivery - Domino’s® Pizza","txt":"Order Your Next Pizza Online & Track Its Delivery With The Domino's Tracker®. Pizza, Dips...","keyscnt":12}],"adkeys":[{"word":"pizza delivery 78750","ws":50,"pos":3,"mincpc":"3.580","maxcpc":"6.910"}],"adconcs":[{"name":"google.com","count":108,"adscnt":666137,"adkeyscnt":749695,"vis":35290856,"it50":481335}],"history":{"2022.09":[4811,11036,14055,19278,41075,241,612,744,5669759]}}

Keyword Summary

GET `report/simple/keyword_dashboard`

Request parameters:

Parameter Type Mandatory Description Default value

base

string

true

Regional database, from which samples are being taken

Possible values:

gny - Google: New York

none

keyword

string

true

search keyword

none

Request example:

report/simple/keyword_dashboard?keyword=ulla johnson shorts sale&base=gny

Response structure:

Field	Type	Description
id	integer	Keyword ID
word	string	Keyword
ws	integer	Volume
top	array	SEO
ads	object(key: type, value: array)	PPC Where type: `pr` - Top place `gr` - Bottom place
similars	array	Similar keywords (first 20)

(object) top:

Field	Type	Description
pos	integer	Position
domain	string	Domain name
url	string	Page url
it1, it3, it5, it10, it50	integer	Number of domain's keywords in Top 1..Top 50
pit1, pit5, pit10, pit50	integer	Number of page's keywords in Top 1..Top 50
adsenseid	string	Publisher identifier in Google Adsense
analytics	integer	Identifier in Google Analytics
pagesinindex	integer	Number of a website's pages found in search results
vis	integer	Estimation of a number of visits per day

(object) ads:

Field	Type	Description
pos	integer	Position
domain	string	Domain name
header	string	Ad's header
txt	string	Ad's text
mincpc	double	Min CPC
maxcpc	double	Max CPC

(object) similars:

Field	Type	Description
word	string	Keyword
count	integer	How similar a keyword is to its original keyword
ws	integer	Volume
docs	integer	Displays how many documents were in search results
mincpc	double	Min CPC
maxcpc	double	Max CPC

Response example:

            {"id":11924889,"word":"ulla johnson shorts sale","ws":50,"top":[{"pos":1,"domain":"lyst.com","url":"/shop/ulla-johnson-shorts","it1":19810,"it3":108837,"it5":226109,"it10":469699,"it50":1118557,"adsenseid":"","analytics":0,"pagesinindex":258446,"pit1":2,"pit5":3,"pit10":4,"pit50":6,"vis":1801944}],"ads":[[{"pos":1,"domain":"modaoperandi.com","header":"Amondi Pleated Cotton Shorts By Ulla Johnson | Moda Operandi","txt":"Discover the New Summer 2022 Collections from our Most-Wanted & Newest Designers. Shop New Season Must-Have Styles including Dresses, Outerwear, Jewelry, Shoes, & More.","mincpc":"1.290","maxcpc":"4.620"}],[{"pos":1,"domain":"bergdorfgoodman.com","header":"Ulla Johnson | Bergdorf Goodman - BergdorfGoodman.com","txt":"Discover the latest clothing, shoes and handbags from designers you love. Personal Styling.","mincpc":"1.290","maxcpc":"4.620"}]],"similars":[{"word":"ulla johnson shorts sale","count":10,"ws":50,"docs":81,"mincpc":"1.290","maxcpc":"4.620"}]}

PPC: keywords

GET `report/simple/context/keywords`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/context/keywords?base=gny&domain=dominos.com&sort=pos%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
pos	integer	Position in block	true
ws	integer	Volume	true
mincpc	double	Min CPC	true
maxcpc	double	Max CPC	true
serpf	string	SERP date
numwords	integer	Number of words in a keyword	true
sr	integer	Ad place Available places: `1` - top block `0` - bottom block	true
header	string	Ad's header	true
txt	string	Ad's text	true
adscnt	integer	Number of PPC ads	true
docs	integer	Displays how many documents were in search results	true
competition	integer	Competition	true

Response example:

            {"current_page":1,"per_page":25,"last_page":30,"data":[{"word":"24 hour pizza delivery myrtle beach","pos":4,"ws":50,"mincpc":"0.580","maxcpc":"3.660","serpf":"2022-09-24","numwords":6,"sr":1,"header":"Domino’s® Pizza Delivery - Domino's® Delivers Late Night","txt":"Order From Your Nearest Store Now. Track Your Order. Find A Location Near You.","adscnt":4,"docs":90,"aid":29949867,"competition":2}],"total":744}

PPC: keywords of an ad

GET `report/simple/context/keywords/byads`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
ads_id	integer	true	Ad identifier `Available in PPC "ads" report`	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/context/keywords/byads?base=gny&domain=dominos.com&ads_id=3926767790&sort=word|desc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
pos	integer	Position in placement	true
ws	integer	Volume	true
mincpc	double	Min CPC	true
maxcpc	double	Max CPC	true
header	string	Ad's header	true
txt	string	Ad's text	true
numwords	integer	Number of words in a keyword	true
sr	integer	Placement Available places: `1` - top block `0` - bottom block	true
adscnt	integer	Number of PPC ads	true
docs	integer	Displays how many documents were in search results	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"word":"domiso pizza","pos":1,"ws":5000000,"header":"50% Off All Menu Price Pizza - Online Ordering","mincpc":"0.540","maxcpc":"1.250","numwords":2,"sr":1,"txt":"Get 50% Off All Domino's Online Pizza Orders At Menu Price This Week Only. Order Your Next Pizza Online & Track Its Delivery With The Domino's Tracker®. Find A Location Near You. Track Your Order. Types: Hand Tossed, Thin Crust, Brooklyn Style, Gluten Free Crust.","adscnt":1,"docs":87}],"total":1}

PPC: ads

GET `report/simple/context/ads`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
full	boolean	false	If `true`, keyword array for each ad will be included in a report	false
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/context/ads?base=gny&domain=dominos.com&full=true&sort=keyscnt%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
id	integer	Ad ID	false
header	string	Ad's header	true
txt	string	Ad's text	true
keyscnt	integer	Number of keywords	true
keys	array	Keywords of an ad, available if parameter `full` provided	false

Response example:

            {"current_page":1,"per_page":25,"last_page":25,"data":[{"id":3614209030,"header":"Domino’s® Late Night - Domino's® Delivers Late Night","txt":"Pizza, Sandwiches, Wings, & More. Order Online For Pickup And Delivery. Track Your Order. Find A Location Near You. Types: Hand Tossed, Thin Crust, Brooklyn Style, Gluten Free Crust.","keyscnt":3,"keys":["pizza delivery after 1am","pizza delivery that`s open","pizza delivery after 10pm"],"url":"https://www.dominos.com/"}],"total":612}

PPC - competitors

GET `report/simple/context/concurents`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/context/concurents?base=gny&domain=dominos.com&sort=cnt%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
name	string	Domain name	true
perc	double	% of shared keywords in a domain's keywords	true
theme	double	% of domain keywords in an analyzed domain's keywords	true
cnt	integer	Shared keywords in a domain's keywords	true
it1	integer	Number of keywords in Top 1	true
it3	integer	Number of keywords in Top 3	true
it5	integer	Number of keywords in Top 5	true
it10	integer	Number of keywords in Top 10	true
it50	integer	Number of keywords in Top 50	true
pagesinindex	integer	Number of a website's pages found in search results	true
adsenseid	string	Publisher identifier in Google Adsense	false
analytics	integer	Identifier in Google Analytics	false
vis	integer	Estimation of a number of visits per day	false
adscnt	integer	Number of PPC ads	true
adkeyscnt	integer	Number of keywords in PPC	true
adtraf	integer	Rough estimation of a number of visits score PPC	false

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"id":29945465,"name":"google.com","perc":0,"theme":15,"cnt":108,"it1":8257,"it3":23151,"it5":34748,"it10":67527,"it50":481335,"pagesinindex":84048,"adsenseid":"0","analytics":"","vis":35290856,"adscnt":666137,"adkeyscnt":749695,"adtraf":770712}],"total":12}

SEO: Keywords of the website

GET `report/simple/organic/keywords`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/organic/keywords?base=gny&domain=dominos.com&sort=pos%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
url	string	Page url	true
delta	integer	Change of domain position in SERP (compared to last month)
pos	integer	Position in SERP	true
ws	integer	Volume	true
serpf	string	SERP date
numwords	integer	Number of words in a keyword	true
kid	integer	Keyword ID
docs	integer	Displays how many documents were in search results	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1643,"data":[{"word":"ww dominos pizza","url":"/en","delta":0,"pos":1,"ws":50,"serpf":"2022-09-24","numwords":3,"kid":5054993,"docs":59}],"total":41075}

SEO: Website pages

GET `report/simple/organic/sitepages`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/organic/sitepages?base=gny&domain=dominos.com&sort=it50%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
url	string	Page URL	true
it1	integer	Number of keywords in Top 1	true
it3	integer	Number of keywords in Top 3	true
it5	integer	Number of keywords in Top 5	true
it10	integer	Number of keywords in Top 10	true
it50	integer	Number of keywords in Top 50	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"url":"\/","it1":45,"it3":127,"it5":257,"it10":807,"it50":5321,"vis":22752}],"total":1}

SEO: Page's keywords

GET `report/simple/organic/keywords/bypage`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
page_url	string	true	Page URL `Available in "SEO pages" and "SEO keywords" reports`	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/organic/keywords/bypage?base=gny&domain=dominos.com&page_url=%2Fbrands%2Fadidas&sort=pos%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
ws	integer	Volume	true
pos	integer	Position in SERP	true
numwords	integer	Number of words in a keyword	true
adscnt	integer	Number of PPC ads	true
docs	integer	Displays how many documents were in search results	true
serpf	string	SERP date
kid	integer	Keyword ID

Response example:

            {"current_page":1,"per_page":25,"last_page":1643,"data":[{"word":"local power dominos","pos":5,"ws":500,"numwords":3,"adscnt":0,"docs":1710000,"serpf":"2022-09-24","kid":11205955}],"total":41075}

SEO: Competitors of the website in organic searches

GET `report/simple/organic/concurents`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/organic/concurents?base=gny&domain=dominos.com&sort=cnt%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
name	string	Domain name	true
perc	double	% of shared keywords in a domain's keywords	true
theme	double	% of domain keywords in a analyzed domain's keywords	true
cnt	integer	Shared keywords in a domain's keywords	true
it1	integer	Number of keywords in Top 1	true
it3	integer	Number of keywords in Top 3	true
it5	integer	Number of keywords in Top 5	true
it10	integer	Number of keywords in Top 10	true
it50	integer	Number of keywords in Top 50	true
pagesinindex	integer	Number of a website's pages found in search results	true
adsenseid	string	Publisher identifier in Google Adsense	false
analytics	integer	Identifier in Google Analytics	false
vis	integer	Estimation of a number of visits per day	false

Response example:

            {"current_page":1,"per_page":25,"last_page":24,"data":[{"id":30854096,"name":"yelp.com","perc":0,"theme":36,"cnt":14698,"it1":524339,"it3":2145011,"it5":3528537,"it10":5760792,"it50":10996221,"pagesinindex":3431343,"adsenseid":"0","analytics":"","vis":929908}],"total":597}

SEO: Competitors of the website's page

GET `report/simple/organic/concurent_pages`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
domain	string	true	Domain name	none
page_url	string	true	Page URL `Available in "SEO pages" and "SEO keywords" reports`	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/organic/concurent_pages?base=gny&domain=dominos.com&page_url=%2Fbrands%2Fadidas&sort=pos%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
domain	string	Domain name	true
url	string	Page displayed in search results	true
perc	double	% of shared keywords in a page's keywords	true
theme	double	% of source page's keywords in a page's keywords	true
cnt	integer	Shared keywords in a domain's keywords	true
it1	integer	Number of keywords in Top 1	true
it3	integer	Number of keywords in Top 3	true
it5	integer	Number of keywords in Top 5	true
it10	integer	Number of keywords in Top 10	true
it50	integer	Number of keywords in Top 50	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"did":29924580,"url":"\/shop\/producer\/6334\/sort\/a\/page\/1.html","domain":"my-shop.ru","cnt":80,"perc":64,"theme":80,"it1":0,"it3":0,"it5":0,"it10":4,"it50":125}],"total":1}

Similar keywords

GET `report/simple/similarkeys`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
base	string	true	Regional database, from which samples are being taken Possible values: `gny` - Google: New York	none
keyword	string	true	search keyword	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/simple/similarkeys?base=gny&keyword=pizza%2Bdelivery &sort=wsk%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
cnt	integer	How similar a keyword is to its original keyword	true
ws	integer	Volume	true
docs	integer	Displays how many documents were in search results	true
avbid	integer	Average cost per click	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"word":"как сделать ремонт на балконе","ws":573,"wsk":26,"cnt":68,"docs":100000000,"avbid":41}],"total":1}

Service keywords

GET `report/keywords`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/keywords?sort=wsk%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
ws	integer	Volume	true
numwords	integer	Number of words in a keyword	true
adscnt	integer	Number of PPC ads	true
docs	integer	Displays how many documents were in search results	true
isgeo	integer	Is a place-name	true
isquest	integer	Is a question	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"word":"бенеттон официальный сайт", "ws":17105,"wsk":11172,"docs":73000000, "numwords":3,"adscnt":8,"isgeo":0,"isquest":0}],"total":1}

Documentation of group report's f REST API

Create group report

POST `report/group`

Request body:

Field name	Type	Required	Description
base	String	true	Database name Available values: `gny` - Google: New York
domains	array	true	Domains array in report
name	String	false	Report name

Request example:

            {"base":"gny","domains":["dominos.com","pizzahut.com"]}

Response structure:

Field	Type	Description
rid	string	Report ID

Response example:

            {"rid":"696b62ec6bceaf00529c4dd4bce02b47"}

SEO - keywords

GET `report/group/organic/keywords/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/organic/keywords/696b62ec6bceaf00529c4dd4bce02b47?sort=ws%7Cdesc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
weight	integer	Keyword's importance in the report	true
ws	integer	Volume	true
numwords	integer	Number of words a in keyword	true
isgeo	integer	Is a place-name	true
isquest	integer	Is a question	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1759,"data":[{"id":57555808,"word":"fortaleza restaurant","weight":1,"ws":5000,"numwords":2,"isgeo":0,"isquest":0}],"total":43975}

SEO competitors

GET `report/group/organic/concurents/{rid}`

Request example:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/organic/concurents/696b62ec6bceaf00529c4dd4bce02b47?sort=cnt%7Cdesc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
name	string	Domain name	true
perc	double	Similarity (Percentage of shared keys among a domain's keys)	true
cnt	integer	Shared	true
it1	integer	Number of keywords for which the page ranks first in search results	true
it3	integer	Number of keywords for which the page holds positions from 1 to 3	true
it5	integer	Number of keywords for which the page holds positions from 1 to 5	true
it10	integer	Number of keywords for which the page holds positions from 1 to 10	true
it50	integer	Number of keywords for which the page holds positions from 1 to 50	true
pagesinindex	integer	Pages in index	true
adsenseid	string	If we've found markers of Google Adsense advertising network on a website's pages, this field will specify its numeric publisher identifier.	false
analytics	integer	A marker of Google Analytics statistical service, if any was found.	false
vis	integer	We calculate the "website visibility" parameter, and on the basis of this parameter we attempt to predict how much visits a website gets due to searches	false

Response example:

            {"current_page":1,"per_page":25,"last_page":400,"data":[{"id":"freshbrothers.com","name":"freshbrothers.com","perc":22,"cnt":461,"it1":134,"it3":294,"it5":380,"it10":523,"it50":2084,"pagesinindex":75,"adsenseid":"0","analytics":"","vis":2330}],"total":10000}

SEO pages

GET `report/group/organic/sitepages/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/organic/sitepages/696b62ec6bceaf00529c4dd4bce02b47?sort=vis%7Cdesc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
domain	string	Domain name	true
url	string	Page url	true
it1	integer	Number of keywords for which the page ranks first in search results	true
it3	integer	Number of keywords for which the page holds positions from 1 to 3	true
it5	integer	Number of keywords for which the page holds positions from 1 to 5	true
it10	integer	Number of keywords for which the page holds positions from 1 to 10	true
it50	integer	Number of keywords for which the page holds positions from 1 to 50	true
vis	integer	We calculate the "website visibility" parameter, and on the basis of this parameter we attempt to predict how much visits a website gets due to searches	true

Response example:

            {"current_page":1,"per_page":25,"last_page":13,"data":[{"url":"/","domain":"pizzahut.com","it1":987,"it3":2015,"it5":2306,"it10":3052,"it50":17904,"vis":2044}],"total":311}

Keywords in PPC

GET `report/group/context/keywords/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/context/keywords/696b62ec6bceaf00529c4dd4bce02b47?sort=weight%7Cdesc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
word	string	Keyword	true
weight	integer	Keyword's importance in the report	true
ws	integer	Volume	true
numwords	integer	Number of words a in keyword	true
isgeo	integer	Is a place-name	true
isquest	integer	Is a question	true
mincpc	double	Min CPC	true
maxcpc	double	Max CPC	true
competition	integer	Competition	true

Response structure:

            {"current_page":1,"per_page":25,"last_page":32,"data":[{"id":21049286,"word":"pizza specials coral springs","weight":2,"ws":50,"numwords":4,"isgeo":0,"isquest":0,"mincpc":"1.090","maxcpc":"2.100","competition":2}],"total":780}

PPC competitors

GET `report/group/context/concurents/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/context/concurents/696b62ec6bceaf00529c4dd4bce02b47?sort=cnt%7Cdesc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
name	string	Domain name	true
perc	double	Similarity (Percentage of shared keys among a domain's keys)	true
cnt	integer	Shared	true
it1	integer	Number of keywords for which the page ranks first in search results	true
it3	integer	Number of keywords for which the page holds positions from 1 to 3	true
it5	integer	Number of keywords for which the page holds positions from 1 to 5	true
it10	integer	Number of keywords for which the page holds positions from 1 to 10	true
it50	integer	Number of keywords for which the page holds positions from 1 to 50	true
pagesinindex	integer	Pages in index	true
adsenseid	string	If we've found markers of Google Adsense advertising network on a website's pages, this field will specify its numeric publisher identifier.	false
analytics	integer	A marker of Google Analytics statistical service, if any was found.	false
vis	integer	We calculate the "website visibility" parameter, and on the basis of this parameter we attempt to predict how much visits a website gets due to searches	false
adscnt	integer	Number of PPC ads advertising this domain	true
adkeyscnt	integer	Number of keywords for which a PPC ad from this website was displayed in search results	true
adtraf	integer		false

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"name":"doordash.com","perc":2,"cnt":104,"it1":12711,"it3":45339,"it5":84669,"it10":192872,"it50":608207,"pagesinindex":227685,"adsenseid":"0","analytics":"","vis":3198832,"adscnt":3170,"adkeyscnt":5209,"adtraf":41891}],"total":20}

PPC ads

GET `report/group/context/ads/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/context/ads/696b62ec6bceaf00529c4dd4bce02b47?sort=keyscnt%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
aid	integer	Unique Ad ID	false
domain	string	Domain name	true
header	string	First row of an ad – its header (or header + header 2, if both fields were filled in for the ad)	true
txt	string	Ad text itself	true
links	array	A list of quick link texts specified for an ad	true
facts	array	A list of facts specified for an ad	true
keyscnt	integer	Number of keywords	true

Response example:

            {"current_page":1,"per_page":25,"last_page":26,"data":[{"aid":827754818,"domain":"dominos.com","header":"Domino’s® Pizza Delivery - Domino’s® Pizza","txt":"Order Your Next Pizza Online & Track Its Delivery With The Domino's Tracker®. Pizza, Dips...","links":[],"facts":[],"keyscnt":12}],"total":647}

PPC ads - unique links

GET `report/group/context/ads/links/{rid}`

Request parameters:

Parameter	Type	Mandatory	Description	Default value
rid	string	true	Report identifier	none
Standard keyword parameters
page	integer	false	Sequence number of a results page	1
per_page	integer	false	Number of results on one page	50 000
sort	string	false	Data sorting by fields Format: `field\|direction`, where `field` - column name `direction` - sorting order, asc - ascending, desc - descending Value example: `pos\|asc` Value example for sorting by two fields: `pos\|asc,wsk\|desc`	none
filter	string	false	Details about filtering you can find in the API description - Data filtering section	none

Request example:

report/group/context/ads/links/696b62ec6bceaf00529c4dd4bce02b47?sort=link%7Casc&page=1&per_page=25

Response structure:

Field	Type	Description	Filter
links	string	Unique Links	true

Response example:

            {"current_page":1,"per_page":25,"last_page":1,"data":[{"links":"Hot pizza"}],"total":1}

Documentation of REST API used by Wordstato.com service

Category

Description of REST API used by the service

Description of REST API for simple requests

GET report/simple/domain_dashboard

GET report/simple/keyword_dashboard

GET report/simple/context/keywords

GET report/simple/context/keywords/byads

GET report/simple/context/ads

GET report/simple/context/concurents

GET report/simple/organic/keywords

GET report/simple/organic/sitepages

GET report/simple/organic/keywords/bypage

GET report/simple/organic/concurents

GET report/simple/organic/concurent_pages

GET report/simple/similarkeys

GET report/keywords

Documentation of group report's f REST API

POST report/group

GET report/group/organic/keywords/{rid}

GET report/group/organic/concurents/{rid}

GET report/group/organic/sitepages/{rid}

GET report/group/context/keywords/{rid}

GET report/group/context/concurents/{rid}

GET report/group/context/ads/{rid}

GET report/group/context/ads/links/{rid}

GET `report/simple/domain_dashboard`

GET `report/simple/keyword_dashboard`

GET `report/simple/context/keywords`

GET `report/simple/context/keywords/byads`

GET `report/simple/context/ads`

GET `report/simple/context/concurents`

GET `report/simple/organic/keywords`

GET `report/simple/organic/sitepages`

GET `report/simple/organic/keywords/bypage`

GET `report/simple/organic/concurents`

GET `report/simple/organic/concurent_pages`

GET `report/simple/similarkeys`

GET `report/keywords`

POST `report/group`

GET `report/group/organic/keywords/{rid}`

GET `report/group/organic/concurents/{rid}`

GET `report/group/organic/sitepages/{rid}`

GET `report/group/context/keywords/{rid}`

GET `report/group/context/concurents/{rid}`

GET `report/group/context/ads/{rid}`

GET `report/group/context/ads/links/{rid}`