Документация API Textgears

Textgears API позволяет интегрировать самые современные технологии анализа текста в любой продукт. От простых мобильных приложений до громоздких энтерпрайз разработок. API позволяет гибко проверять текст на все виды ошибок, определять читабельность текста, оценивать примерный словарный запас автора, и многое другое.

Что умеет API?

С чего начать

Все просто. API доступно для обычных запросов по протоколам HTTP и HTTPS. Формат выходных данных — JSON. Все запросы делаются к серверу api.textgears.com

Чтобы ускорить доступ из разных уголков мира мы расположили сервера в 3 странах: США, Эстония и Сингапур. При отправке запроса на api.textgears.com будет выбрал ближайший кластер. Но вы можете явно делать запросы к ближайшему к вам кластеру чтобы точно уменьшить задержку получения ответа.

https://eu.api.textgears.com – Europe
https://us.api.textgears.com – America
https://sg.api.textgears.com – Asia

Все эндпойнты API — это независимые кластеры серверов. Мы гарантируем работоспобосность каждого из них на уровне 99.9%. Если это кажется вам недостаточным, вы можете менять кластер при возникновении ошибки подключения.

                                                    
import textgears from 'textgears-api';

const textgearsApi = textgears('YOUR_KEY', {language: 'en-US'});
textgearsApi.checkGrammar('I is a engineer')
    .then((data) => {
        for (const error of data.errors) {
            console.log('Error: %s. Suggestions: %s', error.bad, error.better.join(', '));
        }
    })
    .catch((err) => {});
                                                    
                                                

Javascript library

Если вы реализовали библиотеку для работы с API на другом языке или для другого фреймворка, пришлите нам ссылку на GitHub или GitLab — мы с удовольствием ее опубликуем.

Поддерживаемые языки

TextGears анализирует текст не только с учетом языка текста, но и диалекта. Полный список поддерживаемых языков: английский, французский, немецкий, португальский, итальянский, испанский, японский, китайский, греческий

Поддерживаемые диалекты (передаеются в параметре language): en-US, en-GB, en-ZA, en-AU, en-NZ, fr-FR, de-DE, de-AT, de-CH, pt-PT, pt-BR, it-IT, es-ES, ja-JP, zh-CN, el-GR

Авторизация и передача параметров

Авторизация запроса происходит посредством передачи вашего ключа среди прочих параметров запроса одним из перечисленных способов:

  • POST parameter key
  • GET parameter key
    ?key=YOURKEY
  • Json-request
    {
        "key": "YOURKEY",
        // Other params
    }
  • HTTP Header
    Authorization: Basic YOURKEY
    Где YOURKEY - ваш ключ.

Коды ошибок

В случае ошибки параметр status будет false

{
    status : false,
    error_code : 600,  // API error code
    description : "Invalid license key. Go to https://textgears.com/signup.php to get one"
}
  • 600 - Некорректный ключ
  • 606 - Неподдерживаемый язык
  • 607 - Превышено разрешенное количество запросов
  • 500 - Неизвестная внутренняя ошибка сервиса
  • 501 - Длина текста превышает ограничение тарифа

API проверки текста

Проверка грамматики текста

https://api.textgears.com/grammar

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

Параметры запроса
Параметр Пример Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/grammar?key=DEMO_KEY&text=I+is+an+engeneer!&language=en-GB

Отправить запрос Результат будет показан ниже

Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        errors : [  // array of errors info
            0 : {
                id : "e492411846",  // unique error id
                offset : 2,  // error text offset
                length : 2,  // error text length
                bad : "is",  // error text
                better : [  // array of suggestions
                    0 : "am"
                ],
                type : "grammar"
            },
            1 : {
                id : "e627659964",  // unique error id
                offset : 8,  // error text offset
                length : 8,  // error text length
                bad : "engeneer",  // error text
                better : [  // array of suggestions
                    0 : "engineer",
                    1 : "engender"
                ],
                type : "spelling"
            }
        ]
    }
}
                                            
                                        

Проверка орфографии текста

https://api.textgears.com/spelling

Метод проверяет текст по актуальному словарю на опечатки

