#API

#Структура запроса

Использование API предполагает отправку POST–запросов с набором JSON–параметров по адресу https://neuro-semantic.ru/[адрес запроса], где[адрес запроса]указывается в описании нужного запроса.

#Структура ответа

В качестве ответа на любой запрос по корректному адресу возвращается JSON–структура данных с ответом.

Структура ответа всегда однообразна и содержит следующие атрибуты:

полеописание
statusЧисловой код результата выполнения операции.0в случае отсутствия ошибок, либо код ошибки.
errorКороткое описание ошибки, если она произошла.
dataJSON–структура с данными ответа, если они есть.

#Алгоритм проведения расчета

Анализ текстов с помощью API выполняется в 2 шага:

  1. создание запроса;
  2. получение результатов запроса по идентификатору.

#Пользователь

#Информация о балансе

Возвращает остаток средств на балансе пользователя.

Адрес:/api/user/balance

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.

Структура данных ответа в полеdata:

полеописание
user_balanceБаланс аккаунта пользователя.

#История баланса

Возвращает историю списаний и пополнений баланса пользователя.

Адрес:/api/user/balance/history

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.

Структура данных ответа в полеdata:

полеописание
[...]Массив объектов с историей пополнений и списаний.

Структура объекта в массиве данных истории баланса пользователя:

полеописание
date_completeДата и время операции.
descrОписание типа операции.
valueСумма операции.

#История запросов

Возвращает историю запросов к сервису.

Адрес:/api/history/get

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.

Структура данных ответа в полеdata:

полеописание
[...]Массив с историей запросов пользователя.

Структура объекта в массиве данных истории запросов пользователя:

полеописание
calc_qualityКачество определения.
calc_typeТип расчета.classify— классификация по теме,sentiment— анализ тональности,emcol— анализ эмоционального окраса.
date_completeUTC дата и время окончания расчета запроса в формате “ГГГГ.ММ.ДД ЧЧ:ММ:СС”.
date_createUTC дата и время поступления запроса в формате “ГГГГ.ММ.ДД ЧЧ:ММ:СС”.
request_ipIP–адрес источника запроса.
texts_amountКоличество текстов распознанных для анализа.
texts_processedКоличество проанализированных текстов.
transaction_idУникальный идентификатор запроса.
transaction_priceСтоимость запроса.
transaction_statusСтатус транзакции: 10 — в очереди, 20 — рассчитывается, 30 — рассчитан.

#Расчет

#Получение результата

Получение данных о созданном ранее расчете.

Адрес:/api/transaction/get

Параметры:

полеописание
transaction_idОбязательный. Идентификатор запроса.
secretОбязательный. Секретный ключ пользователя.

Структура данных ответа в полеdata: объект сJSON–структурой данных о транзакции.

#Создание транзакции

Адрес:/api/transaction/create

В случае расчета ММК обязательным параметром при создании транзакции является тема по которой производится классификация. Тема должна быть передана в видеJSON–структуры. Подобное необходимо для сохранения возможности восстановить объект анализа в случае изменения или удаления темы.
Для получения JSON–структур всех тем пользователя можно воспользоваться запросомполучения списка тем.

Параметры:

полеописание
calc_typeОбязательный. Тип расчета:classify— ММК,sentiment— тональность,emcol— эмоциональный окрас,wordfreq— частотность слов
theme_idИдентификатор темы для анализа. Обязателен в случае расчета ММК.
request_dataJSON–структура с даннымитемыили числом словосочетаний для анализа частотности слов.
secretОбязательный. Секретный ключ пользователя.
textsОбязательный. Тексты для анализа.
texts_splitterОпциональный. Символ-разделитель текстов.

Структура данных ответа в полеdata: объект сJSON–структурой данных о транзакции.

#Типы расчета

#Получение данных о типах запросов

Получение списка типов запросов со всеми вариантами их названий и стоимостями.

Адрес:/api/calc_types/get

Входные параметры отсутствуют.

Структура данных ответа в полеdataсодержитJSON–объект с данными о типах запросов.

#Сущности

#Обновление сущностей темы

Позволяет добавить, обновить или удалить сущности выбранной темы.

Адрес:/api/entities/update

Параметры:

полеописание
entitiesОпциональный. Массив сJSON–объектами сущностей.
secretОбязательный. Секретный ключ пользователя.
theme_idОбязательный. Идентификатор темы, которой принадлежат редактируемые сущности.

Структура данных ответа в полеdataотсутствует.

#Темы

#Создание

Адрес:/api/themes/create

Параметры:

полеописание
descrОпциональный. Описание сущности.
directory_idОбязательный. Идентификатор каталога, в котором находится тема.idкорневого каталога равен 0.
entitiesОпциональный. Массив с JSON–структурами сущностей.
secretОбязательный. Секретный ключ пользователя.
theme_idОбязательный. Идентификатор темы для редактирования.
titleОбязательный. Название сущности.

Структура данных ответа в полеdataсодержитJSON–объект с данными темы.

#Редактирование

Позволяет отредактировать название и описание темы, а также ее сущности.

Адрес:/api/themes/update

Параметры:

полеописание
descrОпциональный. Описание сущности.
entitiesОпциональный. Массив с JSON–структурами сущностей.
secretОбязательный. Секретный ключ пользователя.
theme_idОбязательный. Идентификатор темы для редактирования.
titleОбязательный. Название сущности.

Структура данных ответа в полеdataотсутствует.

#Список

Возвращает список тем пользователя.

