Доступ к API и другие технические вопросы

Как получить доступ к API сервиса?

Доступ к API — платный.

Для получения доступа необходимо: 1) зарегистрироваться на сайте и 2) оплатить сервис (напишите нам, чтобы уточнить стоимость услуги). После подтверждения оплаты администратор сайта заведет вам логин для доступа к API.

Помимо логина, для выполнения запросов к API потребуется отдельный пароль — он не совпадает с паролем для входа на сайт. Чтобы получить пароль, авторизуйтесь, зайдите в свой профиль и нажмите кнопку «Сгенерировать пароль». Пароль начнет действовать в течение часа после генерации.

Как пользоваться API?

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

В первом случае сервис самостоятельно скачивает документ по указанному URL и производит его анализ. Во втором случае клиент отдает сервису подлежащий обработке документ посредством метода POST протокола HTTP.

Каждый запрос к сервису сопровождается парой login и password.

  • Пример обращения к API «Семантического зеркала» для рубрикации веб-страницы по указанному адресу (вместо LOGIN, PASSWORD и URL_TO_RUBRICATE нужно подставить свои данные):

    http://api.sm.ashmanov.com:8789/remote?url=URL_TO_RUBRICATE&login=LOGIN&password=PASSWORD

  • Пример обращения к API «Автоконтекста» для выделения ключевых терминов с веб-страницы по указанному адресу:

    http://api.sm.ashmanov.com:8794/remote?url=URL_TO_RUBRICATE&login=LOGIN&password=PASSWORD

  • Пример обращения к API «Семантического зеркала» при отправке данных методом POST:

    http://api.sm.ashmanov.com:8789/upload?login=LOGIN&password=PASSWORD

  • Пример обращения к API «Автоконтекста» при отправке данных методом POST:

    http://api.sm.ashmanov.com:8794/upload?login=LOGIN&password=PASSWORD

В двух последних примерах документ загружается методом POST в поле data. Форма для загрузки и отправки одиночных файлов сервису также реализована в личном профиле пользователя.

Как URL_TO_RUBRICATE, так и документы, загружаемые методом POST, должны быть закодированы urlencode. Например, если с помощью API необходимо отрубрицировать URL http://optimization.ru, то URL_TO_RUBRICATE в этом случае должен выглядеть так: http%3A%2F%2Foptimization.ru.

Можно ли ограничить доступ к API по IP-адресу?

Да, сервис позволяет разрешить доступ по конкретному логину только для определенных IP-адресов. Задать список адресов вы можете в своем профиле.

В каком формате API отдает данные?

API возвращает результаты в формате XML.

  • Пример распознанной рубрики из XML-выдачи «Семантического зеркала»:

    <category id="SciTech/Technics" title="Техника, электроника" weight="81.5%" difflimit="91"></category>

  • Пример выделенного термина из XML-выдачи «Автоконтекста»:

    <term weight="0.387334" type="">рубрики первого уровня</term>

Что обозначают атрибуты в XML-выдаче «Семантического зеркала» (API)?

id — идентификатор категории. В идентификаторе указан полный путь от данной рубрики до корневой. Идентификатор каждой рубрики уникален.

title — название категории. Кратко отражает основное содержание рубрики.

difflimit — степень конкретности категории. Значение представляет собой целое число в интервале от 90 до 99. Чем выше difflimit, тем уже содержание рубрики. Иногда difflimit напрямую соответствует уровню вложенности категории, но нередко и расходится с ним.

weight — вес рубрики в процентах, отражает степень соответствия текста данной рубрике.

Что обозначают атрибуты в XML-выдаче «Автоконтекста» (API)?

weight — вес ключевого термина.

type — опциональное служебное поле, используется в технической поддержке сервиса (для пользователей неинформативно).

Работу с документами каких форматов поддерживает сервис?

Сервис умеет обрабатывать документы в форматах TXT и HTML.

Понимает ли сервис кириллические домены?

Кириллические домены необходимо предварительно конвертировать в Punycode. Например, вместо ашманов.рф в качестве запроса к сервису следует задать xn--80aag2bgg0e.xn--p1ai.

Какие рубрики первого уровня распознает «Семантическое зеркало»?