Параметры запроса
Параметр Пример Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/spelling?key=DEMO_KEY&text=I+is+an+engeneer!&language=en-GB

Отправить запрос Результат будет показан ниже

Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        errors : [  // array of errors info
            0 : {
                id : "e627659964",  // unique error id
                offset : 8,  // error text offset
                length : 8,  // error text length
                bad : "engeneer",  // error text
                description: "Error description",
                better : [  // array of suggestions
                    0 : "engineer",
                    1 : "engender"
                ],
                type : "spelling"
            }
        ]
    }
}
                                            
                                        

Автокоррекция текста

https://api.textgears.com/suggest

Система проверки автоматически исправляет ошибки в тексте и предлогает продолжение последнего предложения.

Важно!

При обнаружении опечатки производится замена слова на наиболее близкое. Если есть несколько слов, одинаково похожих на ошибочное, то выбирается наиболее распространенный в современной речи вариант. TextGears еще далек от телепатии, поэтому большом количестве опечаток смысл итогового текста может меняться.

Параметры запроса
Параметр Пример Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/suggest?key=DEMO_KEY&text=I+is+an+engeneer!+My+na

Отправить запрос Результат будет показан ниже

Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        corrected : "I am an engineer. My na", // corrected text
        suggestions : [ // array of suggested text endings
            0 : {
                end : "me",
                source : "I is an engeneer! My name",
                fixed : "I am an engineer. My name",
                next_word : "is"
            },
        ]
    }
}
                                            
                                        

Читабельность текста

https://api.textgears.com/readability

Расчет читабельности (readability) текста по наиболее распространенным алгоритмам и их адаптациям для большинства языков. Более подробно о метриках читабельности можно прочитать нашу отдельную статью.

Важно!

При определении метрик текста точность напрямую зависит от размера текста. Определять читабельность или иные параметры текста лдя предложения из двух слов бессмысленно. Рекомендуется проверять текст длиной хотя бы 30 слов. А лучше, еще больше.

Параметры запроса
Параметр Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/readability?key=DEMO_KEY&text=...
Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        stats: {
             fleschKincaid : { // Flesch–Kincaid index (https://en.wikipedia.org/wiki/Flesch–Kincaid_readability_tests)
                readingEase: 63.3, // Index value
                grade : "8th or 9th grade", // Flesch–Kincaid grade
                interpretation: "Plain English. Easily understood by 13- to 15-year-old students", // index value interpretation
             }
            gunningFog : 9.4, // https://en.wikipedia.org/wiki/Gunning_fog_index
            colemanLiau : 12, // https://en.wikipedia.org/wiki/Coleman–Liau_index
            SMOG : 6.5, // https://en.wikipedia.org/wiki/SMOG
            vocabularySize : {
                active: 5000, // How many words author uses every day
                passinve: 60000, // How many words author knows
            }
            emotion: { // text emotion classifier
                positive: 0.79, // probability
                negative: 0.21,
            }
        }
    }
}
                                            
                                        

Анализ текста

https://api.textgears.com/analyze

Комплексный анализ текста. Находит все виды ошибок, расчитывает метрики читабельности, дает оценку правописанию на 100-бальной шкале, а также дает оценку эмоциональному настроению текста

Важно!

При определении метрик текста точность напрямую зависит от размера текста. Определять читабельность или иные параметры текста лдя предложения из двух слов бессмысленно. Рекомендуется проверять текст длиной хотя бы 30 слов. А лучше, еще больше.

