How to use
Text validation API
Admin API
Other

Grammar and spelling check API documentation

TextGears API allows you to integrate the latest technologies for text analyzing virtually to any product. From simple mobile apps to bulky enterprise developments. The API allows you to check text for all kinds of errors in a flexible manner, determine the readability of the text, evaluate the approximate vocabulary of the author, and much more.

Looking for a plugin for website?

You can easily add text checking to your website. More info about the plugin and sample code can be found on documentation page.

What can the API do?

Docs for Postman

You can download API documentation file for Postman or any other HTTP debugging program. In Postman you can set a key at collection Variables tab..

Download TextGears.postman.json

Where to begin

It's simple and easy. The API is available for regular HTTP and HTTPS requests. The output data is sent in JSON. All requests are made to the api.textgears.com server

To speed up access from different parts of the world, we placed servers in 3 countries: USA, Estonia and Singapore. When submitting a request to api.textgears.com we will choose the closest cluster. But you can explicitly make requests to the cluster located nearby to reduce the delay in receiving a response.

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

All API endpoints are independent clusters of servers. We guarantee a 99.9% availability for each of them . If this seems insufficient to you, you can change the cluster when a connection error occurs. 

                                                    
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

If you have implemented a library for working with API in another language or for another framework, just send us a link on GitHub or GitLab, while we will publish it as well.

Supported languages

TextGears analyzes text not only by taking the language of the text into account, but also keeping the dialect in mind. Full list of supported languages: English, French, German, Portuguese, Russian, Italian, Arabic, Spanish, Japanese, Chinese, Greek

Supported dialects (have to be sent in the language parameter): en-US, en-GB, en-ZA, en-AU, en-NZ, fr-FR, de-DE, de-AT, de-CH, pt-PT, pt-BR, it-IT, ar-AR, ru-RU, es-ES, ja-JP, zh-CN, el-GR

Authorization and parameter transfer

The request is authorized by transferring your key among other parameters in one of the following ways:

  • POST parameter key
  • GET parameter key 
    ?key=YOURKEY
  • Json-request 
    {
    "key": "YOURKEY",
    // Other params
}
  • HTTP Header 
    Authorization: Basic YOURKEY
    Where YOURKEY is your key.

Error codes

In case of an error, the status parameter will have false value 

{
    status : false,
    error_code : 600,  // API error code
    description : "Invalid license key. Go to https://textgears.com/signup.php to get one"
}
  • 600 - Invalid key
  • 606 - Unsupported Language
  • 607 - Allowed number of requests exceeded
  • 500 - Unknown internal service error
  • 501 - Text length exceeds rate limit

Text validation API

Checking the grammar of the text

https://api.textgears.com/grammar

The method allows you to check the text for grammatical, spelling, punctuation and stylistic errors.

Request parameters
Parameter Example Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
whitelist Not required. Array of words and phrases which must not be detected as mistakes.
dictionary_id Not required. Custom dictionary id. Dictionary is a group of custom rules. Create and edit dictionaries.
ai true, false, 1, 0. Use TextGears AI to improve the quality of text analysis.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/grammar?key=DEMO_KEY&text=I+is+an+engeneer!&language=en-GB

Send request The result will be shown below

Server response
                                            
{
    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"
            }
        ]
    }
}

Checking the spelling of text

https://api.textgears.com/spelling

The method checks the text for typos by using the updated dictionary

Request parameters
Parameter Example Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
whitelist Not required. Array of words and phrases which must not be detected as mistakes.
dictionary_id Not required. Custom dictionary id. Dictionary is a group of custom rules. Create and edit dictionaries.
ai true, false, 1, 0. Use TextGears AI to improve the quality of text analysis.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/spelling?key=DEMO_KEY&text=I+is+an+engeneer!&language=en-GB

Send request The result will be shown below

Server response
                                            
{
    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"
            }
        ]
    }
}

Auto-correcting text

https://api.textgears.com/correct

