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

Article
12/06/2019

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

Any edition of Visual studio 2017 or later.

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

Share via