Параметры запроса
Параметр Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/analyze?key=DEMO_KEY&text=...
Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        errors : [  // array of errors info
            0 : {
                id : "e492411846",  // unique error id
                offset : 2,  // error text offset
                length : 2,  // error text length
                description: "Error description",
                bad : "is",  // error text
                better : [  // array of suggestions
                    0 : "am"
                ],
                type : "grammar"
            },
            1 : {
                id : "e627659964",  // unique error id
                offset : 8,  // error text offset
                length : 8,  // error text length
                bad : "engeneer",  // error text
                description: "Error description",
                better : [  // array of suggestions
                    0 : "engineer",
                    1 : "engender"
                ],
                type : "spelling"
            }
        ],
        stats: {
             fleschKincaid : { // Flesch–Kincaid index (https://en.wikipedia.org/wiki/Flesch–Kincaid_readability_tests)
                readingEase: 63.3, // Index value
                grade : "8th or 9th grade", // Flesch–Kincaid grade
                interpretation: "Plain English. Easily understood by 13- to 15-year-old students", // index value interpretation
             }
            gunningFog : 9.4, // https://en.wikipedia.org/wiki/Gunning_fog_index
            colemanLiau : 12, // https://en.wikipedia.org/wiki/Coleman–Liau_index
            SMOG : 6.5, // https://en.wikipedia.org/wiki/SMOG
            vocabularySize : {
                active: 5000, // How many words author uses every day
                passinve: 60000, // How many words author knows
            }
            emotion: { // text emotion classifier
                positive: 0.79, // probability
                negative: 0.21,
            }
        }
    }
}
                                            
                                        

Определение языка

https://api.textgears.com/detect

Определение языка текста и предположение о его диалекте. Метод возвращает массив вероятностей для каждого языка. Если не удается однозначно определить язык, в поле language возвращается null

Параметры запроса
Параметр Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/detect?key=DEMO_KEY&text=Some+test+words
Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        language : "en", // null if language was not detected
        dialect : "en-GB", // language dialect suggestion
        probabilities : { // descending
            "en" : 0.95,
            "fr" : 0.61,
            "ge" : 0.60,
            "fi" : 0.51,
        }
    }
}
                                            
                                        

Admin API

Данные тарифной квоты

https://api.textgears.com/account/resourcequota

Получение данных текущией тарифной квоты. Метод можно использовать чтобы следить за тем, сколько запросов в рамках тарифа уже сделано, сколько запросов еще можно сделать в рамках периода тарификации

Параметры запроса
Параметр Пример Описание
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/account/resourcequota?key=DEMO_KEY

Отправить запрос Результат будет показан ниже

Ответ сервера
                                            
{
    status : true,
    response : {
        api : { // Resource type, "api" if you use TextGears API
            type : "api", // Resource type
            total : 1000000, // Total resource quota size
            used : 123000, // How many requests was made using this quota
            period_start: "2018-10-20T00:00:00+0000", // Quota paid period start (ISO8601 format)
            period_end: "2019-10-20T00:00:00+0000", // End of the quota paid period (ISO8601 format)
        },
    },
}
                                            
                                        

Статистика использования

https://api.textgears.com/account/usage

Получение статистики использования API вашим аккаунтом с разбивкой по днях

Параметры запроса
Параметр Пример Описание
period_start Начале периода. Необзятательный параметр..
period_end Конец периода. Необзятательный параметр. Если период не задан, выводятся данные за последние 30 дней.
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/account/usage?key=DEMO_KEY

Отправить запрос Результат будет показан ниже

Ответ сервера
                                            
{
    status : true,  // false in case of checking error
    response : [
        0 : {
            date : "2020-04-20",
            request_count : 11875
        },
        1 : {
            date : "2020-04-21",
            request_count : 10588
        }
    ]
}
                                            
                                        

Добавить исключение

https://api.textgears.com/custom/addexception

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

Параметры запроса
Параметр Описание
exception Начале периода. Необзятательный параметр..
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/custom/addexception?exception=foobaring&key=DEMO_KEY
Ответ сервера
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
    },
}
                                            
                                        

Список исключений

https://api.textgears.com/custom/listexceptions

Вывод списка ранее добавленных слов-исключений

Параметры запроса
Параметр Описание
limit Максимальное количество записей в результате. Не больше 500..
offset Сколько записей, упорядоченных по тексту, пропускается при выводе. Используется для постраничного вывода..
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/custom/addexception?exception=foobaring&key=DEMO_KEY
Ответ сервера
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
    },
}
                                            
                                        

Удалить исключение

https://api.textgears.com/custom/deleteexception

Удалить слово-исключение для проверки. Если попытаться удалить ранее удаленное, то ошибки не возникает.

Параметры запроса
Параметр Описание
id ID исключения для удаления..
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/custom/deleteexception?id=20&key=DEMO_KEY
Ответ сервера
                                            
{
    status : true,
    response : {}
}