Top.Mail.Ru
API проверкиРуководство по использованию

Взаимодействие через POST-запросы

Адрес для запросов:

Добавление текста на проверку уникальности и получение уникального идентификатора текста (uid)

Входные параметры:

  • text - проверяемый текст на уникальность от 100 до 150000 символов (обязательный);
  • userkey - ваш персональный секретный ключ (обязательный);
  • exceptdomain - домены, которые вы хотите исключить из проверки. Домены разделяются пробелами или запятыми (необязательный);
  • excepturl - ссылки, которые вы хотите исключить из проверки. Ссылки разделяются пробелами или запятыми (необязательный);
  • visible - доступность результатов проверки другим пользователям. По-умолчанию - результаты проверки (https://text.ru/antiplagiat/{your_text_uid}) доступны только вашему аккаунту. Если вы хотите, чтобы результаты проверок были открыты, необходимо передать значение vis_on (необязательный);
  • copying - если вы не хотите, чтобы формировалась ссылка с визуальным оформлением результатов проверки https://text.ru/antiplagiat/{your_text_uid}, то необходимо передать значение noadd (необязательный);
  • callback - ваш URL (ссылка), на которую мы отправим POST-запрос с результатами проверки сразу же после её окончания. Подробности указаны ниже (необязательный).

Выходные параметры:

Если текст успешно добавился, возвращается один параметр:

  • text_uid - уникальный идентификатор текста. Используется при последующем получении результатов проверки.

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

  • error_code - код ошибки;
  • error_desc - описание ошибки.
$body = [
    'userkey' => '<USERKEY>',
    // Проверяемый текст
    'text' => '<TEXT>',
    // Ссылка, на которую нужно отправить результат проверки
    'callback' => 'https://your-site.com/callback',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.text.ru/post');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, \json_encode($body));

$rawResponse = curl_exec($ch);

if (curl_errno($ch)) {
    throw new \Exception('Ошибка curl: ' . curl_error($ch));
}

curl_close($ch);

$response = \json_decode($rawResponse, true);

print_r($response); // ['text_uid' => '63c129651c171']
const axios = require('axios');

const client = axios.create({
    baseURL: 'https://api.text.ru'
});

const body = {
    userkey: '<USERKEY>',
    // Проверяемый текст
    text: '<TEXT>',
    // Ссылка, на которую нужно отправить результат проверки
    callback: 'https://your-site.com/callback'
};

client
    .post('/post', body)
    .then((response) => {
        console.log(response.data);
    })
    .catch((err) => {
        console.error(err);
    })
;
Получение результатов проверки текста

Входные параметры:

  • uid - уникальный идентификатор текста. Берется из метода addText (обязательный);
  • userkey - ваш персональный секретный ключ (обязательный);
  • jsonvisible (необязательный) - параметр позволяет получить более детальную информацию о результатах проверки. Возможные значения:
    detail
    В ответ будут добавлены words и clear_text (см. структуру result_json).
    detail_view
    Параметр является экспериментальным.

    То же, что и detail, но вместо clear_text в корень ответа будут добавлены параметры text_view и words_pos.

    text_view — версия текста с сохраненной структурой и пунктуацией. Соответствует тексту, который отображается в форме на сайте.
    words_pos — список позиций слов в text_view. Номер в списке соответствует номеру слова в words. Каждая позиция представлена парой чисел — начальным и конечным смещением слова в тексте. Отсчет начинается с 0, оба смещения включительны и указаны в символах.

Выходные параметры:

Если текст успешно проверен, возвращаются два параметра:

  • text_unique - уникальность текста в процентах с точностью до 2 знаков после запятой;
  • result_json - дополнительная информация о результатах проверки на уникальность в формате json. Структура json-ответа расшифрована ниже;
  • spell_check - (доступен с опцией jsonvisible) дополнительная информация о результатах проверки на правописание в формате json.
    Структура json-ответа расшифрована ниже;
  • seo_check - (доступен с опцией jsonvisible) дополнительная информация о результатах проверки на SEO-анализ в формате json.
    Структура json-ответа расшифрована ниже.

Если текст ещё не проверился или произошла ошибка при проверке, возвращаются следующие параметры:

  • error_code - код ошибки;
  • error_desc - описание ошибки.
$body = [
    'userkey' => '<USERKEY>',
    'uid' => '<UID>',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.text.ru/post');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, \json_encode($body));

$rawResponse = curl_exec($ch);

if (curl_errno($ch)) {
    throw new \Exception('Ошибка curl: ' . curl_error($ch));
}

curl_close($ch);

$response = \json_decode($rawResponse, true);

print_r($response);
const axios = require('axios');

const client = axios.create({
    baseURL: 'https://api.text.ru'
});

const body = {
    userkey: '<USERKEY>',
    uid: '<UID>'
};

client
    .post('/post', body)
    .then((response) => {
        console.log(response.data);
    })
    .catch((err) => {
        console.error(err);
    })
;
Структура JSON-ответа параметра result_json
  • date_check - дата окончания проверки текста на сервере;
  • unique - уникальность текста в процентах, с точностью до 2 знаков после запятой;
  • urls - массив ссылок, для которых известно:
    • url - текст ссылки;
    • plagiat - процент совпадения текста по ссылке;
    • words - (доступен с опцией jsonvisible) номера позиций "совпадающих" слов в тексте (clear_text - см. ниже). Нумерация начинается с 0.
  • clear_text - (доступен с опцией jsonvisible) очищенный от служебных символов и знаков препинания ваш текст, состоящий из слов, разделенных через пробел.

Посмотреть пример JSON-ответа

{
"date_check":"29.03.2017 14:46:49",
"unique":0,
"clear_text":"Wikipedia was launched оn January 15 2001 by Jimmy Wаles and Larry Sanger 11 Sanger coined its name 12 13 a portmanteau of wiki notes 4 and encyclopedia Therе was only the English language version initially but it quickly developed similar versions in other languages which differ in content and in editing practices With 5 466 824 articles notes 5 the English Wikipedia is the largest of the more than 290 Wikipedia encyclopedias Overall Wikipedia consists of more than 40 million articles in more than 250 different languages 15 and as of February 2014 it had 18 billion page views and nearly 500 million unique visitors each month",
"mixed_words":"4 10 29",
"urls":[
{
"url":"https://en.wikipedia.org/wiki/Wikipedia",
"plagiat":100,
"words":"0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107"
}
]
}
Структура JSON-ответа параметра spell_check

Проверка текста на правописание работает параллельно и независимо с проверкой на уникальность. К примеру, текст может провериться на правописание раньше, чем на уникальность. В этом случае результаты по правописанию уже будут доступны в ответе, в то время как для получения результатов проверки на уникальность понадобятся дополнительные запросы.

Проверка на правописание гарантированно не может найти все ошибки. Мы постоянно работаем над улучшением алгоритма. С примерами его работы вы можете ознакомиться в бесплатной версии через форму на сайте.

Если проверка на правописание ещё не завершена, то параметр spell_check будет равен пустой строке.
По завершению проверки параметр spell_check примет json-представление массива, элементы которого состоят из:

  • error_type - тип ошибки ('Орфография', 'Пунктуация' и т.д.);
  • reason - детальное описание ошибки;
  • error_text - текст фрагмента, в котором обнаружилась ошибка;
  • replacements - массив с предлагаемыми вариантами замены (может быть пустым);
  • start - начальная позиция фрагмента, в котором найдена ошибка;
  • end - конечная позиция фрагмента, в котором найдена ошибка.

Посмотреть пример JSON-ответа

[
{
"error_type":"Spelling",
"replacements":[
"milk",
"mild",
],
"reason":"Spelling error found",
"error_text":"mildd",
"start":255,
"end":272
},
{
"error_type":"Capital letters",
"replacements":[
"Hello"
],
"reason":"This sentence doesn't start with a capital letter",
"error_text":"hello",
"start":276,
"end":287
}
]
Структура JSON-ответа параметра seo_check

Проверка текста на SEO-анализ работает параллельно, как и проверка текста на правописание. Текст на SEO-анализ может провериться раньше, чем на уникальность. В этом случае для получения результатов проверки на уникальность понадобятся дополнительные запросы до готовности ответа от API.

Если проверка на SEO-анализ ещё не завершена, то параметр seo_check будет равен пустой строке.
По завершению проверки параметр seo_check примет следующее json-представление:

  • count_chars_with_space - количество символов с пробелами;
  • count_chars_without_space - количество символов без пробелов;
  • count_words - количество слов в тексте;
  • water_percent - процент воды;
  • spam_percent - процент заспамленности;
  • mixed_words - номера позиций слов в тексте, у которых присутствуют символы из разных алфавитов и имеющих схожее написание. Нумерация начинается с 0.
  • list_keys - список ключей в тексте, отсортированных по частоте встречаемости:
    • key_title - текст ключа;
    • count - количество вхождений ключа в текст во всех формах.
  • list_keys_group - список ключей в тексте, отсортированных по числу значимых слов и сгруппированных по составу слов:
    • key_title - текст ключа;
    • count - количество вхождений ключа в текст во всех формах.
    • sub_keys - список подключей:
      • key_title - текст подключа;
      • count - количество вхождений подключа в текст во всех формах.

Посмотреть пример JSON-ответа

{
"count_chars_with_space":620,
"count_chars_without_space":545,
"count_words":77,
"water_percent":11,
"spam_percent":38,
"mixed_words":[8,11,47],
"list_keys":[
{
"key_title":"check",
"count":6
},
{
"key_title":"text",
"count":5
},
{
"key_title":"antiplagiat",
"count":3
},
{
"key_title":"check text",
"count":3
}
],
"list_keys_group":[
{
"key_title":"check text",
"count":3,
"sub_keys":[
{
"key_title":"check",
"count":6
},
{
"key_title":"text",
"count":5
}
]
},
{
"key_title":"antiplagiat",
"count":3,
"sub_keys":[]
},
{
"key_title":"check",
"count":6,
"sub_keys":[]
},
{
"key_title":"text",
"count":5,
"sub_keys":[]
},
]
}
Callback получение результатов проверки

Проверка текста на уникальность занимает определенное (заранее неизвестное) время. Если вы хотите получить уведомление о факте завершения (вместе с результатами) проверки вашего текста, то вы можете при добавлении текста на API в параметре callback указать адрес вашего скрипта, который обработает наш POST-запрос с результатами проверки текста.

  • Чтобы убедиться, что вы успешно получили результат, на вашей странице должно отобразиться ok и ничего более (echo "ok";).
  • Максимальное число попыток отправки результатов проверки - 3.
  • В callback POST-запросе отправляются 4 параметра: uid, text_unique, json_result, spell_check. Структура json-ответа такая же, что и при ручном запросе результата (без атрибутов clear_text и words).
  • Если проверка на правописание закончится позже проверки на уникальность, то будет отправлено 2 callback-запроса по мере окончания проверок (во время первого запроса параметр spell_check будет равен пустой строке).
  • Получить результаты проверки на уникальность также можно и вручную.
Перечень возможных ошибок при проверке на уникальность
Код ошибки Описание ошибки Код ошибки Описание ошибки
110 Отсутствует проверяемый текст 146 Доступ ограничен
111 Проверяемый текст пустой 150 Шинглов не найдено. Возможно текст слишком короткий
112 Проверяемый текст слишком короткий 151 Ошибка сервера. Попробуйте позднее
113 Проверяемый текст слишком большой. Разбейте текст на несколько частей 160 Отсутствует проверяемый uid текста
120 Отсутствует пользовательский ключ 161 Uid текста пустой
121 Пользовательский ключ пустой 170 Отсутствует пользовательский ключ
140 Ошибка доступа на сервере. Попробуйте позднее 171 Пользовательский ключ пустой
141 Несуществующий пользовательский ключ 180 Текущая пара ключ-uid отсутствует в базе
142 Нехватка символов на балансе 181 Текст ещё не проверен
143 Ошибка при передаче параметров на сервере. Попробуйте позднее 182 Текст проверен с ошибками. Деньги будут возвращены.
144 Ошибка сервера. Попробуйте позднее 183 Ошибка сервера. Попробуйте позднее
145 Ошибка сервера. Попробуйте позднее 429 Исчерпан текущий лимит запросов. Попробуйте позже. *

* Разрешено добавлять не более 3 млн. символов в час на проверку. При превышении данного лимита будет возвращена ошибка с кодом 429. Лимит восстанавливается в начале каждого часа.
Получение остатка символов на балансе

Адрес для запроса: http://api.text.ru/account

POST-параметры запроса:

  • method - 'get_packages_info' (обязательный);
  • userkey - ваш персональный секретный ключ (обязательный);

Результат запроса (в формате json):

  • size - суммарный остаток символов по всем пакетам;

Внимание! В целях безопасности, чтобы ваш IP-адрес не заблокировался, не рекомендуется обращаться к данному методу чаще 2 раз в минуту.


$body = [
    'userkey' => '<USERKEY>',
    'method' => 'get_packages_info',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.text.ru/account');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, \json_encode($body));

$rawResponse = curl_exec($ch);

if (curl_errno($ch)) {
    throw new \Exception('Ошибка curl: ' . curl_error($ch));
}

curl_close($ch);

$response = \json_decode($rawResponse, true);

print_r($response); // ['size' => 1000]
const axios = require('axios');

const client = axios.create({
    baseURL: 'https://api.text.ru'
});

const body = {
    userkey: '<USERKEY>',
    method: 'get_packages_info'
};

client
    .post('/account', body)
    .then((response) => {
        console.log(response.data);
    })
    .catch((err) => {
        console.error(err);
    })
;