Список рубрик первого уровня (в скобках приведены примеры подтем):

  • «Техника и наука» (компьютеры; космос; мобильная связь),

  • «Авто, мото» (внедорожники; шины и диски; трансмиссия),

  • «Дом, офис» (мебель; посуда; канцтовары),

  • «Личные вещи» (одежда; косметика; подарки),

  • «Продукты» (кулинария; молочные продукты; напитки),

  • «Семья, дети» (игрушки; грудное вскармливание; коляски),

  • «Здоровье и красота» (офтальмология; витамины; контроль веса),

  • «Общество» (законодательство; образование; религия),

  • «Культура» (музыка; книги; музеи),

  • «Спорт» (футбол; спортинвентарь; Олимпийские игры),

  • «Досуг» (охота, рыбалка; астрология; эротика),

  • «Недвижимость, строительство, ремонт» (пластиковые окна; строительные смеси; ипотека),

  • «Экономика и бизнес» (ценные бумаги; страхование; энергетика),

  • «Политика» (российская власть; выборы; ядерное оружие),

  • «История» (Древний мир; Средние века; Новое время),

  • «Мир» (Россия; Северная Африка; Скандинавия),

  • «Происшествия» (ДТП; криминал; землетрясения),

  • «Брань» (умеренная брань; грубая брань; мат).

Где можно увидеть полный список рубрик «Семантического зеркала»?

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

Сервис плохо рубрицирует очень короткие тексты: поисковые запросы, ссылки, твиты, теги, sms и т. д. Есть ли решение?

Сервис предназначен прежде всего для рубрикации веб-страниц и других текстов, объем которых обычно не слишком мал и составляет хотя бы несколько предложений. Для рубрикации очень коротких текстов у нас есть отдельное решение — особая разновидность базы, разработанная для выполнения подобных задач. Условия доступа к этой базе оговариваются с каждым клиентом индивидуально.

Какие значения точности и полноты определения тематик обеспечивает «Семантическое зеркало»?

Значения точности и полноты принципиально зависят от конкретной задачи и того материала, на котором эту задачу предполагается решать. Например, на корпусе новостей хотя бы одну рубрику «Семантическое зеркало» присваивает более 90 % текстов при точности в 95 % и выше; на корпусе поисковых запросов первый показатель будет существенно меньше — 60-70 %, а второй может быть даже выше, чем в случае новостей. Воспользуйтесь демонстрационным доступом к сервису, чтобы примерно оценить показатели качества распознавания на интересующем вас материале.

Почему некоторые тексты не получают рубрик?

Помимо недоступности веб-страниц по техническим причинам, не связанным с работой авторубрикатора (ошибка 404 и др.), отсутствие присвоенных рубрик может объясняться следующими факторами:

  • На веб-странице нет текста.

  • Объем текста слишком мал для уверенного определения тематики.
    См. также: Сервис плохо рубрицирует очень короткие тексты. Есть ли решение?

  • Текст бессодержателен. Зачастую это характерно для спамерских страниц, созданных с помощью синонимайзеров и других технологий видоизменения текста.

  • Текст не имеет четкой тематической направленности. Пример: заметка в блоге, мельком затрагивающая ряд разных тем либо полностью абстрактная по своему содержанию. Обычно эта особенность также присуща художественным текстам.

  • Текст посвящен специфической теме, которая пока не проработана в нашем рубрикаторе.
    См. также: Где можно увидеть полный список рубрик «Семантического зеркала»?

  • Текст представлен в формате, не известном сервису.
    См. также: Работу с документами каких форматов поддерживает сервис?

  • Язык текста — не русский. Во многих случаях «Семантическое зеркало» может распознать и страницы на английском языке, другие же языки — не поддерживаются.

Структура рубрик «Семантического зеркала» нам не подходит. Можно ли ее поменять?

Серьезные изменения в структуре рубрикатора невозможны. В таких случаях мы рекомендуем — и активно используем это в своих проектах — создавать таблицу соответствий (таблицу мэппинга) между рубриками «Семантического зеркала» и рубриками, нужными вам.

Допустим, вам необходима рубрика «Наука и образование», а в «Семантическом зеркале» такой рубрики нет. Вместо нее в «Семантическом зеркале» есть две отдельные рубрики: «Наука» (под «Техникой и наукой») и «Образование» (под «Работой и образованием» в «Обществе»). В таком случае с помощью таблицы соответствий вы можете самостоятельно соотнести эти две рубрики с нужной вам «Наукой и образованием».

Кроме того, такой подход позволяет вводить разные дополнительные правила преобразования рубрик. Ср.: если тексту одновременно приписались рубрики «ДТП» и «Автомобили», рубрику «Автомобили» отбрасываем — оставляем только «ДТП» (такое правило может быть полезно при рубрикации новостей).

Таблицы соответствий и правила преобразования рубрик полностью реализуются на стороне клиента.

Можете ли вы разработать для нас новые рубрики?

В некоторых случаях разработка новых рубрик возможна — как правило, за отдельную плату. При этом нужно учитывать, что нередко она занимает значительное количество времени (иногда не один месяц).

Можно ли получить доступ к базе терминов «Семантического зеркала»?

Нет, такой доступ не предоставляется.

У нас есть еще вопросы. Как их задать?

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