Quickstart: Get image insights using the Bing Visual Search REST API and Java

Article
05/22/2020

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 make your first call to the Bing Visual Search API. This Java application uploads an image to the API and displays the information it returns. Although this application is written in Java, the API is a RESTful Web service compatible with most programming languages.

Prerequisites

Create an Azure resource

Start using the Bing Visual Search API by creating one of the following Azure resources:

Bing Search v7 resource

Available through the Azure portal until you delete the resource.
Select the S9 pricing tier.

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 a project

Create a new Java project in your favorite IDE or editor, and import the following libraries:

import java.util.*;
import java.io.*;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

// HttpClient libraries

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;

Create variables for your API endpoint, subscription key, and the path to your image. For the endpoint 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.
```
static String endpoint = "https://api.cognitive.microsoft.com/bing/v7.0/images/visualsearch";
static String subscriptionKey = "your-key-here";
static String imagePath = "path-to-your-image";
```
When you upload a local image, the form data must include the Content-Disposition header. Set its name parameter to "image", and set the filename parameter to the file name of the image. The contents of the form include the binary data of the image. The maximum image size you can upload is 1 MB.
```
--boundary_1234-abcd
Content-Disposition: form-data; name="image"; filename="myimagefile.jpg"

ÿØÿà JFIF ÖÆ68g-¤CWŸþ29ÌÄøÖ‘º«™æ±èuZiÀ)"óÓß°Î= ØJ9á+*G¦...

--boundary_1234-abcd--
```

Create the JSON parser

Create a method to make the JSON response from the API more readable by using JsonParser.

public static String prettify(String json_text) {
        JsonParser parser = new JsonParser();
        JsonObject json = parser.parse(json_text).getAsJsonObject();
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        return gson.toJson(json);
    }

Construct the search request and query

In the main method of your application, create an HTTP client using HttpClientBuilder.create().build();.
```
CloseableHttpClient httpClient = HttpClientBuilder.create().build();
```

Create an HttpEntity object to upload your image to the API.

HttpEntity entity = MultipartEntityBuilder
    .create()
    .addBinaryBody("image", new File(imagePath))
    .build();

Create an httpPost object with your endpoint, and set the header to use your subscription key.

HttpPost httpPost = new HttpPost(endpoint);
httpPost.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
httpPost.setEntity(entity);

Receive and process the JSON response

Use the HttpClient.execute() method to send a request to the API, and store the response in an InputStream object.

HttpResponse response = httpClient.execute(httpPost);
InputStream stream = response.getEntity().getContent();

Store the JSON string, and print the response.

String json = new Scanner(stream).useDelimiter("\\A").next();
System.out.println("\nJSON Response:\n");
System.out.println(prettify(json));

Next steps

Build a Visual Search single-page web app