API

Alexey Knorre edited this page Dec 8, 2016 · 8 revisions
Clone this wiki locally

Зачем всё это нужно

Оценка читаемости текстов необходима для автоматического определения сложности текстов на русском языке.

Что было сделано

Есть 5 американских алгоритмов оценки читаемости текстов, это:

Были накоплены тексты на русском языке с разметками по уровню чтения, это:

  • тексты для внеклассного чтения;
  • экспертно размеченные взрослые тексты;
  • особо сложные тексты законов;
  • и так далее.

Все алгоритмы были обучены под русский язык - специальным образом каждая формула была подобрана на основе обучающей выборки. Для всех формул были применены коэффициенты позволяющие применять их к русским текстам.

На базе этих формул был сделан специальный веб-сервис который позволяет передавать ему текст или ссылку и оценивать его на сложность.

Как работает API

API доступно по ссылке и http://api.plainrussian.ru/api/1.0/ru/measure/ и для его работы ему необходимо передать параметр url (для ссылки) или text (как текст).

Параметр url передается при обращении через GET запрос, пример такого обращения выглядит вот так:

вот с примером простого текста:

или вот:

Результат выглядит вот так:

{ metrics: { wsyllabes: { 1: 94, 2: 116, 3: 140, 4: 87, 5: 139, 6: 45, 7: 18, 8: 4, 15: 1 }, c_share: 32.142857142857146, chars: 6000, avg_slen: 46, spaces: 510, n_syllabes: 2232, n_words: 644, letters: 5170, n_sentences: 14, n_complex_words: 207, n_simple_words: 437, avg_syl: 3.4658385093167703 }, status: 0, indexes: { grade_SMOG: "Аспирантура, второе высшее образование, phD", grade_ari: "Аспирантура, второе высшее образование, phD", index_fk: 33.342906832298134, grade_cl: "Аспирантура, второе высшее образование, phD", grade_fk: "Аспирантура, второе высшее образование, phD", index_cl: 23.062857142857148, grade_dc: "Аспирантура, второе высшее образование, phD", index_dc: 30.300857142857147, index_ari: 32.11796894409938, index_SMOG: 34.046178356649776 } }

Кроме того, вместо параметра url можно использовать text, чтобы при запросе передавался текст, а не гиперссылка на текст. Вместо GET-запроса имеет смысл использовать POST, чтобы обойти ограничение на размер URI.
Пример того, как это выглядит в Python с использованием библиотеки requests:

import requests
text = "Здесь может быть Ваш текст"
response = requests.post("http://api.plainrussian.ru/api/1.0/ru/measure/", data={"text":text})
response.json()

Параметры означают:

indexes - набор индикаторов читаемости текста:

  • grade_SMOG - уровень образования необходимый для понимания текста по формуле SMOG, человеческим языком
  • grade_ari - уровень образования необходимый для понимания текста по формуле Automated Readability Index, человеческим языком
  • grade_cl - уровень образования необходимый для понимания текста по формуле Coleman-Liau, человеческим языком
  • grade_fk - уровень образования необходимый для понимания текста по формуле Flesch-Kinkaid, человеческим языком
  • grade_dc - уровень образования необходимый для понимания текста по формуле Dale-Chale, человеческим языком
  • index_SMOG - уровень образования необходимый для понимания текста по формуле SMOG, в годах обучения от 1 до бесконечности
  • index_ari - уровень образования необходимый для понимания текста по формуле Automated Readability Index, в годах обучения от 1 до бесконечности
  • index_cl - уровень образования необходимый для понимания текста по формуле Coleman-Liau, в годах обучения от 1 до бесконечности
  • index_fk - уровень образования необходимый для понимания текста по формуле Flesch-Kinkaid, в годах обучения от 1 до бесконечности
  • index_dc - уровень образования необходимый для понимания текста по формуле Dale-Chale, в годах обучения от 1 до бесконечности

metrics - набор расчетных показателей из текста

  • chars - сколько всего знаков тексте
  • spaces - сколько пробелов в тексте
  • letters - сколько букв в тексте
  • n_words - число слов
  • n_sentences - число предложений
  • n_complex_words - число слов с более чем 4-мя слогами
  • n_simple_words - число слов до 4-х слогов включительно
  • avg_slen - среднее число слов на предложение
  • avg_syl - среднее число слогов на предложение
  • c_share - процент сложных слов от общего числа
  • w_syllabes - словарь из значений: число слогов и число слов с таким числом слогов в этом тексте

Если передать параметр debug=1, то также вернется значение текста которое было передано.

Вот несколько примеров текстов на которых шло обучение.