Как использовать
API проверки текста
Admin API
Прочее

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

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

Нужен плагин для сайта?

Вы можете без проблем добавить проверку текста на свой сайт. Подробнее о плагине и примеры кода можно найти на странице документации.

Что умеет API?

Документация для Postman

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

Download TextGears.postman.json

С чего начать

Все просто. 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, ru-RU, ar-AR, 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. Список поддерживаемых кодов
whitelist Необязательный параметр. Массив слов, которые не нужно считать ошибками.
dictionary_id Необязательный параметр. id словаря с кастомными правилами проверки. Создание и редактирование словарей.
ai true, false, 1, 0. Использовать TextGears AI для улучшения качества анализа текста.
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. Список поддерживаемых кодов
whitelist Необязательный параметр. Массив слов, которые не нужно считать ошибками.
dictionary_id Необязательный параметр. id словаря с кастомными правилами проверки. Создание и редактирование словарей.
ai true, false, 1, 0. Использовать TextGears AI для улучшения качества анализа текста.
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/correct

Есть два метода для автоматического исправления текста. Метод correct заметно точнее, но относится к AI-запросам.

Важно!

В данный момент метод работает только для английского языка

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

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

Ответ сервера
                                            
{
    status : true,  // false in case of checking error
    response : {
        corrected : "What is your name?"  // corrected text
    }
}
                                            
                                        
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 : "My name is Seth. My family",  // corrected text
        suggestions : [  // array of suggested text endings
            0 : {
                text : "My name is Seth. My family wishes",
                next_word : "wishes"
            },
            1 : {
                text : "My name is Seth. My family traditions",
                next_word : "traditions"
            },
            2 : {
                text : "My name is Seth. My family together",
                next_word : "together"
            },
            3 : {
                text : "My name is Seth. My family support",
                next_word : "support"
            },
            4 : {
                text : "My name is Seth. My family respectfully",
                next_word : "respectfully"
            }
        ]
    }
}

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

https://api.textgears.com/readability

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

Важно!

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

Параметры запроса
Параметр Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
text 
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 : 53.4, // Index value
                grade : "10th to 12th grade", // Flesch–Kincaid grade
                interpretation : "Fairly difficult to read" // index value interpretation
            },
            gunningFog : 12.2, // https://en.wikipedia.org/wiki/Gunning_fog_index
            colemanLiau : 12, // https://en.wikipedia.org/wiki/Coleman–Liau_index
            SMOG : 12, // https://en.wikipedia.org/wiki/SMOG
            vocabularySize : {
                active : null, // How many words author uses every day
                passive : null // How many words author knows
            },
            emotion : { // text emotion classifier
                positive : 0.79,
                negative : 0.21
            },
            counters : {
                length : 1128,
                clearLength : 936,
                words : 187,
                sentences : 10
            }
        }
    }
}

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

https://api.textgears.com/analyze

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

Важно!

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

Параметры запроса
Параметр Описание
text Текст в кодировке UTF-8. Лучше отправлять голый текст без HTML-тегов с некорректных UTF-8 символов. Мавсимальная длина ограничена параметрами вашего тарифного плана.
language Код языка. Необязательный параметр, значение по-умолчанию en-US. Список поддерживаемых кодов
whitelist Необязательный параметр. Массив слов, которые не нужно считать ошибками.
dictionary_id Необязательный параметр. id словаря с кастомными правилами проверки. Создание и редактирование словарей.
ai true, false, 1, 0. Использовать TextGears AI для улучшения качества анализа текста.
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/analyze?key=DEMO_KEY&text=...
Ответ сервера
                                            
