Quickstart: Send a search request to the Bing Entity Search REST API using C#

Warning

Bing Search APIs are moving from Cognitive Services to Bing Search Services. Starting October 30, 2020, any new instances of Bing Search need to be provisioned following the process documented here. Bing Search APIs provisioned using Cognitive Services will be supported for the next three years or until the end of your Enterprise Agreement, whichever happens first. For migration instructions, see Bing Search Services.

Use this quickstart to make your first call to the Bing Entity Search API and view the JSON response. This simple C# application sends a news search query to the API, and displays the response. The source code for this application is available on GitHub.

Although this application is written in C#, the API is a RESTful Web service compatible with most programming languages.

Prerequisites

Create an Azure resource

Start using the Bing Entity Search API by creating one of the following Azure resources.

Bing Entity Search 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 Entity Search is also offered in paid tiers of the Bing Search v7 resource.

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 C# console solution in Visual Studio.

  2. Add the Newtonsoft.Json NuGet package.

    1. Right-click your project in Solution Explorer.
    2. Select Manage NuGet Packages.
    3. Search for and select Newtonsoft.Json, and then install the package.
  3. Then, add the following namespaces into the main code file:

    using Newtonsoft.Json;
    using System;
    using System.Net.Http;
    using System.Text;
    
  4. Create a new class, and add variables for the API endpoint, your subscription key, and the query you want to search. You can use the global endpoint in the following code, or use the custom subdomain endpoint displayed in the Azure portal for your resource.

    namespace EntitySearchSample
    {
        class Program
        {
            static string host = "https://api.cognitive.microsoft.com";
            static string path = "/bing/v7.0/entities";
    
            static string market = "en-US";
    
            // NOTE: Replace this example key with a valid subscription key.
            static string key = "ENTER YOUR KEY HERE";
    
            static string query = "italian restaurant near me";
        //...
        }
    }
    

Send a request and get the API response

  1. Within the class, create a function called Search(). Within this function, create a new HttpClient object, and add your subscription key to the Ocp-Apim-Subscription-Key header.

  2. Construct the URI for your request by combining the host and path. Then, add your market and URL-encode your query.

  3. Await client.GetAsync() to get an HTTP response, and then store the JSON response by awaiting ReadAsStringAsync().

  4. Format the JSON string with JsonConvert.DeserializeObject() and print it to the console.

    async static void Search()
    {
     //...
     HttpClient client = new HttpClient();
     client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);
    
     string uri = host + path + "?mkt=" + market + "&q=" + System.Net.WebUtility.UrlEncode(query);
    
     HttpResponseMessage response = await client.GetAsync(uri);
    
     string contentString = await response.Content.ReadAsStringAsync();
     dynamic parsedJson = JsonConvert.DeserializeObject(contentString);
     Console.WriteLine(parsedJson);
    }
    
  5. In the Main() method of your application, call the Search() function.

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

Example JSON response

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

{
  "_type": "SearchResponse",
  "queryContext": {
    "originalQuery": "italian restaurant near me",
    "askUserForLocation": true
  },
  "places": {
    "value": [
      {
        "_type": "LocalBusiness",
        "webSearchUrl": "https://www.bing.com/search?q=sinful+bakery&filters=local...",
        "name": "Liberty's Delightful Sinful Bakery & Cafe",
        "url": "https://www.contoso.com/",
        "entityPresentationInfo": {
          "entityScenario": "ListItem",
          "entityTypeHints": [
            "Place",
            "LocalBusiness"
          ]
        },
        "address": {
          "addressLocality": "Seattle",
          "addressRegion": "WA",
          "postalCode": "98112",
          "addressCountry": "US",
          "neighborhood": "Madison Park"
        },
        "telephone": "(800) 555-1212"
      },

      . . .
      {
        "_type": "Restaurant",
        "webSearchUrl": "https://www.bing.com/search?q=Pickles+and+Preserves...",
        "name": "Munson's Pickles and Preserves Farm",
        "url": "https://www.princi.com/",
        "entityPresentationInfo": {
          "entityScenario": "ListItem",
          "entityTypeHints": [
            "Place",
            "LocalBusiness",
            "Restaurant"
          ]
        },
        "address": {
          "addressLocality": "Seattle",
          "addressRegion": "WA",
          "postalCode": "98101",
          "addressCountry": "US",
          "neighborhood": "Capitol Hill"
        },
        "telephone": "(800) 555-1212"
      },
      
      . . .
    ]
  }
}

Next steps