Spell check text strings

The Spell Check API lets you perform contextual grammar and spell checking.

What’s the difference between regular spell-checkers and Bing’s 3rd generation spell-checker? Current spell-checkers rely on verifying spelling and grammar against dictionary-based rule sets, which get updated and expanded periodically. In other words, the spell-checker is only as strong as the dictionary that supports it, and the editorial staff who supports the dictionary. You know this type of spell-checker from Microsoft Word and other word processors.

In contrast, Bing has developed a web-based spell-checker that leverages machine learning and statistical machine translation to dynamically train a constantly evolving and highly contextual algorithm. The spell-checker is based on a massive corpus of web searches and documents.

This spell-checker can handle any word-processing scenario:

  • Recognizes slang and informal language
  • Recognizes common name errors in context
  • Corrects word breaking issues with a single flag
  • Is able to correct homophones in context, and other difficult to spot errors
  • Supports new brands, digital entertainment, and popular expressions as they emerge
  • Words that sound the same but differ in meaning and spelling, for example “see” and “sea.”

Spell check modes

The API supports two proofing modes, Proof and Spell. The default mode is Proof. The Proof spelling mode provides the most comprehensive checks, but it's available only in the en-US (English-United States) market. For all other markets, set the mode query parameter to Spell. The Spell mode finds most spelling mistakes but doesn't find some of the grammar errors that Proof catches (for example, capitalization and repeated words).

POST vs. GET

The API supports either HTTP POST or HTTP GET. Which you use depends on the length of text you plan to proof. If the strings are always less than 1,500 character, you'd use a GET. But if you want to support strings up to 10,000 characters, you'd use POST. The text string may contain any valid UTF-8 character.

The following shows a POST request to check the spelling and grammar of a text string. The example includes the mode query parameter for completeness (it could have been left out since mode defaults to Proof). The text query parameter contains the string to be proofed.

POST https://api.cognitive.microsoft.com/bing/v7.0/spellcheck?mode=proof&mkt=en-us HTTP/1.1  
Content-Type: application/x-www-form-urlencoded  
Content-Length: 47  
Ocp-Apim-Subscription-Key: 123456789ABCDE  
X-MSEdge-ClientIP: 999.999.999.999  
X-Search-Location: lat:47.60357;long:-122.3295;re:100  
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>  
Host: api.cognitive.microsoft.com  

text=when+its+your+turn+turn,+john,+come+runing  

If you use HTTP GET, you'd include the text query parameter in the URL's query string

The following shows the response to the previous request. The response contains a SpellCheck object.

{  
    "_type" : "SpellCheck",  
    "flaggedTokens" : [{  
        "offset" : 5,  
        "token" : "its",  
        "type" : "UnknownToken",  
        "suggestions" : [{  
            "suggestion" : "it's",  
            "score" : 1  
        }]  
    },  
    {  
        "offset" : 25,  
        "token" : "john",  
        "type" : "UnknownToken",  
        "suggestions" : [{  
            "suggestion" : "John",  
            "score" : 1  
        }]  
    },  
    {  
        "offset" : 19,  
        "token" : "turn",  
        "type" : "RepeatedToken",  
        "suggestions" : [{  
            "suggestion" : "",  
            "score" : 1  
        }]  
    },  
    {  
        "offset" : 35,  
        "token" : "runing",  
        "type" : "UnknownToken",  
        "suggestions" : [{  
            "suggestion" : "running",  
            "score" : 1  
        }]  
    }]  
}  

The flaggedTokens field lists the spelling and grammar errors that the API found in the text string. The token field contains the word to be replaced. You'd use the zero-based offset in the offset field to find the token in the text string. You'd then replace the word at that location with the word in the suggestion field.

If the type field is RepeatedToken, you'd still replace the token with suggestion but you'd also likely need to remove the trailing space.

Throttling requests

The service and your subscription type determines the number of queries that you may make per second (QPS). You should ensure that your application includes the logic necessary to stay within your quota. If you exceed your QPS, the request fails with HTTP status code 429. The response also includes the Retry-After header, which contains the number of seconds that you should wait before sending another request.

Denial of Service (DOS) versus Throttling

The service differentiates between a DOS attack and QPS violation. If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK); however, the body of the response is empty.

Next steps

To get started quickly with your first request, see Making Your First Request.

Familiarize yourself with the Spell Check API Reference. The reference contains the list of endpoints, headers, and query parameters that you'd use to request search results, and the definitions of the response objects.

Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the results.