{
    status : true, // false in case of checking error
    response : {
        grammar: {
            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-ключ. Нет ключа? Получить в один клик!.
Пример запроса
text 
https://api.textgears.com/detect?key=DEMO_KEY&text=...

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

Ответ сервера
                                            
{
    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,
        }
    }
}

Суммаризация и извлечение ключевых слов

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

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

Ответ сервера
                                            
{
    status : true,  // false in case of checking error
    response : {
        keywords : [
            0 : "text",
            1 : "readability",
            2 : "english",
            3 : "printing",
            4 : "fewer",
            5 : "words",
            6 : "terms",
            7 : "higher",
            8 : "features",
            9 : "indexes"
        ],
        highlight : [ // Most important paragraph, starting with main sentence
            0 : "The two main factors of readability are the printing and linguistic features of the text.",
            1 : "In other words, pages containing simple and clear text get higher positions in the search results."
        ],
        summary : [ // Text summary sentences
            0 : "The two main factors of readability are the printing and linguistic features of the text.",
            1 : "The Flesch Kinkaid Score is the most popular way to measure the readability of English text.",
            2 : "It works on the principle of “the fewer words in the text, and the fewer syllables in them, the easier it is to perceive” and is most often used for checking essays in schools and universities."
        ]
    }
}

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/createdictionary

Если вам нужна гибкая настройка проверки текста на ошибки, воспользуйтесь настройкой кастомных исключений. Это будет особенно удобно компаниям, работающим с текстами, изобилующими специальной лексикой. Отмечайте слова или словосочетания как «правильные» чтобы система перестала считать их ошибочными или наоборот – чтобы система находила ошибку при появлении заданных вами слов. Кастомные правила проверки можно объединять в словари. Чтобы, например, разные функции вашего продукта использовали разный набор правил. Или чтобы каждый пользователь вашего продукта мог иметь свой собственный набор исключений.

Параметры запроса
Параметр Описание
id Id создаваемого словаря. Да, вы сами задаете удобный вам id. Строка до 64 символов. Это может быть числом, GUID или даже null. Словарь с id === null будет словарем по умолчанию. В него попадают исключения, созданные без указания dictionary_id.
title Название словаря. Максимальная длина 500 символов.
key Ваш API-ключ. Нет ключа? Получить в один клик!. 
https://api.textgears.com/custom/updatedictionary
Параметр Описание
id Id словаря. Числом, GUID или даже null.
title Название словаря. Максимальная длина 500 символов.
key Ваш API-ключ. Нет ключа? Получить в один клик!. 
https://api.textgears.com/custom/listdictionaries
Параметр Описание
limit Максимальное количество записей в результате. Не больше 500.
offset Сколько записей пропускается при поиске.
key Ваш API-ключ. Нет ключа? Получить в один клик!. 
https://api.textgears.com/custom/deletedictionary
Параметр Описание
id Id словаря. Числом, GUID или даже null
key Ваш API-ключ. Нет ключа? Получить в один клик!.

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

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

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

Параметры запроса
Параметр Описание
text Слово или текст которые будут обрабатываться особым образом. Максимальная длина 500 симоволов.
type Тип исключения. Значения: 2 - считать text ошибкой, 1 - не считать text ошибкой.
lang Код языка текста. Исключение будет применяться только для текстов на таком же языке. Если передать значение en, будет применяться для всех диалектов английского, de — немецкого, и.т.д.
description Необязательный параметр. Текст описания исключения.
dictionary_id Необязательный параметр. Идентификатор кастомного "словаря" — группы исключений. Строка не более 64 символов или NULL. При анализе текста можно передавать id словаря для включения исключений конкретной группы.
suggestions Необязательный параметр. Варианты исправления текста. Массив строк или строка, разделенная запятыми. Максимальное количество: 16. Параметр учитывается только для ошибок.
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/custom/addexception?text=foobaring&type=2&lang=en-US&key=DEMO_KEY
Ответ сервера
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
        text: "foobaring",
        type: 1,
        lang: "en-US",
        creation_time: "2024-04-16T18:14:25+0000",
        suggestions: [],
        update_time: null,
        description: null,
    },
}

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

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

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

Параметры запроса
Параметр Описание
limit Максимальное количество записей в результате. Не больше 500.
offset Сколько записей, упорядоченных по тексту, пропускается при выводе. Используется для постраничного вывода.
dictionary_id Необязательный параметр. id группы исключений (словаря). Для получения исключений из группы по умолчанию допустимо передавать null.
text Необязательный параметр. Фильтр по тексту исключения.
type Необязательный параметр. Фильтр по типу исключения.
lang Необязательный параметр. Фильтр по языку.
key Ваш API-ключ. Нет ключа? Получить в один клик!.
Пример запроса
https://api.textgears.com/custom/addexception?text=foobaring&key=DEMO_KEY
Ответ сервера
                                            
{
    status : true,
    response : {
        exceptions : [
            {
                id: 20,
                text: "foobaring",
                type: 1,
                lang: "en-US",
                creation_time: "2024-04-16T18:14:25+0000",
                update_time: null,
                description: null,
            },
        ],
    },
}

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

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

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

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