Quickstart: Call your Bing Custom Search endpoint using C#

Warning

On October 30, 2020, the Bing Search APIs moved from Azure AI services to Bing Search Services. This documentation is provided for reference only. For updated documentation, see the Bing search API documentation. For instructions on creating new Azure resources for Bing search, see Create a Bing Search resource through the Azure Marketplace.

Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in C#, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on GitHub.

Prerequisites

• A Bing Custom Search instance. For more information, see Quickstart: Create your first Bing Custom Search instance.

• Microsoft .NET Core.

• Any edition of Visual Studio 2019 or later.

• If you're using Linux/MacOS, this application can be run using Mono.

• The Bing Custom Search NuGet package.

  To install this package in Visual Studio:

  1. Right-click your project in Solution Explorer, and then select Manage NuGet Packages.
  2. Search for and select Microsoft.Azure.CognitiveServices.Search.CustomSearch, and then install the package.

  When you install the Bing Custom Search NuGet package, Visual Studio also installs the following packages:

  • Microsoft.Rest.ClientRuntime
  • Microsoft.Rest.ClientRuntime.Azure
  • Newtonsoft.Json

Create an Azure resource

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

Bing Custom 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.

Multi-Service resource

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

Create and initialize the application

1. Create a new C# console application in Visual Studio. Then, add the following packages to your project:

   using System;
   using System.Net.Http;
   using System.Web;
   using Newtonsoft.Json;
   

2. Create the following classes to store the search results returned by the Bing Custom Search API:

   public class BingCustomSearchResponse {        
       public string _type{ get; set; }            
       public WebPages webPages { get; set; }
   }
   
   public class WebPages {
       public string webSearchUrl { get; set; }
       public int totalEstimatedMatches { get; set; }
       public WebPage[] value { get; set; }        
   }
   
   public class WebPage {
       public string name { get; set; }
       public string url { get; set; }
       public string displayUrl { get; set; }
       public string snippet { get; set; }
       public DateTime dateLastCrawled { get; set; }
       public string cachedPageUrl { get; set; }
   }
   

3. In the main method of your project, create the following variables for your Bing Custom Search API subscription key, search instance's custom configuration ID, and search term:

   var subscriptionKey = "YOUR-SUBSCRIPTION-KEY";
   var customConfigId = "YOUR-CUSTOM-CONFIG-ID";
   var searchTerm = args.Length > 0 ? args[0]:"microsoft";
   

4. Construct the request URL by appending your search term to the q= query parameter, and your search instance's custom configuration ID to the customconfig= parameter. Separate the parameters with an ampersand (&). For the url variable value, you can use the global endpoint in the following code, or use the custom subdomain endpoint displayed in the Azure portal for your resource.

   var url = "https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/search?" +
               "q=" + searchTerm + "&" +
               "customconfig=" + customConfigId;
   

Send and receive a search request

1. Create a request client, and add your subscription key to the Ocp-Apim-Subscription-Key header.

   var client = new HttpClient();
   client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
   

2. Perform the search request and get the response as a JSON object.

   var httpResponseMessage = client.GetAsync(url).Result;
   var responseContent = httpResponseMessage.Content.ReadAsStringAsync().Result;
   BingCustomSearchResponse response = JsonConvert.DeserializeObject<BingCustomSearchResponse>(responseContent);
   

Process and view the results

• Iterate over the response object to display information about each search result, including its name, url, and the date the webpage was last crawled.

  for(int i = 0; i < response.webPages.value.Length; i++) {                
      var webPage = response.webPages.value[i];
  
      Console.WriteLine("name: " + webPage.name);
      Console.WriteLine("url: " + webPage.url);                
      Console.WriteLine("displayUrl: " + webPage.displayUrl);
      Console.WriteLine("snippet: " + webPage.snippet);
      Console.WriteLine("dateLastCrawled: " + webPage.dateLastCrawled);
      Console.WriteLine();
  }
  Console.WriteLine("Press any key to exit...");
  Console.ReadKey();
  

Next steps

Build a Custom Search web app