API for developers

1. Format of request

API accepts requests at: https://api.topvisor.com/. We accept up to 10 requests per second from 1 ip.

Table – GET parameters of request

GET Parameters   Description
api_key Obligatory Your access key
oper Obligatory Operation type ['get', 'add', 'edit', 'del']
module Obligatory Module ['mod_projects', 'mod_keywords']
method    
filter   json-object, object filter, for example: {"id":12345}
post[]   POST parameters (alternative way of passing POST parameters)

Table - POST parameters of request

POST Parameters Description
Object parameters Used for editing, for assigning properties for objects
Id Object identifier (obligatory for changing and deleting)
Function arguments Various parameters necessary for running 'oper=get' requests. (Described in requests specification)

POST parameters can be passed with GET parameters in the address bar:
&post[site]=http://yandex.ru

Arrays are passed in the following way (array(1,2,3)):
&post[ids][]=1&post[ids][]=2&post[ids][]=3

Data in GET request must match url format of the address. For example:
&post[phrase]=Request%20with%20whitespaces.
To cast a string to url format in php you can use a urlencode() function.

Get list of the projects:
https://api.topvisor.com/?api_key=YOUR KEY&oper=get&module=mod_projects

Get list of locations supported by the system for Google by the term:
https://api.topvisor.com/?api_key=YOUR KEY&oper=get&module=mod_projects&method=regions&post[rows]=20&post[searcher]=1&post[search]=moscow

List of locations in a separate file

2. Response format

  • If you sent a request for getting data (oper=get), the response is an array of results: [data1,data2,...,dataN].
    • The following formats of responses are available: json, jgrid, jgrid-xml, xml_pager, json_pager. To select a format specify it in the parameter getFormat (getFormat=json_pager) that you pass.
      xml_pager, json_pager -response will additionally contain the number of pages and total number of results for request.
    • Additional POST-parameters (we recommend to use with getFormat):
      rows - number of rows to display (limitation is 5000);
      page - number of results page.
  • If the request was not processed due to an error, the response will contain json-object: {"message":"Error message", "error":"true"}.
  • The request for editing data (oper=add/edit/del), returns response as a json-object: {"result":data, "message":"Error message", "error":"false/true"}.

3. Manage project

All requests will begin with: https://api.topvisor.com/?api_key=YOUR_KEY

Table – manage project

Operation Parameters GET Parameters POST Response
Get the list of projects &oper=get&module=mod_projects[&method=full] Array of project objects
Create a project &oper=add&module=mod_projects site[,
on]
(Int) id
Delete a project &oper=del&module=mod_projects id (int) 0/1

Comments to project data:

      Name – project's name
      update – date of the latest rankings tracking
      status – 1: rankings tracking is running for the project, 0: no status
      subdomains –check if subdomains are included into ranks tracking
    on – 2: rankings are tracked after Yandex updates, 1: scheduled ranks tracking, 0: scheduled tracking is disabled, -1: project in archive
   time_for_update – days of week and time of scheduled ranks tracking (if days of weeks are not specified, project will be updated on a daily basis) - [1,2,3,4,5,6,7]:0-23
   wait_after_updates – number of hours after update till rankings are tracked - 0, 1, 2, 3, 4, 6, 12 hours
      count_keywords - number of active keywords in the project
      cat_y: presence in Yandex catalogs(0/1)
      cat_dm: presence in dmoz catalog (0/1)
      cat_m: presence in Mail catalog(0/1)
      project_cost: cost of one-time ranks tracking for the project
      email: E-mail of the project owner
      history: history of site statistics for the last 2 days
            [{
                cy – CY,
                pr – PR,
                indexed_y – indexed in Yandex,
                indexed_g – indexed in Google,
                traffic_y –Yandex traffic,
                traffic_g - Google traffic,
                backlinks – number of backlinks
             }, {…}]
      searchers: information about SE settings (if method=full)
      competitors: information about competitors in the project (if method=full)

Get data for the project number XXX:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=get&module=mod_projects&filter={"id": XXX}

Project settings.

Table - manage SE settings

Action GET Parameters POST Parameters Response
Add a SE &oper=add&module=mod_projects&method=searcher project_id,
searcher[,
domain,
regions]
(int) id_searcher
Delete a SE &oper=del&module=mod_projects&method=searcher id 0/1
Add a location to SE &oper=add&module=mod_projects&method=searcher_region searcher_id,
region
(int) id_region
Delete a location &oper=del&module=mod_projects&method=searcher_region id 0/1

