Tutorial: Extract image details using the Bing Image Search API and C#

  • Article

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.

There are multiple endpoints available through the Bing Image Search API. The /details endpoint accepts a POST request with an image, and can return a variety of details about the image. This C# application sends an image using this API, and displays the details returned by Bing, which are JSON objects, such as the following:

[JSON results]

This tutorial explains how to:

  • Use the Image Search /details endpoint in a POST request
  • Specify headers for the request
  • Use URL parameters to specify results
  • Upload the image data and send the POST request
  • Print the JSON results to the console

Prerequisites

Construct an image details search request

The following is the /details endpoint, which accepts POST requests with image data in the body of the request. You can use the global endpoint below, or the custom subdomain endpoint displayed in the Azure portal for your resource.

https://api.cognitive.microsoft.com/bing/v7.0/images/details

When constructing the search request URL, the modules parameter follows the above endpoint, and specifies the types of details the results will contain:

  • modules=All
  • modules=RecognizedEntities (people or places visible in the image)

Specify modules=All in the POST request to get JSON text that includes the following:

  • bestRepresentativeQuery - a Bing query that returns images similar to the uploaded image
  • detectedObjects - objects found in the image
  • image - metadata for the image
  • imageInsightsToken - a token for a later GET requests that get RecognizedEntities (people or places visible in the image) from the image.
  • imageTags - tags for the image
  • pagesIncluding - Web pages that include the image
  • relatedSearches - searches based on details in the image.
  • visuallySimilarImages - similar images on the web.

Specify modules=RecognizedEntities in the POST request to only get imageInsightsToken, which can be used in a subsequent GET request to identify people or places in the image.

Create a WebClient object, and set headers for the API request

Create a WebClient object, and set the headers. All requests to the Bing Search API require an Ocp-Apim-Subscription-Key. A POST request to upload an image must also specify ContentType: multipart/form-data.

WebClient client = new WebClient();
client.Headers["Ocp-Apim-Subscription-Key"] = accessKey;
client.Headers["ContentType"] = "multipart/form-data";

Upload the image, and display the results

The WebClient class's UpLoadFile() method formats data for the POST request, including formatting RequestStream and calling HttpWebRequest.

Call WebClient.UpLoadFile() with the /details endpoint and the image file to upload. Use the JSON response to initialize an instance of the SearchResult structure, and store the response.

const string uriBase = "https://api.cognitive.microsoft.com/bing/v7.0/images/details";
// The image to upload. Replace with your file and path.
const string imageFile = "your-image.jpg";
byte[] resp = client.UploadFile(uriBase + "?modules=All", imageFile);
var json = System.Text.Encoding.Default.GetString(resp);
// Create result object for return
var searchResult = new SearchResult()
{
    jsonResult = json,
    relevantHeaders = new Dictionary<String, String>()
};

This JSON response can then be printed to the console.

Use an image insights token in a request

To use the ImageInsightsToken returned with results of a POST, you can add it to a GET request. For example:

https://api.cognitive.microsoft.com/bing/v7.0/images/details?InsightsToken="bcid_A2C4BB81AA2C9EF8E049C5933C546449*ccid_osS7gaos*mid_BF7CC4FC4A882A3C3D56E644685BFF7B8BACEAF2

If there are identifiable people or places in the image, this request will return information about them.

Next steps

Display images and search options in a single-page Web app

See also