Quickstart: Check spelling with the Bing Spell Check REST API and C#

Use this quickstart to make your first call to the Bing Spell Check REST API. This simple C# application sends a request to the API and returns a list of suggested corrections. While this application is written in C#, the API is a RESTful Web service compatible with most programming languages. The source code for this application is available on GitHub.

Prerequisites

  • Any edition of Visual Studio 2017 or later.
  • To install Newtonsoft.Json as a NuGet package in Visual studio:
    1. In Solution Explorer, right-click the Solution file.
    2. Select Manage NuGet Packages for Solution.
    3. Search for Newtonsoft.Json and install the package.
  • If you're using Linux/MacOS, this application can be run using Mono.

You must have a Cognitive Services API account with access to the Bing Spell Check API. If you don't have an Azure subscription, you can create an account for free. Before continuing, You will need the access key provided after activating your free trial, or a paid subscription key from your Azure dashboard.

Create and initialize a project

  1. Create a new console solution named SpellCheckSample in Visual Studio. Then add the following namespaces into the main code file.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;
    using Newtonsoft.Json;
    
  2. Create variables for the API endpoint, your subscription key, and the text to be spell checked.

    namespace SpellCheckSample
    {
        class Program
        {
            static string host = "https://api.cognitive.microsoft.com";
            static string path = "/bing/v7.0/spellcheck?";
            static string key = "<ENTER-KEY-HERE>";
            //text to be spell-checked
            static string text = "Hollo, wrld!";
        }
    }
    
  3. Create a variable for your search parameters. 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).

    static string params_ = "mkt=en-US&mode=proof";
    

Create and send a spell check request

  1. Create an asynchronous function called SpellCheck() to send a request to the API. Create a HttpClient, and add your subscription key to the Ocp-Apim-Subscription-Key header. Then perform the following steps within the function.

    async static void SpellCheck()
    {
        HttpClient client = new HttpClient();
        client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);
    
        HttpResponseMessage response = new HttpResponseMessage();
        // add the rest of the code snippets here (except for main())...
    }
    
  2. Create the URI for your request by appending your host, path, and parameters.

    string uri = host + path + params_;
    
  3. Create a list with a KeyValuePair object containing your text, and use it to create a FormUrlEncodedContent object. Set the header information, and use PostAsync() to send the request.

    List<KeyValuePair<string, string>> values = new List<KeyValuePair<string, string>>();
    values.Add(new KeyValuePair<string, string>("text", text));
    
    using (FormUrlEncodedContent content = new FormUrlEncodedContent(values))
    {
        content.Headers.ContentType = new MediaTypeHeaderValue("application/x-www-form-urlencoded");
        response = await client.PostAsync(uri, content);
    }
    

Get and print the API response

Get the client ID header

If the response contains an X-MSEdge-ClientID header, get the value and print it.

string client_id;
if (response.Headers.TryGetValues("X-MSEdge-ClientID", out IEnumerable<string> header_values))
{
    client_id = header_values.First();
    Console.WriteLine("Client ID: " + client_id);
}

Get the response

Get the response from the API. Deserialize the JSON object, and print it to the console.

string contentString = await response.Content.ReadAsStringAsync();

dynamic jsonObj = JsonConvert.DeserializeObject(contentString);
Console.WriteLine(jsonObj);

Call the spell check function

In the Main function of your project, call SpellCheck().

static void Main(string[] args)
{
    SpellCheck();
    Console.ReadLine();
}

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