Регистрация сайта и управление

Регистрация сайта

URL: https://top.mail.ru/json/add

Параметр	Обязательно	Описание
apikey	да	Ключ к API, требуется для регистрации сайтов. Для получения ключа напишите нам
category	нет	Опционально, требуется в случае участия в рейтинге (rating=1). Для участия в рейтинге выберите наиболее подходящую для Вашего ресурса категорию Рейтинга Mail.Ru. Правильный выбор категории обеспечит Вам наибольший приток целевой аудитории со страниц Рейтинга Mail.Ru. А также поможет сравнить популярность своего ресурса с популярностью ресурсов конкурентов.
email	да	Адрес электронной почты, по которому Вам будет выслано подтверждение регистрации счётчика, его ID. Если Вы забудете свой пароль, то сервер сможет выслать Вам его по этому адресу. Также в случае значительной реорганизации Рейтинга Mail.Ru по этому адресу Вам может быть послано уведомление. Этот адрес не будет показываться на общедоступных страницах Рейтинга Mail.Ru.
ignore_url_warn	нет	Игнорирование ограничения на регистрацию нескольких счетчиков на один домен: ignore_url_warn=yes
password	да	Пароль Вам понадобится, если Вы захотите изменить какие-либо параметры счётчика или удалить свой ресурс из Рейтинга Mail.Ru. Также Вы можете закрыть свободный доступ к статистике по Вашему ресурсу - эта статистика будет доступна по паролю. Во избежание различных проблем с кодировками в пароле можно использовать только цифры, латинские буквы и символы _-+/*^%=~#$@:;.,!?{}()[]. Прописные и строчные буквы различаются. Не менее 7 и не более 15 символов.
public	да	Открытость статистики: 0 (нет) или 1 (да). Вы можете запретить просмотр подробной статистики Вашего ресурса другими пользователями (общедоступной будет только информация о количестве визитов и посетителей, показываемая на страницах Рейтинга Mail.Ru). Для доступа к подробной статистике Вы должны будете использовать свой пароль, введённый выше. После регистрации вы сможете настроить разрешение или запрет просмотра каждого вида отчета по отдельности.
rating	да	Участие в рейтинге: 0 (нет) или 1 (да). Участие в рейтинге не влияет на сбор и показ статистики ресурса.
title	да	Название сайта, будет выводиться на страницах Рейтинг Mail.ru и в заголовке страниц статистики по ресурсу. В названии должно быть не более 60 символов. Разрешены русские и латинские буквы нижнего и верхнего регистров, цифры, пробел и символы _ + / = & ! @ * : % . , ? ; ~ # “ ‘ ( ) [ ] { } -
url	да	Адрес (URL), по которому расположен Ваш ресурс. Адрес должен начинаться с http:// или https://, не превышать 100 символов в длину и не должен содержать символа @ в имени домена. Мы поддерживаем кириллические домены в адресе, Вам не нужно вводить их в Punycode.

Ответ

HTTP GET

{   
    "error" : STR,
    "error_code" : STR,
    "id" : STR,
    "result" : STR
}

Описание полей

Имя	Описание
error	Описание ошибки. Отсутствует если ошибки не было.
error_code	Код ошибки. Отсутствует если ошибки не было.
id	Номер нового счетчика (см. параметр &id). Отсутствует если произошла ошибка.
result	Имя действия которое произошло, для /json/add это `"result":"created"`.

Описание кодов ошибки (error_code)

Код	Описание
NOT_AGREED	Не установлена галочка согласия с лицензионным соглашением и политикой конфиденциальности.
NO_TITLE	Не указано название сайта.
BAD_TITLE	Название сайта не удовлетворяет требованиям. Не допускается слишком много заглавных букв.
BAD_URL	Урл не соответствует ограничениям.
NO_EMAIL	Не указан емейл.
BAD_EMAIL	Емейл не соответствует ограничениям.
NO_PWD	Не указан пароль.
BAD_PWD	Пароль не соответствует ограничениям.
BAD_LENGTH_PWD	Пароль не соответствует ограничениям по длине.
PWD_MISMATCH	Пароль и повтор пароля не совпадают (если применимо).
BAD_CAPTCHA	Не правильно угадана капча (если применимо).
NO_CATEGORY	Не указана категория сайта (если применимо).
WRONG_DOMAIN	Домен в урле не соответствует ограничениям.
1LEVEL_DOMAIN	Домен в урле является доменом первого уровня.
ALREADY_EXISTS	Сайт с таким урлом уже существует или имеется один сайт для указанного домена. См. параметр ignore_url_warn
SITE_EXISTS	Существует более одного сайта для указанного домена. См. параметр ignore_url_warn
DENIED	В регистрации счетчика отказано. Для регистрации счетчика обратитесь в службу поддержки через форму на сайте

Список категорий рейтинга

URL: https://top.mail.ru/json/categories

Ответ содержит объект categories с массивом категорий, которые в свою очередь, имеют подкатегории.

Ответ

HTTP GET

{
    "categories" : [
    {
        "id" : STR,
        "number" : NUM,
        "name" : STR,
        "childs" : [
        {
            "id": STR,
            "name": STR
        },
        ...
        ],
    },
    ...
    ]
}

Описание полей

Имя	Описание
categories[].id	Уникальный идентификатор родительской категории.
categories[].number	Индекс категории.
categories[].name	Имя категории.
categories[].childs[].id	Уникальный идентификатор дочерней категории.
categories[].childs[].name	Имя дочерней категории.

Аутентификация

URL: https://top.mail.ru/json/login

Параметр	Обязательно	Описание
session	нет	Сессия, к которой привязывается доступ после успешной аутентификации. При отсутствии создается новый.
id	да	id счетчика
password	да	Пароль к счетчику.
action	да	Управление ответом: при action=redirect при корректной аутентификации редиректит на статистику счетчика, полезно для использования вместе с веб формой; при action=json все ответы в json

Ответ содержит json объект, в utf-8. Наличии error показывает, что произошла ошибка. В случае успешной регистрации в action=json ответе будет "logged":"yes".

Для аутентификации обязательны id,password.

Ответ

HTTP GET

{   
    "error" : STR,
    "wrong" : STR,
    "id" : NUM,
    "session" : STR,
    "logged" : STR
}

Описание полей

Имя	Описание
error	Описание ошибки. Отсутствует если ошибки не было.
wrong	Указание на место ошибки, к примеру, если указан неправильный &id - `"wrong":"id"`. Отсутствует если ошибки не было.
id	Уникальный идентификатор счетчика. Отсутствует если произошла ошибка.
session	Уникальный идентификатор сессии.
logged	“yes” - в случае успешной аутентификации, в другом случае отсутствует.

Редактирование информации

URL: https://top.mail.ru/json/edit

Параметр	Обязательно	Описание
url	нет	Адрес (URL), по которому расположен Ваш ресурс. Адрес должен начинаться с http:// или https://, не превышать 100 символов в длину и не должен содержать символа @ в имени домена. Мы поддерживаем кириллические домены в адресе, Вам не нужно вводить их в Punycode.
title	нет	Название сайта, будет выводиться на страницах Рейтинг Mail.ru и в заголовке страниц статистики по ресурсу.В названии должно быть не более 60 символов. Разрешены русские и латинские буквы нижнего и верхнего регистров, цифры, пробел и символы _ + / = & ! @ * : % . , ? ; ~ # “ ’ ( ) [ ] { } -
rating	нет	Участие в рейтинге: 0 (нет) или 1 (да). Участие в рейтинге не влияет на сбор и показ статистики ресурса.
password или session	да	Пароль или сессия для авторизации
id	да	ID счетчика
email	нет	Адрес электронной почты, по которому Вам будет выслано подтверждение регистрации счётчика, его ID. Если Вы забудете свой пароль, то сервер сможет выслать Вам его по этому адресу. Также в случае значительной реорганизации Рейтинга Mail.Ru по этому адресу Вам может быть послано уведомление. Этот адрес не будет показываться на общедоступных страницах Рейтинга Mail.Ru.
category	нет	Опционально, требуется в случае участия в рейтинге (rating=1). Для участия в рейтинге выберите наиболее подходящую для Вашего ресурса категорию Рейтинга Mail.Ru. Правильный выбор категории обеспечит Вам наибольший приток целевой аудитории со страниц Рейтинга Mail.Ru. А также поможет сравнить популярность своего ресурса с популярностью ресурсов конкурентов

Все параметры кроме id и password, опциональные.

Ответ

HTTP GET

{   
    "result" : STR,
    "error" : STR,
    "error_code" : STR,
    "message" : STR,
    "message_code" : STR
}

Описание полей

Имя	Описание
error	Описание ошибки. Отсутствует если ошибки не было.
error_code	Код ошибки. Отсутствует если ошибки не было.
result	Имя действия которое произошло, для /json/edit это `"result":"edited"`. Может отсутствовать.
message	Дополнительная информации о редактирование. Может отсутствовать.
message_code	Код информации о редактировние. Может отсутствовать.

Описание кодов ошибки (error_code)

Код	Описание
ID_NOT_FOUND	Счетчик с указанным id не найден.
URL_NOT_FOUND	Счетчик с указанным url не найден.
WRONG_PWD	Некорректный пароль счетчика.
BAD_TITLE	Название сайта не удовлетворяет требованиям. Не допускается слишком много заглавных букв.
BAD_URL	Урл не соответствует ограничениям.
BAD_EMAIL	Емейл не соответствует ограничениям.
BAD_CAPTCHA	Не правильно угадана капча (если применимо).
NO_CATEGORY	Не указана категория сайта (если применимо).
WRONG_DOMAIN	Домен в урле не соответствует ограничениям.
1LEVEL_DOMAIN	Домен в урле является доменом первого уровня.
ALREADY_EXISTS	Сайт с таким урлом уже существует.
DENIED	В редактировании данных счетчика отказано. Обратитесь в службу поддержки через форму на сайте

Описание кодов информации (message_code)

Код	Описание
CHANGED	Изменения внесены.
DOMAIN_UPDATED	Домен сайта изменен.
NO_CHANGES	Нет изменений.

Код счетчика

URL: https://top.mail.ru/json/code

Параметр	Обязательно	Описание
id	да	ID счетчика
mode		Вид логотипа: nologo (без логотипа, только код), double (код и логотип)
type_8		Номер картинки или “wot”

В ответе будет 2 объекта, logo и code, с кодом логотипа и кода счетчика для вставки.

Ответ

HTTP GET

{
    "error" : STR,
    "code" : STR,
    "logo" : STR
}

Описание полей

Имя	Описание
error	Описание ошибки. Отсутствует если ошибки не было.
code	Javascript код счетчика. Отсутствует если произошла ошибка.
logo	html код логотипа или `null` если &mode=nologo. Отсутствует если произошла ошибка.