Add Yandex SE to the project number XXX:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=add&module=mod_projects&method=searcher&post[id]=0
&post[project_id]=XXX&post[searcher]=0

Add Yandex SE and locations Moscow and St. Perersburg to the project number XXX:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=add&module=mod_projects&method=searcher&post[id]=0
&post[project_id]=XXX&post[searcher]=0&post[regions][]=213:1:ru&post[regions][]=2:1:ru

Add a location: Moscow to the SE with the number YYY (id_searcher):
https://api.topvisor.com/?api_key=YOUR_KEY&oper=add&module=mod_projects&method=searcher_region&post[searcher_id]=YYY
&post[region]=213

Schedule project updates:
URL: https://api.topvisor.com/?api_key=YOUR_KEY&oper=edit&module=mod_projects
POST-parameters (only POST method): id, on[, wait_after_updates[, time_for_update]]
id: project id

4. Manage keywords

Table – manage keywords

Operation GET Parameters POST Parameters Response
Get a list of keywords &oper=get&module=mod_keywords project_id[,
group_id,
only_enabled,
searcher *,
region_key *]
Array of keyword objects

* SE and Location must be specified to get necessary AMS data
Add a keyword &oper=add&module=mod_keywords phrase,
project_id[,
group_id]
(Int) id
Bulk import of keywords &oper=add&module=mod_keywords&method=import phrases*,
project_id,
group_id **
(Int) number of added keywords
* e.g., phrases='keyword1|||keyword2'
** group_id = -1 - add keywords to the new group
Delete a keyword &oper=del&module=mod_keywords id 0/1
Change keyword target &oper=edit&module=mod_keywords id,
target
0/1
Send a request for tracking AMS statistics for the project &oper=edit&module=mod_keywords&method=frequency_task id,
provider
regions_keys[],
phrase_forms[],
only_new
Number of submitted tasks (N of keyword * N of locations * N of word forms)
Learn cost of AMS tracking for the project &oper=get&module=mod_keywords&method=frequency_price project_id,
provider
regions_keys[],
phrase_forms[],
only_new
[NN.NN]
Get status of AMS tracking &oper=get&module=mod_keywords&method=frequency_status project_id [true] - AMS for the project is tracking,
[false] - AMS for the project is not tracking,
Add a group &oper=add&module=mod_keywords&method=group project_id,
name,
on
ID of a new group
Percent of completion of clustering &module=mod_keywords&method=percent_claster project_id [Percent]
Cost of clustering &module=mod_keywords&method=price_claster project_id [Price]
Run clustering &oper=add&module=mod_keywords&method=claster_task project_id,
searcher,
region_key,
region_lang,
count
{result:0/1}
Cost of re-clustering &module=mod_keywords&method=price_claster_change project_id [Price]
Level of the previous clustering &module=mod_keywords&method=count_claster project_id [Level from 1 to 9]
Run re-clustering (change level of the previous clustering) &oper=add&module=mod_keywords&method=claster_task_change project_id,
count
{result:0/1}

