nofollow

Описание API v2 от SE Ranking

API доступен по ссылке http://online.seranking.com/structure/clientapi/v2.php . Все принимаемые и выдаваемые данные - в кодировке UTF-8. Взаимодействие идёт по протоколу HTTP, если не указано иное, то параметры передаются через GET. При передаче параметров через POST-запрос, весь их массив должен быть json_encoded и находиться в элементе data POST-запроса, т.е. data == {"param1":"value1","param2":"value2"} Результат вызова любого метода - массив в JSON-формате. В каждый метод, кроме логина должен передаваться access-token (GET-параметр - "token"), получаемый при успешном логине. При вызове любого метода API надо указывать его название в GET-параметре "method". Порядок передаваемых GET-параметров не имеет значения. При неуспешном вызове любого метода - http код ответа будет не равен 200 (например 403 при неправильном логине-пароле) + в ответе будет приведено описание ( {"message":"description"} ) . Ниже представлено описание каждого метода.

login (аутентификация - получение токена для вызова остальных методов)

параметры

  • login - логин (обязательный параметр)
  • pass - md5 от пароля (обязательный параметр)
При успешном вызове возвращает результат вида:
{
"name":"name1 name2",
"token":"c3b7ce7ae4cce5a6312f4046b701da9d",
"avatar": "http://online.seranking.com/tmp/avatar/upload-icon.png"
}

Описание возвращаемых параметров:

  • name - полное имя пользователя
  • token - токен авторизации
  • avatar - адрес изображения аватара пользователя

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=login&login=вашлогин&pass=хэшМд5пароля

searchEngines (список поисковых систем)

Для этого метода нет параметров. Возвращает список в массиве всех поисковиков с возможными регионами (для яндекса).
Данные в каждом элементе массива:

  • id - уникальный идентификатор поисковой системы
  • name - название
  • regionid - ID региона для searchVolume
  • regions - массив регионов (для яндекса)
При успешном вызове возвращает результат вида:
[
    {"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"}, ...]},
    ....
]

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=searchEngines&token=токенПолученныйПриЛогине

sites (список сайтов пользователя)

Для этого метода нет параметров. Возвращает список всех сайтов клиента.
При успешном вызове возвращает результат вида:

[
    {"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":[{"seID":"226","regionID":null},{"seID":"413","regionID":"157"},{"seID":"384","regionID":null},{"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":[{"seID":"226","regionID":null}] ,}
]

Описание параметров, возвращаемых для каждого сайта:

  • id - уникальный идентификатор сайта (ID)
  • name - url сайта
  • title - название сайта
  • group_id – ID группы сайтов
  • todayAvgPosition - средняя позиция за последнюю дату снятия позиций (сегодня)
  • yesterdayAvgPosition - средняя позиция за предыдущую дату снятия позиций (вчера)
  • totalUp - сколько позиций поднялось в выдаче
  • totalDown - сколько позиций опустилось в выдаче
  • keysCount - всего запросов в сайте
  • process - текущий процент обработки позиций сайта
  • SEs - массив поисковиков, к которым привязан сайт, каждый элемент - массив с тремя элементами - seID (ID поисковика) , regionID (ID региона яндекса, если поисковик - не яндекс, то null), regionName (название города (или индекс), если такой был указан для google)

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=sites&token=токенПолученныйПриЛогине

siteKeywords (список запросов сайта)

параметры

  • siteid - уникальный идентификатор сайта (обязательный параметр)
При успешном вызове возвращает результат вида:
[
	{"id":1,"name":"ключ1","group_id":"11", "link":null, "first_check_date":null},
	{"id":2,"name":"ключ2","group_id":"22", "link":"http://mysite.ru/", "first_check_date":"2014-02-03"},
	....
]

Описание параметров, возвращаемых для каждого запроса:

  • id - уникальный идентификатор запроса (ID)
  • name - сам запрос
  • group_id – ID группы запросов
  • link – целевой URL
  • first_check_date – дата первой проверки запроса

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=siteKeywords&siteid=12345&token=токенПолученныйПриЛогине

stat (статистика по запросам)

параметры:

  • siteid - уникальный идентификатор сайта (обязательный параметр)
  • dateStart - дата начала в формате yyyy-mm-dd (необязательный параметр, по умолчанию - сегодня минус неделя)
  • dateEnd - дата конца в формате yyyy-mm-dd (необязательный параметр, по умолчанию - сегодня)
  • SE - ID поисковиков, на которые надо отобразить статистику - массив ID поисковиков сайта (для яндекса указывается в формате IDпоисковика~IDрегиона) Если не указан - отображается для всех поисковиков сайта (необязательный параметр)
При успешном вызове возвращает результат вида:
[
    {"seID":"1","regionID":null,"keywords":[{"id":"1","positions":[{"date":"2013-09-03", "change":"1","pos":"1", "price":3},...]]},
    ....
]

Возвращает массив из всех поисковиков сайта. В каждом поисковике - массив keywords, состоящий из элементов вида {"id":123,"positions":[...],"landing_pages":[...]} . Пример одного элемента массива keywords:

    {
        "id": "4188",
        "positions": [
            {"date": "2014-06-20", "pos": "2", "change": 0, "price":3},
            {"date": "2014-06-21", "pos": "2", "change": 0, "price":4},
            {"date": "2014-06-22", "pos": "3", "change": 0, "price":5},
            {"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 - уникальный идентификатор запроса
  • positions - массив с элементами:
    • date - дата в формате yyyy-mm-dd
    • change - изменение позиции по сравнению с пред. датой (может быть отрицательное)
    • pos - текущая позиция
    • price - цена, рассчитанная из настроек фин. отчёта
  • landing_pages - массив с элементами:
    • date - дата в формате yyyy-mm-dd
    • url - url в выдаче

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=stat&siteid=12345&dateStart=2014-01-01&SE[]=123&SE[]=123~456&token=токенПолученныйПриЛогине

logout - прекращение сеанса

Для этого метода нет параметров. Сбрасывает access-token, полученный при авторизации. После вызова метода token, полученный ранее, становится недействительным.


Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=logout&token=токенПолученныйПриЛогине
searchVolumeRegions (список регионов для avg.search volume)

Для этого метода нет параметров. Возвращает список всех регионов для получения avg.search volume.
При успешном вызове возвращает результат вида:

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

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=searchVolumeRegions&token=токенПолученныйПриЛогине

keySearchVolume (получение avg.search volume для одного запроса)

Возвращает avg.search volume для указанного региона и ключевого слова. параметры

  • regionid - ID региона. Все регионы и их ID можно получить в методе searchVolumeRegions (обязательный параметр)
  • keyword - ключевое слово (запрос), для которого будет получен avg.search volume. Должен быть url-encoded в url, т.е. "ключ" превратится в %D0%BA%D0%BB%D1%8E%D1%87 (обязательный параметр)
  • yandex_region_code - код региона из wordstat (необязательный параметр, если указан - вернётся частотность из яндекс wordstat, если нет - из google)
При успешном вызове возвращает результат вида:
{"volume":123500}

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=keySearchVolume&regionid=12&keyword=%D0%BA%D0%BB%D1%8E%D1%87&token=токенПолученныйПриЛогине

keySearchVolumeList (получение avg.search volume для списка запросов)

Возвращает avg.search volume для указанного региона и массива ключевых слов. параметры

  • regionid - ID региона. Все регионы и их ID можно получить в методе searchVolumeRegions (обязательный параметр)
  • keyword - массив ключевых слов (запросов), для которого будет получен avg.search volume. Каждый элемент должен быть url-encoded в url, т.е. "ключ" превратится в %D0%BA%D0%BB%D1%8E%D1%87 (обязательный параметр)
  • yandex_region_code - код региона из wordstat (необязательный параметр, если указан - вернётся частотность из яндекс wordstat, если нет - из google)
При успешном вызове возвращает результат вида:
{
    "keyword1":"123500",
    "keyword2":"5678"
}

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=keySearchVolumeList&regionid=12&keyword[]=%D0%BA%D0%BB%D1%8E%D1%87&keyword[]=sony&token=токенПолученныйПриЛогине

addSiteKeywords (добавление запросов к сайту)

Возвращает массив из двух элементов: 'added' - количество реально добавленных запросов, 'ids' - массив ID добавленных запросов. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - уникальный идентификатор сайта (обязательный параметр)
  • keywords - массив запросов (обязательный параметр)
  • groupid - ID группы запросов (если не указать, будет использована группа по умолчанию)
При успешном вызове возвращает результат вида:
    {
        "added": "2",
        "ids": [111,112]
    }
    

addSiteKeywordsExt (расширенное добавление запросов к сайту)

Возвращает массив из двух элементов: 'added' - количество реально добавленных запросов, 'ids' - массив ID добавленных запросов. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - уникальный идентификатор сайта (обязательный параметр)
  • keywords - ассоциативный массив запросов, пары запрос=>целевая_ссылка (обязательный параметр)
  • groupid - ID группы запросов (если не указать, будет использована группа по умолчанию)
  • is_strict_target_urls - Проверять позиции только для указанных целевых ссылок (0 или 1, по умолчанию - 0)
При успешном вызове возвращает результат вида:
    {
        "added": "2",
        "ids": [111,112]
    }
    

addSite (добавление сайта)

Возвращает ключ siteid (ID добавленого сайта) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • url - url сайта (обязательный параметр)
  • title - название сайта (обязательный параметр)
  • depth - глубина сбора позиций (50,100,150,200), по умолчанию - 100
  • subdomain_match - учитывать сабдомены в выдаче? (0 или 1), по умолчанию - 0
  • exact_url - точный URL? (0 или 1), по умолчанию - 0
  • manual_check_freq - частота сбора позиций - ('check_daily','check_1in3','check_weekly','check_yandex_up','manual'), по умолчанию - check_daily
  • auto_reports - еженедельный отчет? (0 или 1), по умолчанию - 1
  • group_id - ID группы, куда добавить созданный сайт
  • day_of_week - если указан manual_check_freq=check_weekly, то в этом параметре можно задать день недели. Значения от 1 (понедельник) до 7 (воскресенье)
Пример кода на PHP:
        $method = 'addSite';
        $token = 'токенПолученныйПриЛогине';

        $apiUrl = 'http://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);
        $result = curl_exec($curlHandler);
        $err = curl_error($curlHandler);
        if ($err) {
            print 'error: '.$err."\n";
        }
        print 'result: '.$result;
    

deleteSite (удаление сайта)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - ID сайта для удаления (обязательный параметр)

moveSites2group (переносит сайты в другую группу сайтов)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • site_ids - массив ID сайтов для перемещения (обязательный параметр)
  • group_id - ID группы, куда переместить сайты (обязательный параметр)

sitesGroupsList (список групп сайтов)

Возвращает список групп сайтов. При успешном вызове возвращает результат вида:

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

addSiteGroup (добавление группы сайтов)

Возвращает ID созданной группы . Параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • name - имя группы (обязательный параметр)

deleteKeywords (удаление запросов)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • keywords_ids - массив ID удаляемых запросов (обязательный параметр)
  • siteid - ID сайта, из которого удаляются запросы (обязательный параметр)

addKeywordsGroup (добавление группы для запросов)

Возвращает ключ id, содержащий id добавленной группы в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • name - имя группы (обязательный параметр)
  • siteid - ID сайта, в который будет добавлена группа (обязательный параметр)

moveKeywords2Group (перенос запросов в другую группу)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • keywords_ids - массив ID переносимых запросов (обязательный параметр)
  • siteid - ID сайта, к которому принадлежат запросы (обязательный параметр)
  • groupid - ID группы, куда переносить запросы (обязательный параметр)

changeGroupName (изменение названия группы запросов)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • newname - новое название группы (обязательный параметр)
  • siteid - ID сайта, к которому принадлежит группа (обязательный параметр)
  • groupid - ID группы (обязательный параметр)

deleteKeywordGroup (удаление группы запросов)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - ID сайта, к которому принадлежит группа (обязательный параметр)
  • groupid - ID удаляемой группы (обязательный параметр)

keywordsGroupsList (список групп запросов)

Возвращает список групп запросов для указанного сайта. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - ID сайта (обязательный параметр)
При успешном вызове возвращает результат вида:
        [
            {"id":"111","name":"group1","creation_date":"2016-08-08"},
            {"id":"222","name":"group2","creation_date":null},
            ...
        ]
    

updateSiteSE (обновление/добавление поисковиков сайта)

Возвращает ключ status (=1) в массиве результата при успешном вызове. параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid (обязательный параметр) - ID сайта
  • se (обязательный параметр) - массив поисковых систем в виде
                      [
                        "IDпоисковойСистемы1" => {
                            "region_name" => "названиеРегиона",
                            "lang_code" => "кодЯзыка",
                        },
                        "IDпоисковойСистемы2~IDрегиона" => null,
                        ...
                    ]
                
    "названиеРегиона" и "кодЯзыка" задаются только для гугл-поисковиков (для остальных пустая строка или null). Для яндекс-поисковиков ID поисковика задаётся как IDпоисковойСистемы~IDрегиона (например, яндекс-москва это 411~213)

getGoogleLangs (список языков гугла)

Возвращает полный список возможных языков для гугл-поисковиков в виде массива код=>название. Метод не требует параметров
При успешном вызове возвращает результат вида:

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

competitorsList (получение списка добавленных конкурентов)

параметры:

  • siteid - ID сайта для списка конкурентов (обязательный параметр)
При успешном вызове возвращает результат вида:
            [
              {"id":"111", "name":"my competitor","domain":"comp1domain.com","pr":null, "tic":1000},
            ...
              {"id":"222", "name":"my competitor5","domain":"comp5domain.com","pr":2, "tic":null}
            ]
        

Возвращает массив добавленных конкурентов с данными по ним:

  • id - уникальный идентификатор конкурента
  • name - указанное название конкурента
  • domain - домен сайта конкурента
  • pr - Google PageRank домена
  • tic - Яндекс тИЦ домена

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=competitorsList&siteid=айди_вашего_сайта&token=токенПолученныйПриЛогине

competitorStat (статистика по запросам для конкурентов)

параметры:

  • competitorid - уникальный идентификатор конкурента (обязательный параметр)
  • dateStart - дата начала в формате yyyy-mm-dd (необязательный параметр, по умолчанию - сегодня минус неделя)
  • dateEnd - дата конца в формате yyyy-mm-dd (необязательный параметр, по умолчанию - сегодня)
  • SE - ID поисковиков, на которые надо отобразить статистику - массив ID поисковиков сайта (для яндекса указывается в формате IDпоисковика~IDрегиона) Если не указан - отображается для всех поисковиков сайта (необязательный параметр)
При успешном вызове возвращает результат вида:
        [

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

Возвращает массив из всех поисковиков сайта, к которому относится конкурент. В каждом поисковике - массив keywords, состоящий из элементов вида {"id":123,"positions":[...]} - id запроса и массив позиций (positions):

  • date - дата в формате yyyy-mm-dd
  • change - изменение позиции по сравнению с пред. датой (может быть отрицательное)
  • pos - текущая позиция

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=competitorStat&competitorid=12345&dateStart=2014-01-01&SE[]=123&SE[]=123~456&token=токенПолученныйПриЛогине

addSiteCompetitor (добавление конкурента к сайту)

Возвращает уникальный идентификатор добавленного конкурента, ключ id в массиве результата.
Параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - уникальный идентификатор сайта (обязательный параметр)
  • url - url сайта конкурента (обязательный параметр)
  • name - имя сайта конкурента (если не указать, будет использован url)

deleteCompetitor (удаление конкурента сайта)

Возвращает ключ status (=1) в массиве результата при успешном вызове.
Параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • competitorid - уникальный идентификатор конкурента (обязательный параметр)

getTopCompetitors (получение топ 10 конкурентов для сайта)

Возвращает топ 10 конкурентов сайта с адресами и позициями
Параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid – уникальный идентификатор сайта (обязательный параметр)
  • date – дата (если не указана, будет возвращена выдача за текущую дату)
  • seID – идентификатор поисковой системы (необязательный параметр, если не указан, будут возвращены все)
  • keywordID – идентификатор ключевого слова (смотрите метод siteKeywords для получения списка с идентификаторами для сайта) (необязательный параметр, если не указан, будет возвращена выдача для всех ключевых слов)

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=getTopCompetitors&siteid=12345&date=2016-02-01&seID=200&keywordID=678&token=токенПолученныйПриЛогине

updateSite (обновление настроек сайта)

При успешном выполнении возвращает массив {"status" => 1} .
Параметры, передаваемые в json-encoded элементе 'data' в POST-запросе:

  • siteid - ID сайта (обязательный)
  • site_title - имя сайта (необязательный)
  • site_name - адрес сайта (необязательный)
  • site_exact_url - точный URL? (0 или 1) (необязательный)
  • site_active - автоматический съём позиций (0 - выключен, 1 - включён)
  • site_subdomain_match - учитывать сабдомены в выдаче? (0 или 1) (необязательный)
  • manual_check_freq - частота сбора позиций - ('check_daily','check_1in3','check_weekly','check_yandex_up','manual') (необязательный)
  • site_depth - глубина сбора позиций (50, 100,150,200) (необязательный)
  • manual_check_freq_day - если указан у сайта выставлена еженедельная проверка позиций (check_weekly_, то в этом параметре можно задать день недели. Значения от 1 (понедельник) до 7 (воскресенье) (необязательный)

getBalance

Возвращает баланс акаунта.
Не требует параметров
Результат вида:

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

Пример вызова: http://online.seranking.com/structure/clientapi/v2.php?method=getBalance&token=токенПолученныйПриЛогине

setPosition (ручная установка позиции)

При успешном выполнении возвращает массив {"status" => 1} .
Параметры (все обязательные), передаваемые в json-encoded элементе 'data' в POST-запросе:

  • keyword_id - ID запроса
  • date - дата в формате ГГГГ-ММ-ДД (yyyy-mm-dd)
  • search_engine_uid - ID поисковика (для яндекса указывается в формате IDпоисковика~IDрегиона)
  • position - позиция, от 0 до 200, 0 считается как "не найдено"

Остались вопросы?
Задавайте!
Один из тех случаев, когда получаешь даже больше чем ожидаешь. Мощный аудит сайтов, сравнение с конкурентами, маркетинг-план, система отчетов — действительно целый комплекс seo инструментов — это действительно удобно! people Дмитрий Клиндухов Генеральный директор
ООО Феррум Студио
Сервисом довольны, он позволяет автоматизировать сбор позиций и анализировать динамику большого количества сайтов, продвигаемых нашей компанией.
Радуют постоянные работы, направленные на улучшение работы сервиса и расширение его функционала.
people Владимир Ведущий SEO-специалист
ООО Россайт
Несколько раз пытались начать работать с сервисом, но всегда что-то останавливало.
Сейчас перевели все проекты к вам. Всем довольны. Используем в качестве мониторинга позиций и анализа сниппетов. Must have. Спасибо!
people Сергей Новицкий Генеральный директор
интернет-агентства Brandmaker
Лучший сервис по проверке позиций в Рунете. Приятно удивил не только очень быстрой и 100% точной проверкой позиций, но и наличием мощного инструментария по аналитике запросов и аудиту сайтов. people Юрий Макаров SEO-специалист,
блогер
Очень доволен, замена почившему скрипту Лидер - идеальная. Техподдержка отвечает быстро, помогают сразу. Функции добавляются нужные. Всем советую! people Алексей Баранцев Коммерческий директор
ООО «Абарис»
Спасибо за отличный сервис, и суперскую тех. поддержку, помогли все настроить, отдельное спасибо Valery K и Alex D. people Станислав Голубев SEO-специалист
Практически все инструменты для эффективной работы оптимизатора в одном месте. Все очень удобно организовано, а интерфейс онлайн-версии продуман до мелочей. people Елена SEO-специалист,
блогер
Пользуюсь сервисом больше 2 лет. Хорошая техподдержка, постоянно допиливают новые фишки, которые помогают при анализе позиций продвигаемых сайтов и поиске проблемных мест в выдаче. Есть возможность быстро проанализировать всех своих конкурентов в два клика. people Дмитрий SEO-специалист,
блогер
Забыл что такое ручной контроль съема позиций. Даже после введения русскоязычной капчи - решили оперативно. Спасибо, так держать! people Александр Толкач директор binovery.com,
SEO-специалист