There are two methods for automatic text correction. The "correct" method is noticeably more precise, but it applies to AI requests.

Important!

At the moment, the method only works for the English language.

Request parameters
Parameter Example Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/correct?text=What+are+you+name%3F&language=en-GB&key=DEMO_KEY

Send request The result will be shown below

Server response
                                            
{
    status : true,  // false in case of checking error
    response : {
        corrected : "What is your name?"  // corrected text
    }
}
                                            
                                        
https://api.textgears.com/suggest

The verification system automatically corrects errors in the text and suggests a continuation of the last sentence.

Important!

If a typo is found, the word is replaced to the closest word from the dictionary. If there are multiple words looking similar to the detected one, then the most common word in modern speech is chosen. TextGears is still far from telepathy, so if there are a lot of typos the meaning of the final text may change.

Request parameters
Parameter Example Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/suggest?key=DEMO_KEY&text=I+is+an+engeneer!+My+na

Send request The result will be shown below

Server response
                                            
{
    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"
            }
        ]
    }
}

Readability of the text

https://api.textgears.com/readability

Calculation of the readability of the text according to the most common algorithms and their adaptations for most languages. You can learn more about readability metrics. by reading our separate article.

Important!

When determining text metrics, accuracy is directly related to the size of the text. Determining the readability or other parameters of the text for a two-word sentence is meaningless. It is recommended to check texts that has at least 30 words. The more the better.

Request parameters
Parameter Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
key Your API key. Don’t you have a key? Get it in one click!.
Request example
text 
https://api.textgears.com/readability?key=DEMO_KEY&text=...

Send request The result will be shown below

Server response
                                            
{
    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
            }
        }
    }
}

Text analysis

https://api.textgears.com/analyze

Comprehensive text analysis. It finds all kinds of errors, calculates readability metrics, grades spelling on a 100-point scale, and also evaluates the emotional mood of the text.

Important!

When determining text metrics, accuracy is directly related to the size of the text. Determining the readability or other parameters of the text for a two-word sentence is meaningless. It is recommended to check texts that has at least 30 words. The more the better.

Request parameters
Parameter Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
whitelist Not required. Array of words and phrases which must not be detected as mistakes.
dictionary_id Not required. Custom dictionary id. Dictionary is a group of custom rules. Create and edit dictionaries.
ai true, false, 1, 0. Use TextGears AI to improve the quality of text analysis.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/analyze?key=DEMO_KEY&text=...
Server response
                                            
{
    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,
            }
        }
    }
}

Language detection

https://api.textgears.com/detect

Determination of the language of the text and the assumption of its dialect. The method returns an array of probable options for each language. If it is not possible to unambiguously identify the language, the language field returns null

Request parameters
Parameter Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
text 
https://api.textgears.com/detect?key=DEMO_KEY&text=...

Send request The result will be shown below

Server response
                                            
{
    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,
        }
    }
}

Summarization and keywords extraction

https://api.textgears.com/summarize
Request parameters
Parameter Description
text UTF-8 encoded text. We recommend sending pure text without HTML tags and invalid UTF-8 characters. The maximum length is limited by the parameters of your billing plan.
language Language code. It’s an optional parameter, and the default value is en-US. List of supported codes
max_sentences Optional parameter. Max number of sentences in summary
key Your API key. Don’t you have a key? Get it in one click!.
Request example
language
text 
https://api.textgears.com/summarize?key=DEMO_KEY&language=en-GB&text=...

Send request The result will be shown below

Server response
                                            
{
    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

Plan quota

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

Receiving data on the current plan quota. The method can be used to keep track of whether how many requests within the plan have already been made, or how many requests can still be made within the billing period

Request parameters
Parameter Example Description
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/account/resourcequota?key=DEMO_KEY

Send request The result will be shown below

Server response
                                            
{
    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)
        },
    },
}

Usage statistics

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

Getting statistics of API usage for your account with a breakdown by day

