Textgears 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.

What can the API do?

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% serviceability 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, Italian, 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, 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
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
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/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 : "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"
            },
        ]
    }
}
                                            
                                        

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
https://api.textgears.com/readability?key=DEMO_KEY&text=...
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: 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,
            }
        }
    }
}
                                            
                                        

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
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 : {
        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
https://api.textgears.com/detect?key=DEMO_KEY&text=Some+test+words
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,
        }
    }
}
                                            
                                        

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
        }
    ]
}
                                            
                                        

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
exception Beginning of the period. Optional parameter..
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/custom/addexception?exception=foobaring&key=DEMO_KEY
Server response
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
    },
}
                                            
                                        

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..
key Your API key. Don’t you have a key? Get it in one click!.
Request example
https://api.textgears.com/custom/addexception?exception=foobaring&key=DEMO_KEY
Server response
                                            
{
    status : true,
    response : {
        id: 20, // New exception id
    },
}
                                            
                                        

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..
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 : {}
}