Quickstart: Check spelling with the Bing Spell Check REST API and Node.js

Use this quickstart to make your first call to the Bing Spell Check REST API. This simple Node application sends a request to the API and returns a list of words it didn't recognize, followed by suggested corrections. While this application is written in Node.js, the API is a RESTful Web service compatible with most programming languages. The source code for this application is available on GitHub.

Prerequisites

Create an Azure resource

Start using the Bing Spell Check API by creating one of the Azure resources below.

  • Create a trial resource:

    • No Azure subscription needed.
    • Valid for seven days, for free. After signing up, a trial key and endpoint will be available on the Azure website.
  • Create a Bing Spell Check resource:

    • Available through the Azure portal until you delete the resource.
    • Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
    • Bing Spell Check API is also offered in some tiers of the Bing Search v7 resource.
  • Create a Multi-Service resource:

    • Available through the Azure portal until you delete the resource.
    • Use the same key and endpoint for your applications, across multiple Cognitive Services.

Create and initialize a project

  1. Create a new JavaScript file in your favorite IDE or editor. Set the strictness, and require https. Then create variables for your API endpoint's host, path, and your subscription key. You can use the global endpoint below, or the custom subdomain endpoint displayed in the Azure portal for your resource.

    'use strict';
    let https = require ('https');
    
    let host = 'api.cognitive.microsoft.com';
    let path = '/bing/v7.0/spellcheck';
    let key = '<ENTER-KEY-HERE>';
    
  2. Create variables for your search parameters and the text you want to check. Append your market code after mkt=. The market code is the country you make the request from. Also, append your spell-check mode after &mode=. Mode is either proof (catches most spelling/grammar errors) or spell (catches most spelling but not as many grammar errors).

    let mkt = "en-US";
    let mode = "proof";
    let text = "Hollo, wrld!";
    let query_string = "?mkt=" + mkt + "&mode=" + mode;
    

Create the request parameters

Create your request parameters by creating a new object with a POST method. Add your path by appending your endpoint path, and query string. Add your subscription key to the Ocp-Apim-Subscription-Key header.

let request_params = {
   method : 'POST',
   hostname : host,
   path : path + query_string,
   headers : {
   'Content-Type' : 'application/x-www-form-urlencoded',
   'Content-Length' : text.length + 5,
      'Ocp-Apim-Subscription-Key' : key,
   }
};

Create a response handler

Create a function called response_handler to take the JSON response from the API, and print it. Create a variable for the response body. Append the response when a data flag is received, using response.on(). When a end flag is received, print the JSON body to the console.

let response_handler = function (response) {
    let body = '';
    response.on ('data', function (d) {
        body += d;
    });
    response.on ('end', function () {
        let body_ = JSON.parse (body);
        console.log (body_);
    });
    response.on ('error', function (e) {
        console.log ('Error: ' + e.message);
    });
};

Send the request

Call the API using https.request() with your request parameters, and response handler. Write your text to the API, and end the request afterwards.

let req = https.request (request_params, response_handler);
req.write ("text=" + text);
req.end ();

Run the application

Build and run your project.

If you're using the command line, use the following commands to build and run the application.

node <FILE_NAME>.js

Example JSON response

A successful response is returned in JSON, as shown in the following example:

{
   "_type": "SpellCheck",
   "flaggedTokens": [
      {
         "offset": 0,
         "token": "Hollo",
         "type": "UnknownToken",
         "suggestions": [
            {
               "suggestion": "Hello",
               "score": 0.9115257530801
            },
            {
               "suggestion": "Hollow",
               "score": 0.858039839213461
            },
            {
               "suggestion": "Hallo",
               "score": 0.597385084464481
            }
         ]
      },
      {
         "offset": 7,
         "token": "wrld",
         "type": "UnknownToken",
         "suggestions": [
            {
               "suggestion": "world",
               "score": 0.9115257530801
            }
         ]
      }
   ]
}

Next steps