Адрес:/api/themes/get

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя. Для получения системных тем, необходимо передать значение -1.
with_systemОпциональный. Булевый флаг загрузки системных сущностей. Если указан, то системные темы будут добавлены к темам пользователя.

Структура данных ответа в полеdataсодержит массивJSON–объектов с данными темы.

#Удаление

Адрес:/api/themes/delete

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.
theme_idОбязательный. Идентификатор темы для удаления.

Структура данных ответа в полеdataотсутствует.

#Каталоги

#Создание

Адрес:/api/directory/create

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.
root_idОбязательный. Идентификатор каталога, в котором находится каталог.
titleОбязательный. Название каталога.

Структура данных ответа в полеdataотсутствует.

#Редактирование

Позволяет изменить название каталога.

Адрес:/api/directory/update

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.
dir_idОбязательный. Идентификатор каталога.
new_titleОбязательный. Новое название каталога.

Структура данных ответа в полеdataотсутствует.

#Список

Возвращает список каталогов и тем, содержащихся в каталоге.

Адрес:/api/directory/get

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.
idОпциональный. Идентификатор каталога. Если не указан, значение будет равно идентификатору корневого каталога — 0.
recursiveОпциональный. Булевый флаг загрузки содержимого каталога. Если указан, то содержимое будет браться из заданного каталога, иначе — из корневого.
with_systemОпциональный. Булевый флаг загрузки системных сущностей. Если указан, то системные темы будут добавлены к темам пользователя.

Структура данных ответа в полеdataсодержит массив JSON–объектов сданными каталоговиданными тем.

#Удаление

Адрес:/api/directory/delete

Параметры:

полеописание
secretОбязательный. Секретный ключ пользователя.
dir_idОбязательный. Идентификатор каталога.

Структура данных ответа в полеdataотсутствует.

#JSON–структуры данных

#Результаты расчета

Представляет собойJSON–объект темы,объекты сущностейкоторой содержат дополнительные поля:

  • texts— тексты, соотнесенные с сущностью;
  • texts_amount— количество текстов, соотнесенных с сущностью;
  • texts_percent— количество текстов, соотнесенных с сущностью, выраженное в процентах от общего количества текстов в расчете.

Кроме этого набор сущностей темы, по которой производился расчет, дополняется сущностьюНе распознано, которой сопоставляются все тексты, которые не удалось классифицировать. Объект сущностиНе распознанообладает теми же атрибутами, что и обычные сущности.

#Содержимое каталога

полеописание
directory_idИдентификатор каталога. Идентификатор корневого каталога равен 0.
titleНазвание каталога.
user_uuidИдентификатор пользователя владельца каталога.
root_idИдентификатор каталога, в котором находится каталог.

#Сущность

полеописание
associationsСлова–ассоциации, слова строгого соответствия и стоп–слова для сущности.
descrОпциональное описание сущности.
textsПоявляется при наличии результатов. Массив с текстами, отнесенными к сущности.
texts_amountПоявляется при наличии результатов. Количество текстов, отнесенных к сущности.
texts_percentПоявляется при наличии результатов. Процентное количество текстов, отнесенных к сущности, от общего количества текстов распознанных для классификации.
titleНазвание сущности.

#Тема

полеописание
descrОписание темы.
entitiesМассивобъектов сущностейтемы.
theme_idИдентификатор темы в базе данных сервиса.
titleНазвание темы.
user_uuidИдентификатор пользователя владельца темы. В случае значенияnullтема является системной.

#Тип запроса

полеописание
calc_typeТип расчета.classify— классификация по теме,sentiment— анализ тональности,emcol— анализ эмоционального окраса.
short_nameАббревиатура типа расчета.ММК— классификация по теме,ТО— анализ тональности,ЭО— анализ эмоционального окраса.
long_nameПолное название типа расчета.
priceСтоимость анализа 1 текста длиной до 2.000.000 символов. классификация по теме — 1.0 ₽, анализ тональности — 0.5 ₽,анализ эмоционального окраса - — 0.5 ₽.

#Транзакция

полеописание
calc_qualityКачество определения для запроса.
calc_typeТип расчета.classify— классификация по теме,sentiment— анализ тональности,emcol— анализ эмоционального окраса.
date_createUTC дата и время поступления запроса.
date_completeUTC дата и время окончания расчета запроса.
is_paidФлаг оплаты транзакции.
transaction_idУникальный идентификатор транзакции.
request_dataJSON–структура с даннымитемыили числом словосочетаний для анализа частотности слов.
request_ipIP–адрес источника запроса.
request_rawИсходный вариант текста для анализа.
result_dataJSON–структура с результатами расчета.
result_entitiesМассив сущностей, содержащий корневую сущность для расчета и сущность “Не распознано”.
texts_amountОбщее количество текстов, переданных на обработку.
texts_processedКоличество проанализированных текстов.
texts_splitterСимвол–разделитель текстов.
transaction_priceСтоимость транзакции.
transaction_statusСтатус транзакции: 10 — в очереди, 20 — рассчитывается, 30 — рассчитан.
transaction_titleОпциональное название запроса.

#Коды ошибок

кодрасшифровкаописание
2Ошибка сервераПри обработке запроса произошла ошибка на стороне сервера.
1001Пользователь не авторизованНеверно указан секретный ключ пользователя.
2001Невалидные данныеНекорректные данные в запросе.
2100Отрицательный балансБаланс пользователя меньше нуля.
2200Превышен лимит длины текста для анализаСуммарная длина общего текста запроса превышает установленный лимит.