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

fieldLIKEvalue

string

Not like

fieldNOT LIKEvalue

string

Starts with

fieldSTARTSWITHvalue

string

Ends with

fieldENDSWITHvalue

string, integer

Is one of

fieldINvalueA,valueB

string, integer

Is not one of

fieldNOT INvalueA,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

fieldBETWEENvalueA@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
  1. <?php
  2.  
  3. /*
  4.  * Example of PHP script, with use cURL lib
  5.  *
  6.  */
  7.  
  8. $url = "https://api.wordstato.com/report/simple/context/concurents?base=gny&domain=foodband.ru&sort=cnt%7Cdesc&page=1&per_page=250";
  9. $curl = curl_init();
  10. $headers = array('X-Keyso-TOKEN: 5a2a5f0e538dd5.6691914852255446e23a9bcac46ee5255625f5d5');
  11. curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  12. curl_setopt($curl, CURLOPT_URL, $url);
  13. curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
  14. curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
  15. curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  16. curl_setopt($curl, CURLOPT_HEADER, true);
  17. curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 15);
  18. curl_setopt($curl, CURLOPT_TIMEOUT, 15);
  19. $response = curl_exec($curl);
  20. $header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
  21. $headerCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  22. $responseBody = substr($response, $header_size);
  23. curl_close($curl);
  24.  

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}