Table – types of AMS and suggested bid (you can see in the request's object)

Number of AMS Value Number of suggested bid Value
1 Basic 1 Premium placement
2 "Phrase" 2 1st place
3 "!Exact" 3 Guaranteed placement

Add a keyword in the project #:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=add&module=mod_keywords&post[project_id]=XXX&post[phrase]=KEYWORD

Bulk import of keywords in the project #:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=add&module=mod_keywords&method=import&post[project_id]=XXX&post[phrases]=KEYWORD1|||KEYWORD2

Get active keywords of the selected project # XXX:
https://api.topvisor.com/?api_key=ВАШ_КЛЮЧ&oper=get&module=mod_keywords&post[project_id]=XXX&post[only_enabled]=1

Get keywords of the project # XXX with AMS in the location Moscow:
https://api.topvisor.com/?api_key=YOUR_KEY&oper=get&module=mod_keywords&post[project_id]=XXX&post[region_key]=213

Track rankings of the project XXX in Saint Petersburg and Moscow, include all word forms (all AMS types) in Yandex and exact type in Google, skip AMS tracked in this month:
https://api.topvisor.com/?api_key=Your_Key&oper=edit&module=mod_keywords&method=frequency_task
&post[id]=XXX
&post[providers][0][provider]=0
&post[providers][0][regions_keys][]=2
&post[providers][0][regions_keys][]=213
&post[providers][0][phrase_forms][]=1
&post[providers][0][phrase_forms][]=2
&post[providers][0][phrase_forms][]=3
&post[providers][1][provider]=1
&post[providers][1][regions_keys][]=2
&post[providers][1][regions_keys][]=213
&post[providers][1][phrase_forms][]=2
&post[group_id]=YYY
&post[only_new]=1

5. Manage history

Table – manage keywords

Operation GET Parameters POST Parameters Response
Start rankings tracking &oper=edit&module=mod_keywords
&method=parse_task
id Number of submitted tasks. You will be charged = [number of tasks]*[price of one tracking]
Status of rankings tracking &oper=get&module=mod_keywords
&method=percent_of_parse
project_ids[] [{id:X, percent:Y},…]
View project's dynamic for keywords &oper=get&module=mod_keywords
&method=history
project_id,
page,
rows,
searcher,
region_key,
region_lang,
group_id,
date1,
date2,
type_range[,
competitor_id]
{
total,
phrases,
all_dates,
scheme
}

Description of POST parameters:

  • rows – number of keywords on the page (from 1 to 1000);
  • page – number of the page;
  • searcher – selected SE:
    • 0 - Yandex, location-based;
    • 1 - Google, location-based;
    • 2 - Mail
    • 3 - Sputnik
    • 4 - Youtube
    • 5 - Bing
    • 6 - Yahoo
    • -2 - Searchers comparison
  • region_key – location number (search results location code "-1", regions comparison "-2");
  • region_lang – language code of search results (by default "en");
  • group_id – id of keyword group ("-1" – all groups) ;
  • date1 – from the date (international format YYYY-MM-DD);
  • date2 – until the date (international formatт YYYY-MM-DD);
  • type_range – default 3:
    • 1 – Only days of Yandex updates;
    • 2 – the whole period (not more than 30 days);
    • 3 – two dates;
    • 4 – one day;
    • 5 – the last date of each month.
  • competitor_id – competitor id (get competitor's dynamics), how to get competitor's id: see. "Get list of projects" (competitors comparison "-2")

Note: If there was not specified one of the dates (date1 or date2), there would be a result including 30 last checks until the specified date


Description of the results:

  • total – total amount of keywords
  • phrases – array of keywords objects
    • dates – objects of dates:{
       'date_N':{
         page - webpage URL
         position - Site rankings
         visitors - Number of visits
       },…
      }
  • all_dates – list of dates, tracked for the selected location and SE.
  • scheme – report for dates and search engines
    • date – dates of project updates

Note: Data in the array phrases[0,1,2....][0][dates][0] correspond to the date scheme[dates][0][date]

Check status of project's rankings tracking XXX[]:
https://api.topvisor.com/?api_key=Your_Key&oper=get&module=mod_keywords&method=percent_of_parse
&post[project_ids][]=XXX1&post[project_ids][]=XXX2

View dynamics of project's keywords for the project XXX Yandex SE, for location: Saint Petersburg for all keyword groups from October 11 till October 15, 2014.:
https://api.topvisor.com/?api_key=Your_Key&oper=get&module=mod_keywords&method=history&post[project_id]=XXX
&post[rows]=20&post[page]=1&post[searcher]=0&post[region_key]=2&post[group_id]=-1&post[date1]=2013-10-11
&post[date2]=2013-10-15&post[type_range]=2

Pay attention, that you should request data only for the locations and SE selected in the settings. Otherwise, you will not get results.

Getting null in the results array ([0]) means an attempt to request data of somebody else's project.

6. Other functions

Table – useful functions

Operation GET Parameters Response
Get user's balance (your account) &oper=get&module=bank&method=balance [NN.NN]
Get statistics of transferred xml-limits (your account) &oper=get&module=user&method=xml {
login,
site,
user,
count,
balance,
status
}
Get dynamics page summary &oper=get&module=mod_keywords&method=history_summary

Additional POST-parameters:
project_id,
group_id,
date1,
date2,
searcher,
region_key
{
avg,
count10,
count30,
count50,
count100,
count10000,
d: {count, up_position, down_position, stay_position},
up10,
up30,
up50,
up100,
up10000,
up_avg
}
Get information about project groups &oper=get&module=mod_keywords&method=groups {
project_id,
rows
}
Get Updates calendar &oper=get&module=mod_common&method=apometr_calendar

Additional POST-parameters:
date_month – дата,
action – output format (0 - general output, 1 - Yandex XML, -1 - Yandex SERP),
searcher,
region_key,
region_lang
{
date,
Am,
is_update
}

Description of the results for xml method:

  • site – site transferred
  • login – login transferred
  • count – total number of transferred limits
  • balance – number of available limits
  • user –user id in the system
  • status – status of transferred limits (0 - pending, 1 - accepted, 2 - declined)