Request parameters
Parameter Example Description
period_start Beginning of the period. Optional parameter..
period_end End of the period. Optional parameter. If the period is not specified, the data for the last 30 days is displayed.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/account/usage?key=DEMO_KEY

Send request The result will be shown below

Server response
                                            
{
    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
        }
    ]
}

Create and edit dictionaries

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

If you need a flexible setting for checking text for errors, use the custom exceptions setting. This will be especially useful for companies working with texts that are full of words from a special vocabulary. Mark words or phrases as "correct" so that the system stops considering them mistakes. You can also use it to allow the system to find mistakes according to the list of specific words. Custom rules can be combined and transformed into dictionaries. Such an approach makes it possible for the different functions of your product to use a different set of rules. At the same time, each user of your product can have their own set of exceptions

Request parameters
Parameter Description
id Id of custom dictionary. Yes, you set id by yourself. Two different accounts can create dictionaries with the same ids. Can be a number, a string or even null. Default dictionary has id === null. It will be filled with exceptions created without dictionary_id parameter.
title Dictionary title. Max length: 500 chars.
key Your API key. Don’t you have a key? Get it in one click!. 
https://api.textgears.com/custom/updatedictionary
Parameter Description
id Dictionary Id. Can be any string up to 64 chars or null.
title Dictionary title. Max length: 500 chars.
key Your API key. Don’t you have a key? Get it in one click!. 
https://api.textgears.com/custom/listdictionaries
Parameter Description
limit The maximum number of records in the result. No more than 500..
offset How many records will be ignored.
key Your API key. Don’t you have a key? Get it in one click!. 
https://api.textgears.com/custom/deletedictionary
Parameter Description
id Dictionary Id. Can be any string up to 64 chars or null
key Your API key. Don’t you have a key? Get it in one click!.

Add an exception

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

If you are checking texts with very specific vocabulary that is marked as errors in our system, you can add words or phrases to exceptions. After that, they will not be considered errors.

Request parameters
Parameter Description
text A word or a text to be marked another custom way. Max length is 500 characters.
type Exception type. Possible values: 2 – text IS a mistake, 1 – text is NOT a mistake.
lang Language code. Exception will be applied only to text in this language. Set en for all English dialects, de for all German dialects, pt for all Portuguese dialects, etc.
description Not required. Custom exception description.
dictionary_id Not required parameter. Custom dictionary (a group of exceptions) id. String, length can be up to 64 chars or NULL. You can set dictionary_id parameter while sending analyze or check request to choose a dictionary to be applied.
suggestions Not required. Text correction suggestions. String array or a string of comma separated values. Max count: 16. Parameter is ignored if type=2.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/custom/addexception?text=foobaring&type=2&lang=en-US&key=DEMO_KEY
Server response
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
        text: "foobaring",
        type: 1,
        lang: "en-US",
        creation_time: "2024-11-08T18:07:19+0000",
        suggestions: [],
        update_time: null,
        description: null,
    },
}

List of exceptions

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

List previously added exclusion words

Request parameters
Parameter Description
limit The maximum number of records in the result. No more than 500..
offset How many records ordered by text are skipped in the output. Used for paged output..
dictionary_id Not required. Dictionary (exception group) id. To get all exceptions of default dictionary you can use null value.
text Not required. Text filter.
type Not required. Exception type filter.
lang Not required. Language filter.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/custom/addexception?text=foobaring&key=DEMO_KEY
Server response
                                            
{
    status : true,
    response : {
        exceptions : [
            {
                id: 20,
                text: "foobaring",
                type: 1,
                lang: "en-US",
                creation_time: "2024-11-08T18:07:19+0000",
                update_time: null,
                description: null,
            },
        ],
    },
}

Remove exception

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

Remove the exception word for checking. If you try to delete a previously deleted word, no error occurs.

Request parameters
Parameter Description
id Exception ID to remove..
dictionary_id Dictionary Id. Can be any string up to 64 chars or null.
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/custom/deleteexception?id=20&key=DEMO_KEY
Server response
                                            
{
    status : true,
    response : {}
}