BLACKFRIDAY2017

30/30 Black Friday Sale
grab your coupon now

30/30 black friday sale – grab your coupon now

API v2

All methods are accessed via: https://online.seranking.com/structure/clientapi/v2.php. Any incoming and outgoing data is in UTF-8 encoding. All API calls should be made with HTTPS, if no specified, request method is GET. The result of calling any method is the array in JSON format. While sending data by POST request, all the data should be JSON encoded string in 'data' element of POST body, i.e. data == {"param1":"value1","param2":"value2"} In each method, except the login, must be passed access-token (GET-parameter - "token"), that received upon a successful login. While calling any method you should specify its name in GET-parameter "method". The order of parameters doesn't matter. If call to method was unsuccessful, HTTP response code won’t be equal 200 (for example, 403 with the wrong login or password) + you will get the response ({"message": "description"}). Here is the description of each method:

login (authentication - receiving token to use other methods)

parameters:

  • login - username (required)
  • pass - md5 from the password (required)
A successful call returns something like:
{
"name":"name1 name2",
"token":"c3b7ce7ae4cce5a6312f4046b701da9d",
"avatar": "http://online.seranking.com/tmp/avatar/upload-icon.png"
}

The description of the parameters returned

  • name - full user's name
  • token - auth token for any other method
  • avatar - user's avatar image url

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=login&login=username&pass=md5passwords

searchEngines (the list of search engines)

This method has no parameters. Returns a list of all the search engines in an array of all possible regions (for Yandex) .
The data in each element of the array:

  • id – a unique identifier of the search engine
  • name - the name
  • regionid – the ID of a region for searchVolume
  • regions - an array of regions (for Yandex)
A successful call returns something like:
[
    {"id":"200","name":"Google USA","regionid":"123","regions":[]},
    {"id":"411","name":"Yandex Russia","regionid":"456","regions":[{"id":"213","name":"\u041c\u043e\u0441\u043a\u0432\u0430"},{"id":"1095","name":"\u0410\u0431\u0430\u043a\u0430\u043d"}, ...]},
    ....
]

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=searchEngines&token=logintoken

