API, разрабатываемый совместно с EnduranceRobots.com, позволяет перефразировать предложения и отдельные слова, а также определять пропущенные члены предложения. Основные функции API реализованы для двух языков (русский, английский), некоторые функции пока работают только для одного языка.
В настоящий момент доступна альфа-версия API (лицензия MIT), и мы приглашаем к тестированию разработчиков, исследователей, лингвистов, веб-мастеров, SEO-специалистов, копирайтеров, а также всех, кто заинтересован в использовании пообного сервиса.
Использование API возможно программным способом (это требует несложной регистрациии на ParaPhraser.ru) либо через специальную Web-форму (без регистрации).
В ближайшем будущем планируется внедрение других функций, таких как подбор гипонимов и гиперонимов, анализ тональности фразы, тематическая классификация фразы и перефразирование текста.
Мы рады отзывам, комментариям и пожеланиям по работе API и внедрению новых функций и любой обратной связи на api@paraphraser.ru.
Выполнять запросы к API можно только имея учетную запись на ParaPhraser.ru. Гостевые запросы возможны через Web-форму.
После регистрации каждый пользователь получает уникальный токен, который нужно использовать для обращения к методам API. Посмотреть свой токен можно в личном кабинете. При необходимости, токен может быть получен программным способом в результате обращения по адресу http://paraphraser.ru/token и передачи серверу пары логин/пароль.
http://paraphraser.ru/token?login=user&password=12345678
{ 'login': 'user', 'password': '12345678' }
При обращении к API передача токена серверу осуществляется непосредственно в HTTP-запросе:
?token=9944b09199c62bcf3048ad846dd0e4bbdfc6ee4b&...
{ 'token': '9944b09199c62bcf3048ad846dd0e4bbdfc6ee4b', ... }
Запрос к API может быть выполнен методом GET или POST. Метод GET используется для передачи отдельных слов или коротких фраз, в то время как POST можно использовать для обработки небольших текстов.
При передаче параметров методом POST необходимо использовать формат JSON.
Запросы на обработку текста принимаются по адресу http://paraphraser.ru/api.
http://paraphraser.ru/api? token=9944b09199c62bcf3048ad846dd0e4bbdfc6ee4b& c=vector&query=ищите женщину&top=3&lang=ru&format=json
{ 'token': '9944b09199c62bcf3048ad846dd0e4bbdfc6ee4b', 'c': 'vector', 'query': 'ищите женщину', 'top': 3, 'lang': 'ru', 'format': 'json', }
В разделе Примеры использования приведен пример кода рабочего приложения.
Возвращает список слов или фраз, близких по смыслу исходному слову или фразе, на основе векторной семантической модели.
Функция принимает на вход фразу или слово, осуществляет морфологический разбор, снимает неоднозначность на уровне частей речи и возвращает список фраз или слов, семантически близких к исходной фразе или слову, на основе технологии Word2Vec. Также возвращаются начальная форма и часть речи исходного слова в формате Universal POS tags (в случае фраз эта информация возвращается для каждого слова внутри исходной фразы).
В случае, если на вход подается слово, которое является неоднозначным, ответ выдается для каждой возможной части речи этого слова отдельно. Кроме того, выдаваемые слова ставятся в ту же форму, что и слова в исходном запросе.
В случае, если на вход подается слово, отсутствующее в векторной модели, функция возвращает только начальную форму и часть речи. Некоторые служебные части речи (артикли, вспомогательные глаголы), а также знаки пунктуации и прочие символы обрабатываются аналогичным образом – функция возвращает только начальную форму и часть речи.
Функция является базовой для данного API.
Параметр | Описание |
c | vector |
query | Искомое слово или фраза (строка, длина не более 90 символов или 4 слов) |
top | Количество возвращаемых схожих по смыслу слов или фраз (число от 0 до 30) |
lang | Язык (принимает значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "response": { "1": { "original": "ищите женщину", "vector": [ "отыскивайте девушку", "выискивайте девушку", "отыскивайте мужчину", ], "lemma": "искать женщина", "pos": "VERB NOUN" } }, "code": 0, "msg": "OK" }
{ "response": { "1": { "original": "striped kitten", "vector": [ "blotched cat", "blotched puppy", "white-spotted puppy" ], "pos": "ADJ NOUN", "lemma": "striped kitten" } }, "code": 0, "msg": "OK" }
Набор входных параметров данной функции может быть расширен для получения коэффициентов семантической близости и словоформ.
Возвращает для каждой фразы или слова в выдаваемом векторе близких слов коэффициент семантической близости между выдаваемым и исходным словом или фразой.
Функция расширяет вектор похожих слов (фраз), снабжая его коэффициентами семантического сходства (по отношению к исходному слову или фразе). Коэффициенты могут принимать значения от 0 до 1.
В дополнение к базовым параметрам функции получения похожих слов (фраз) следует указывать следующие параметры:
Параметр | Описание |
scores | Возвращать коэффициенты семантической близости (число, должно принимать значение «1») |
{ "response": { "1": { "original": "ищите женщину", "vector": [ [ "отыскивайте девушку", 0.7048 ], [ "выискивайте девушку", 0.7011 ], [ "отыскивайте мужчину", 0.6609 ] ], "lemma": "искать женщина", "pos": "VERB NOUN" } }, "code": 0, "msg": "OK" }
{ "response": { "1": { "original": "striped kitten", "pos": "ADJ NOUN", "lemma": "striped kitten", "vector": [ [ "blotched cat", 0.7723 ], [ "blotched puppy", 0.7634 ], [ "white-spotted puppy", 0.7629 ] ] } }, "code": 0, "msg": "OK" }
Данная функция может вызываться совместно с функцией словоформ.
Возвращает все словоформы слов из вектора для заданного слова (фразы).
Функция расширяет вектор похожих слов (фраз), возвращая все возможные формы исходного слова (или слов внутри исходной фразы), а также все возможные формы слов для результирующего вектора слов/фраз.
В дополнение к базовым параметрам функции получения похожих слов (фраз) следует указывать следующие параметры:
Параметр | Описание |
forms | Возвращать все словоформы (число, должно принимать значение «1») |
{ "code": 0, "msg": "OK", "response": { "1": { "pos": "VERB NOUN", "lemma": "искать женщина", "forms_query": { "ищите": [ "ищете", "искало", "искали", "ищешь", "ищем", "ищут", "искала", "ищу", "ищет", "искал" ], "женщину": [ "женщине", "женщинами", "женщины", "женщинах", "женщинам", "женщиной", "женщина", "женщин", "женщину" ] }, "original": "ищите женщину", "forms": [ { "отыскивайте": [ "отыскивает", "отыскивала", ... ], "девушку": [ "девушка", "девушки", ... ] }, { "выискивайте": [ "выискивает", "выискиваю", ... ], "девушку": [ "девушка", "девушки", ... ] }, { "отыскивайте": [ "отыскивает", "отыскивала", ... ], "мужчину": [ "мужчина", "мужчиной", ... ] } ], "vector": [ "отыскивайте девушку", "выискивайте девушку", "отыскивайте мужчину", ] } } }
{ "code": 0, "msg": "OK", "response": { "1": { "forms": [ { "blotched": [ "blotched" ], "cat": [ "cats", "cat" ] }, { "blotched": [ "blotched" ], "puppy": [ "puppies", "puppy" ] }, { "white-spotted": [ "white-spotted" ], "puppy": [ "puppies", "puppy" ] } ], "forms_query": { "striped": [ "striped" ], "kitten": [ "kittens", "kitten" ] }, "vector": [ "blotched cat", "blotched puppy", "white-spotted puppy" ], "pos": "ADJ NOUN", "original": "striped kitten", "lemma": "striped kitten" } } }
Данная функция может вызываться совместно с функцией коэффициентов семантической близости.
Возвращает синонимы к заданному слову (фразе) на основе Yet Another RussNet.
Функция возвращает синонимы к исходным слову или фразе на основе синсетов из тезауруса Yet Another RussNet. В случае фразы синонимы подбираются отдельно для каждого слова внутри фразы (кроме служебных частей речи), а затем комбинируются в составе фразы.
Кроме того, для каждого слова внутри фразы функция возвращает начальную форму и часть речи в формате Universal POS tags. Для некоторых служебных частей речи (артикли, вспомогательные глаголы), а также знаков пунктуации и прочих символов синонимы не подбираются – возвращаются только начальная форма и часть речи.
Параметр | Описание |
c | syns |
query | Искомое слово или фраза (строка, длина не более 90 символов или 4 слов) |
top | Максимально допустимое количество возможных комбинаций (число от 1 до 30) |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "code": 0, "response": { "1": { "syns": [ "полосатый котишка", "полосатый морской котик", "полосатый кошечка" ], "original": "полосатый котик", "lemma": "полосатый котик", "pos": "ADJ NOUN" } }, "msg": "OK" }
{ "code": 0, "response": { "1": { "original": "striped kitten", "lemma": "striped kitten", "pos": "ADJ NOUN", "syns": [ "stripy pussycat", "stripy kitty-cat", "stripy kitty" ] } }, "msg": "OK" }
Набор входных параметров данной функции может быть расширен для получения коэффициентов семантической близости и словоформ.
Возвращает гипонимы и гиперонимы для слов из запроса.
Функция возвращает более частные (гипонимы) и более общие (гиперонимы) понятия для слов из запроса (кроме служебных частей речи) на основе данных Викисловаря для русского языка и WordNet _ для английского. Гипонимы и гиперонимы ставятся в ту же форму, что и исходное слово. В случае запроса-фразы функция возвращает гипонимы и гиперонимы к каждому слову из фразы отдельно (кроме служебных частей речи).
Параметр | Описание |
c | hyp |
query | Искомое слово или фраза (строка, длина не более 90 символов) |
top | Максимально допустимое количество гипонимов и гиперонимов (число от 1 до 30) |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "code": 0, "response": { "1": { "original": "ищите женщину", "lemma": "искать женщина", "pos": "VERB NOUN", "hyponym": { "ищите": [ "отыскивайте", "приискивайте", "разыскивайте", ], "женщину": [ "старуху", "мать", "барышню" ] }, "hypernym": { "ищите": [], "женщину": [ "человека", "самку", "любовницу" ] }, } }, "msg": "OK" }
{ "msg": "OK", "code": 0, "response": { "1": { "pos": "ADJ NOUN", "lemma": "good job", "hyponym": { "job": [ "grade", "merchandising", "preoccupancy" ], "good": [] }, "hypernym": { "job": [ "air medal", "emergency room", "order isoetales" ], "good": [] }, "original": "good job" } } }
Возвращает однокоренные слова для слов из запроса.
Функция возвращает однокоренные слова для слов из запроса (кроме служебных частей речи) на основе словаря Тихонова для русского языка. В случае запроса-фразы функция возвращает однокоренные слова для каждого слова из фразы отдельно (кроме служебных частей речи).
Параметр | Описание |
c | root |
query | Искомое слово или фраза (строка, длина не более 90 символов) |
top | Максимально допустимое количество однокоренных слов (число от 1 до 30) |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "time": 0.0329, "code": 0, "msg": "OK", "response": { "1": { "pos": "VERB NOUN", "root": { "ищите": [ "искательство", "сыщик", "ищейка" ], "женщину": [ "женственность", "женский", "женофоб" ] }, "lemma": "искать женщина", "original": "ищите женщину" } } }
Возвращает коэффициент сходства между двумя словами или фразами.
Функция возвращает коэффициент сходства между двумя словами или фразами, который может быть рассчитан одним из трех способов на выбор пользователя: на основе семантической векторной модели, на основе отношений синонимии или же на основе морфологического родства слов в составе фраз.
Параметр | Описание |
c | sim |
query | Два слова или фразы, разделенные знаком ";" (строка, длина не более 90 символов) |
type | Способ расчета возвращаемого семантического коэффициента (возможные значения: "vector", "syn", "root") |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "code": 0, "response": { "1": { "original_1": "стоимость", "original_2": "цена", "lemma_1": "стоимость", "lemma_2": "цена", "pos_1": "NOUN", "pos_2": "NOUN", "sim": { "score": 0.6959 }, } }, "msg": "OK" }
{ "code": 0, "msg": "OK", "response": { "1": { "lemma_2": "dog", "pos_2": "NOUN", "lemma_1": "cat", "sim": { "score": 0.7551 }, "original_2": "dog", "original_1": "cat", "pos_1": "NOUN" } } }
Все три способа расчета коэффициента сходства двух фраз реализованы только для русского языка. Для английского языка возможен расчет коэффициента на основе векторной модели или отношений синонимии. В случае выбора опции морфологического родства для английского языка коэффициент рассчитывается на основе отношений синонимии.
Возвращает значение, указывающее на отсутствие в предложении подлежащего или сказуемого.
Функция принимает на вход предложение и проверяет, содержит ли оно и субъект (подлежащее), и предикат (сказуемое).
Параметр | Описание |
c | misent |
query | Искомое слово или фраза (строка, длина не более 90 символов) |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "msg": "OK", "code": 0, "response": { "missing": [ "subject" ], "phrase": [ { "pos": "VERB", "word": "ищите", "lemma": "искать" }, { "pos": "NOUN", "word": "женщину", "lemma": "женщина" } ] } }
{ "msg": "OK", "code": 0, "response": { "phrase": [ { "word": "striped", "lemma": "striped", "pos": "ADJ" }, { "word": "kitten", "lemma": "kitten", "pos": "NOUN" } ], "missing": [ "predicate" ] } }
Возвращает центроид заданных слов или фраз.
Функция возвращает центроид (в терминах векторной модели) заданных слов или фраз, то есть слово/фразу, которая является наиболее общей для тематики данных слов/фраз. Все слова, которые подаются на вход функции, должны быть лемматизированы и снабжены тегом части речи в формате Universal POS tags. Например, вот так:
Параметр | Описание |
c | centroid |
query | Произвольное количество слов или фраз (лемматизированных, с тегом части речи), разделенных знаком ";" (строка, длина не более 90 символов) |
lang | Язык (может принимать значения «ru» или «en») |
format | Формат вывода (должен принимать значение «json») |
{ "code": 0, "response": { "phrases": [ "собака_NOUN", "мышь_NOUN", "животное_NOUN" ], "centroid": "животное_NOUN" }, "msg": "OK" }
{ "code": 0, "response": { "centroid": "car_NOUN", "phrases": [ "car_NOUN", "plane_NOUN", "bus_NOUN" ] }, "msg": "OK" }
Возвращает тематику запроса исходя из классификации Википедии.
Функция классифицирует тематику запроса на основе категорий Википедии.
Параметр | Описание |
c | wikitopic |
query | Искомое слово или фраза (строка, длина не более 90 символов) |
format | Формат вывода (должен принимать значение «json») |
{ "code": 0, "response": { "topics": [ "Фильмы 1982 года", "Фильмы Аллы Суриковой", "Телефильмы СССР 1982 года", "Фильмы студии «Мосфильм»", "Кинокомедии СССР", "Кинокомедии 1982 года", "Детективные фильмы СССР", "Фильмы о юристах", "Экранизации произведений Робера Тома", ] }, "msg": "OK" }
Возвращает список ключевых слов и фраз для текста.
Функция возвращает список ключевых слов для заданного текста. Список ключевых слов может быть дополнен семантически близкими словами. Можно выбирать части речи возвращаемых слов. Кроме того, функция может возвращать ключевые фразы.
Функция поддерживает выделение из текста основных тематик (кластеры ключевых слов) и их веса при программном обращении к ней (не через Web-форму).
Выделение тематик работает только при расширении ключевых слов синонимами.
Данная функция может быть вызвана только в POST-запросе.
Параметр | Описание |
c | keywords |
query | Исходный текст (строка, длина не более 2000 символов) |
top | Максимально допустимое количество ключевых слов (число от 1 до 30) |
pos | Части речи возвращаемых ключевых слов, перечисленные через запятую |
expand | Расширить список ключевых слов синонимами (число, должно принимать значение «1» или «0») |
mwe | Возвращать словосочетания (число, должно принимать значение «0» или «1») |
forms | Возвращать все словоформы (число, должно принимать значение «0» или «1») |
clusters | Возвращать тематики по ключевым словам (имеет смысл только при expand=1) (число, должно принимать значение «0» или «1») |
stopwords | Стоп-слова в начальной форме, перечисленные через ";" |
lang | Язык (должен принимать значение «ru») |
format | Формат вывода (должен принимать значение «json») |
Набор входных параметров данной функции может быть расширен для получения словоформ всех ключевых слов.
Пример POST-запроса с параметром c=syns на языке Python 3.x с использованием библиотеки requests:
#!/usr/bin/env python
import json
import requests
# 1. Get your authentication token
# by posting username and password to the server
r = requests.post('http://paraphraser.ru/token/',
data={'login': 'user', 'password': '12345678'})
token = r.json().get('token', '')
# 2. Make a request using the obtained token
payload = {'c': 'syns',
'query': 'кот ест рыбку',
'top': 3,
'scores': 0,
'forms': 0,
'format': 'json',
'lang': 'ru',
'token': token}
r = requests.post('http://paraphraser.ru/api/',
data=payload)
result = r.json()
if result['code'] == 0:
response = result['response']
for item in response:
for value in response[item]['syns']:
print(value)
else:
print('Error:', result['msg'])
Результат выполнения (некоторые слова могут различаться в зависимости от используемой модели):
кошак кушает солнышко котэ кушает солнышко кошак кушает рыбёшку
Пример GET-запроса с параметром c=vector на Python 3.5+ без использования сторонних библиотек:
#!/usr/bin/env python
import json
from urllib.request import urlopen, HTTPError
from urllib.parse import urlencode, quote_plus
def token(login, password):
payload = {'login': login, 'password': password}
params = urlencode(payload, quote_via=quote_plus)
url = 'http://paraphraser.ru/token?{0}'.format(params)
try:
return json.loads(urlopen(url).read().decode('utf-8'))['token']
except HTTPError:
return None
def send(payload):
params = urlencode(payload, quote_via=quote_plus)
url = 'http://paraphraser.ru/api?{0}'.format(params)
try:
return json.loads(urlopen(url).read().decode('utf-8'))
except Exception as err:
return json.loads(err.read().decode('utf-8'))
token = token('user', '12345678')
if token is not None:
result = send({
'c': 'vector',
'query': 'кот ест рыбку',
'top': 4,
'scores': 0,
'forms': 0,
'lang': 'ru',
'token': token
})
if result['code'] == 0:
response = result['response']
for item in response:
for value in response[item]['vector']:
print(value)
else:
print('Ошибка при выполнении запроса:', result['msg'])
else:
print('Неверные имя пользователя или пароль')
Результат выполнения (некоторые слова могут различаться в зависимости от используемой модели):
кошка ест карася котёнок ест карася кошка ест окунька кошка ест рыбёшку
Пример POST-запроса с параметром c=keywords на языке PHP с использованием модуля cURL (токен определен в переменной $token):
$text = 'Врагу не сдается наш гордый Варяг,
пощады никто не желает';
$payload = array(
'c' => 'keywords',
'query' => $text,
'top' => 10,
'pos' => 'NOUN',
'expand' => 0,
'mwe' => 1,
'forms' => 0,
'clusters' => 0,
'lang' => 'ru',
'format' => 'json',
'token' => $token
);
$curl = curl_init('http://paraphraser.ru/api/');
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($curl);
curl_close($curl);
if ($response === false)
die(var_export(curl_getinfo($curl)));
$result = json_decode($response, true);
if ($result['code'] != 0)
die($result['msg']);
$keywords = $result['response']['keywords'];
print_r($keywords);
Результат выполнения (некоторые слова могут различаться в зависимости от используемой модели):
Array ( [0] => варяг [1] => пощада [2] => враг )
Код | Текст ошибки | Описание |
---|---|---|
0 | OK | Корректный запрос |
1 | Message transfer error | Ошибка при передаче данных на сервер |
2 | Query format error | Параметр "query" указан неверно |
3 | Invalid query parameters | Один или более параметров запроса указаны неверно (например, "scores", "forms" и т.д.) |
4 | Unknown query type | Параметр "type" указан неверно. Он должен принимать одно из следующих значений: "vector", "syn", "root" |
5 | Language must be "ru" or "en" | Параметр "lang" указан неверно |
6 | Wrong command | Параметр "command" указан неверно. Он должен принимать одно из следующих значений: "vector", "syns", "misent", "hyp", "sim", "centroid" |
ПО | Ссылка |
---|---|
pymorphy2 | Korobov M.: Morphological Analyzer and Generator for Russian and Ukrainian Languages // Analysis of Images, Social Networks and Texts, pp. 320-332 (2015) |
topia | https://pypi.python.org/pypi/topia.termextract/ |
spaCy | Honnibal, M., Johnson, M.: An Improved Non-monotonic Transition System for Dependency Parsing. In EMNLP 2015, pp. 1373–1378 (2015) |
pattern | De Smedt, T., Daelemans, W.: Pattern for Python. Journal of Machine Learning Research, vol. 13, pp. 2031–2035 (2012) |
gensim | Řehůřek, R., Sojka, P.: Software Framework for Topic Modelling with Large Corpora. Proceedings of the LREC 2010 Workshop on New Challenges for NLP Frameworks, pp. 45-50 (2010) |
SyntaxNet | https://research.googleblog.com/2016/05/announcing-syntaxnet-worlds-most.html |
Модели RusVectores | Kutuzov A., Kuzmenko E.: WebVectors: A Toolkit for Building Web Interfaces for Vector Semantic Models. In: Ignatov D. et al. (eds) Analysis of Images, Social Networks and Texts. AIST 2016. Communications in Computer and Information Science, vol 661. Springer, Cham (2017) |
Yet Another RussNet | Braslavski, P., Ustalov, D., Mukhin, M., Kiselev, Y.: YARN: Spinning-in-Progress. Proceedings of the Eight Global Wordnet Conference. Bucharest, Romania, 2016, pp. 58–65 |
MyStem | https://tech.yandex.ru/mystem/ |