sites (a list of a user's sites)

This method has no parameters. Returns a list of all the client’s websites.
A successful call returns something like:

[
    {"id":123,"name":"site1.com", "group_id":null, "title":"my site", "todayAvgPosition":123, "yesterdayAvgPosition":111, "totalUp":0, "totalDown":5, "keysCount":124, "process":"99.9" , "SEs":[{"site_engine_id":"1","seID":"226","regionID":null},{"site_engine_id":"2","seID":"413","regionID":"157"},{"site_engine_id":"3","seID":"384","regionID":null},{"site_engine_id":"4","seID":"413","regionID":"153"}]},
    {"id":456,"name":"site2.com", "group_id":2, "title":"my site#2", "todayAvgPosition":222, "yesterdayAvgPosition":223, "totalUp":4, "totalDown":4, "keysCount":34, "process":"100" , "SEs":[{"site_engine_id":"5","seID":"226","regionID":null}]}
]

The description of the parameters returned for each site:

  • id - a unique identifier of a site(ID)
  • name - website URL
  • title – website title
  • group_id – id of site's group
  • todayAvgPosition – an average position for last position checking date (today)
  • yesterdayAvgPosition – an average position for prev position checking date (yesterday)
  • totalUp - how many keywords have moved up in SERP
  • totalDown - how many keywords have moved down in SERP
  • keysCount – keywords count
  • process - the current percentage of the website rankings processing
  • SEs - an array of search engine IDs, to which the site is attached
  • group_id - website group ID

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=sites&token=logintoken

siteKeywords (a list of website keywords)

parameters

  • siteid – a unique identifier of a website (required)
A successful call returns something like:
[
	{"id":1, "name":"key1", "group_id":"11", "link": null, "first_check_date": null"},
	{"id":2, "name":"key2", "group_id":"22", "link": "http://mysite.com/", "first_check_date": "2015-02-03"},
	....
]

The description of the parameters returned for each keyword:

  • id - a unique identifier of a keyword(ID)
  • name - keyword
  • group_id – ID of keyword's group
  • link – target URL
  • first_check_date – date of first check for keyword

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=siteKeywords&siteid=12345&token=logintoken

stat (statistics on keyword positions)

parameters:

  • siteid – a unique identifier of a website (required)
  • dateStart – the start date in the format yyyy-mm-dd (optional , by default - today minus one week )
  • dateEnd – the end date in the format yyyy-mm-dd (optional , by default - today)
  • SE - search engine IDs, on which statistics should be displayed - a string with numbers separated by a comma (200,411, 453,). If it is not specified it will be displayed for all search engines of a website (optional)
A successful call returns something like:
[
    {"id":"1","keywords":[{"id":"1","positions":[{"date":"2013-09-03", "change":"1","pos":"1", "price":3},...]]},
    ....
]

Returns an array of all the search engines of a website. Each search engine has an array of keywords. Sample element from "keywords" array:

    {
        "id": "4188",
        "positions": [
            {"date": "2014-06-20", "pos": "2", "change": 0, "price":4},
            {"date": "2014-06-21", "pos": "2", "change": 0, "price":3},
            {"date": "2014-06-22", "pos": "3", "change": 0, "price":2},
            {"date": "2014-06-23", "pos": "4", "change": -1, "price":1}
        ],
        "landing_pages": [
            {"url": "http:\/\/mysite.com\/", "date": "2014-02-06"},
            {"url": "http:\/\/mysite.com\/page1", "date": "2014-02-08"}
        ]
    }
    
  • id - unique key identifier
  • positions - array of elements:
    • date - date in "yyyy-mm-dd" format
    • change - the change of keyword positions compared to the previous date (can be negative)
    • pos - current position
    • price - price, based on financial reports settings
  • landing_pages - array of elements:
    • date - date in "yyyy-mm-dd" format
    • url - url in SERP

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=stat&siteid=12345&dateStart=2014-01-01&token=logintoken

logout – the session interruption

This method has no parameters. Resets the access-token obtained in authorization. After calling the token method obtained earlier, it becomes invalid.


The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=logout&token=logintoken

searchVolumeRegions (a list of regions for avg.search volume)

This method has no parameters. Returns a list of all regions for getting avg.search volume..
A successful call returns the following:

[
    {"id":"1","name":"Afghanistan"},
    {"id":"2","name":"Algeria"},
    ...
]

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=searchVolumeRegions&token=logintoken

keySearchVolume (getting avg.search volume for one keyword)

Returns avg.search volume for a specified region and a keyword. Parameters:

  • regionid – a region ID. All regions and its IDs can be obtained with the method searchVolumeRegions (required)
  • keyword – a keyword (search query). It should be url-encoded (required)
A successful call returns something like:
{"volume":123500}

The sample call : https://online.seranking.com/structure/clientapi/v2.php?method=keySearchVolume&regionid=12&keyword=%D0%BA%D0%BB%D1%8E%D1%87&token=logintoken

keySearchVolumeList (getting avg.search volume for keywords list)

Returns avg.search volumes for a specified region and keywords list.
Parameters:

  • regionid - a region ID. All regions and its ID can be obtained with the method searchVolumeRegions (required)
  • keyword - an array of keywords (search queries) (required)
A successful call returns something like:
{
    "keyword1":"123500",
    "keyword2":"5678"
}

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=keySearchVolumeList&regionid=12&keyword[]=keyword1&keyword[]=keyword2&token=logintoken

addSiteKeywords (add keywords to site)

Returns array with to elements: 'added' - qty of added keywords, 'ids' - array of IDs for added keywords.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - site ID (required)
  • keywords - array of keywords (required)
  • groupid - key group ID (if not specified, the default group will be used)
A successful call returns something like:
{
    "added": 2,
    "ids": [111, 112]
}

addSiteKeywordsExt (add keywords to site)

Extended version of addSiteKeywords. Returns array with to elements: 'added' - qty of added keywords, 'ids' - array of IDs for added keywords.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - site ID (required)
  • keywords - associative array of keywords (keyword=>targetUrl pairs) (required)
  • groupid - key group ID (if not specified, the default group will be used)
  • is_strict_target_urls - check rankings for target URLs only (0 or 1, default - 0)
A successful call returns something like:
{
    "added": 2,
    "ids": [111, 112]
}

addSite (add site)

Returns ID of new site of keywords, element 'siteid' in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • url - site ulr (required)
  • title - site name (required)
  • depth - collection depth (50,100,150,200), default - 100
  • subdomain_match - match subdomains in SERP? (0 or 1), default - 0
  • exact_url - exact URL? (0 or 1), default - 0
  • manual_check_freq - check frequency - ('check_daily','check_1in3','check_weekly','check_yandex_up','manual'), по-умолчанию - check_daily
  • auto_reports - weekly report? (0 or 1), default - 1
  • group_id - ID of site group to put newly created site
  • day_of_week - if manual_check_freq param is set to 'check_weekly', you can set day of week here. Values from 1 (Monday) to 7 (Sunday)
Sample PHP code:
        $method = 'addSite';
        $token = 'my_login_token';

        $apiUrl = 'https://online.seranking.com/structure/clientapi/v2.php?method='.$method.'&token='.$token;
        $curlHandler = curl_init($apiUrl);
        curl_setopt($curlHandler, CURLOPT_POST, 1);
        $data = [
            'url' => 'http://my_site.com',
            'title' => 'my site',
        ];
        curl_setopt($curlHandler, CURLOPT_POSTFIELDS, http_build_query(array('data' => json_encode($data))));
        curl_setopt($curlHandler, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curlHandler, CURLOPT_SSL_VERIFYHOST, 2);
        curl_setopt($curlHandler, CURLOPT_SSL_VERIFYPEER, false);
        $result = curl_exec($curlHandler);
        $err = curl_error($curlHandler);
        if ($err) {
            print 'error: '.$err."\n";
        }
        print 'result: '.$result;
    

deleteSite (delete a site)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - site ID to delete (required)

moveSites2group (moves sites to another group of sites)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • site_ids - array of sites ID to move (required)
  • group_id - group ID to move site to (required)

sitesGroupsList (sites groups list)

Returns sites groups list. A successful call returns something like:

        [
            {"id":"111","name":"group1"},
            {"id":"222","name":"group2"},
            ...
        ]
    

addSiteGroup (adds new group of sites)

Returns ID of new created group on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • name - name for new group (required)

deleteKeywords (delete keywords)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • keywords_ids - array of keywords ID to delete (required)
  • siteid - site ID of keywords (required)

addKeywordsGroup (adds keyword group)

Returns key 'id' (=1), holding an ID of new group in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • name - group name (required)
  • siteid - site ID to add group (required)

moveKeywords2Group (moves keywords from one group to another)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • keywords_ids - array of IDs for moved keywords (required)
  • siteid - site ID of group (required)
  • groupid - group ID to move keywords (required)

changeGroupName (changes keywords group name)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • newname - new group name (required)
  • siteid - site ID of group (required)
  • groupid - group ID (required)

deleteKeywordGroup (delete keywords group)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - site ID of group (required)
  • groupid - group ID (required)

keywordsGroupsList (keywords groups list)

Returns keywords groups list for a specified site.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - site ID of group (required)
A successful call returns something like:
        [
            {"id":"111","name":"group1","creation_date":null},
            {"id":"222","name":"group2","creation_date":"2016-08-08"},
            ...
        ]
    

updateSiteSE (update/add site's search engines)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid (required) - site ID
  • se (required) - array of search engines,
                    [
                        "engineId1" => {
                            "region_name" => "DesiredRegionName1",
                            "lang_code" => "LangCode1",
                        },
                        "engineId2" => null,
                        ...
                    ]
                
    "region_name" and "lang_code" (see method getGoogleLangs for full list) are only for google search engines (empty string or NULL for others)

getGoogleLangs (get google's languages)

Returns full list of available languages for google search engines as key=>value (code=>full name) list. This method does not require any parameters
A successful call returns something like:

            [
                "de":"Deutsch",
                "en":"English",
                "es":"español"
                ...
            ]
        

competitorsList (list of competitors)

Parameters:

  • siteid - site ID (required)
A successful call returns something like:
            [
              {"id":"111", "name":"my competitor","domain":"comp1domain.com","pr":null, "tic":1000},
            ...
              {"id":"222", "name":"my competitor5","domain":"comp5domain.com","pr":2, "tic":null}
            ]
        

Returns a list of all added competitors for specified site as array:

  • id - a unique identifier of the competitor
  • name - competitor's name
  • domain - competitor's domain
  • pr - Google PageRank of competitor's domain
  • tic - Yandex Tic of competitor's domain

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=competitorsList&siteid=your_site_id&token=logintoken

competitorStat (statistics on keyword positions for competitor)

parameters:

  • competitorid – a unique identifier of a competitor (required)
  • dateStart – the start date in the format yyyy-mm-dd (optional , by default - today minus one week )
  • dateEnd – the end date in the format yyyy-mm-dd (optional , by default - today)
  • SE - search engine IDs, on which statistics should be displayed - a string with numbers separated by a comma (200,411, 453,). If it is not specified it will be displayed for all search engines of a website (optional)

A successful call returns something like:

[

    {"id":"1","keywords":[{"id":"1","positions":[{"date":"2013-09-03", "change":"1","pos":"1"},...]]},
    ....
]

Returns an array of all the search engines of a website competitor belongs to. Each search engine has an array of keywords, consisting of elements that have the form {"id": 123 , "positions": [...]} - id search query and an array of positions (positions):

  • date - the date in the format yyyy-mm-dd
  • change – the change of keyword positions compared to the previous date (it can be negative)
  • pos - the current position

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=competitorStat&competitorid=12345&dateStart=2014-01-01&dateEnd=2014-01-15&SE[]=123&SE[]=456&token=logintoken

addSiteCompetitor (adding competitor to site)

Returns a unique identifier of added competitor, key "id" in result array.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - a unique identifier of a website (required)
  • url - competitor's site url (required)
  • name - competitor name (will be used url if omitted)

deleteCompetitor (delete a competitor)

Returns key 'status' (=1) in result array on successful call.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • competitorid - competitor ID to delete (required)

getTopCompetitors (get top 10 site competitors)

Gets site's top 10 competitors with URLs and positions
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid – a unique identifier of a website (required)
  • date – date for report (current date will be used if omitted)
  • seID – identifier of search engine (optional, every engine data will be in response if omitted)
  • keywordID – identifier of site keyword - call siteKeywords method to get identifiers (optional, all keywords will be in response if omitted)

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=getTopCompetitors&siteid=12345&date=2016-02-01&seID=200&keywordID=678&token=logintoken

updateSite (site settings update)

Returns key 'status' (=1) in result array on successful call.
Parameters (anything is optional except siteid) passed in JSON-encoded format in 'data' element of POST request:

  • siteid - a unique identifier of a website (required)
  • site_title - site name
  • site_name - site URL
  • site_exact_url -exact URL? (0 or 1)
  • site_active - status (0 - disabled, 1 - enabled)
  • site_subdomain_match - match subdomains in SERP? (0 or 1)
  • site_depth - collection depth (50,100,150,200), default - 100

getBalance

Returns account's balance.
No parameters required A successful call returns something like:

{"currency":"USD","value":11.22}

The sample call: https://online.seranking.com/structure/clientapi/v2.php?method=getBalance&token=logintoken

setPosition (manual position set)

Returns key 'status' (=1) in result array on successful call.
Parameters (all required) passed in JSON-encoded format in 'data' element of POST request:

  • keyword_id - identifier of site keyword
  • date - date in the format yyyy-mm-dd
  • search_engine_uid - search engine id
  • position - position, from 0 to 200. 0 means "not found"

recheck (start keywords positions checker)

On successful call returns the total number of keywords queued to recheck.
Parameters passed in JSON-encoded format in 'data' element of POST request:

  • siteid - Website ID (required). If this is the only parameter stated in the query all project keywords positions will be rechecked.
  • site_engine_id - Search engine ID, see sites (optional). When applied the keywords positions will be rechecked only for the specified search engine.
  • keywords - an array of the specific keywords to be rechecked (optional). Two parameters are stated for every keyword: site_engine_id (website search engine identifier) and keyword_id (website keyword identifier). When applied, the site_engine_id parameter is ignored.

Ask Us a Question
or Leave Some Feedback!

I've been using SE Ranking for tracking my progress in getting to the first page of Google for Qeryz for my target keywords. It's done a phenomenal job of keeping itself accurate - which sets it apart from all other rank tracking tools I've used in the past. That alone is reason enough for me to use and stay with SE Ranking amongst other things. people Sean Si from Qeryz.com
SE Ranking is my favorite tool for tracking daily changes in SERP rankings, including localized rankings. Especially the possibility to re-check on request is very nice. Next to that, the Website Audit is very helpful for tracking on-page SEO issues. people Simon Kloostra from Joomlaseo.com
So when I learned about SE Ranking, and tried it for our clients, I couldn't help but use and recommend it to our audience by writing a review about it. Such a promising tool! people Pam Sallegue of SEO-Hacker
Content marketing is a key component of my marketing strategy. I want to create content that is relevant, engaging and ranks well. SE Ranking enables me to carry out keyword research and ensure my content is as effective as possible. people Paul Boag from Boagworld.com
SE Ranking is my go-to rank tracking tool after years of trying to finding the right tool. It's easy to use and has all the features I need to keep on top of my rankings. people Adam Connell from Bloggingwizard.com
I’ve been using SE Ranking for 4 months now and it is now an important tool in my arsenal of blogging tools. It’s powerful and lets me track my rankings for keywords on Successful Blogging. I’ve been pleased with the support that they give you and the quality of SE Ranking. people Sue Anne Dunlevie from Successfulblogging.com
I’ve been lucky enough to get an early access to SE Ranking and found it really user-friendly. I am very busy and I need to save time and SE Ranking is perfect for that: Setting up a site takes minutes and everything is very easy and fast to find. I just love those rankings reports SE Ranking sends every week or month. No need to login to check the rankings: You get your rankings in your email inbox and can continue working. people Ann Smarty from www.seosmarty.com
All aboard! I brought my clients over to SE Ranking. I thought I would have never left my old KW tracking software, but guess what? I outgrew it. To all marketing agencies, start selling content marketing packages like we have. Record keyword rankings & monitor backlinks within one software. Nice keyword suggestion tool too. Thanks SE Ranking. people Francisco Meza from planetmarketing.com