Quickstart: Use the Bing Visual Search Java client library

Use this quickstart to begin getting image insights from the Bing Visual Search service, using the Java client library. While Bing Visual Search has a REST API compatible with most programming languages, the client library provides an easy way to integrate the service into your applications. The source code for this quickstart can be found on GitHub.

Use the Bing Visual Search client library for Java to:

  • Upload an image to send a visual search request.
  • Get the image insight token and visual search tags.

Reference documentation | Library source code | Artifact (Maven) | Samples

Prerequisites

After you get a key from your resource, create an environment variable for the key, named BING_SEARCH_V7_SUBSCRIPTION_KEY.

Create a new Gradle project

In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.

mkdir myapp && cd myapp

Run the gradle init command from your working directory. This command will create essential build files for Gradle, including build.gradle.kts which is used at runtime to create and configure your application.

gradle init --type basic

When prompted to choose a DSL, select Kotlin.

Locate build.gradle.kts and open it with your preferred IDE or text editor. Then copy in this build configuration:

plugins {
    java
    application
}
application {
    mainClassName = "main.java.BingVisualSearchSample"
}
repositories {
    mavenCentral()
}
dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-visualsearch:1.0.2-beta")
    compile("com.google.code.gson:gson:2.8.5")
}

Create a folder for your sample app. From your working directory, run the following command:

mkdir -p src/main/java

Create a folder for the image you want to upload to the API. Place the image inside the resources folder.

mkdir -p src/main/resources

Navigate to the new folder and create a file called BingVisualSearchSample.java. Open it in your preferred editor or IDE and add the following import statements:

package main.java;

import com.google.common.io.ByteStreams;
import com.google.gson.Gson;
import com.microsoft.azure.cognitiveservices.search.visualsearch.BingVisualSearchAPI;
import com.microsoft.azure.cognitiveservices.search.visualsearch.BingVisualSearchManager;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.CropArea;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ErrorResponseException;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.Filters;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageInfo;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageKnowledge;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageTag;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.KnowledgeRequest;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.VisualSearchRequest;```

Then create a new class.

```java
public class BingVisualSearchSample {
}

In the application's main method, create variables for your resource's Azure endpoint and key. If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable. Then create a byte[] for the image you'll be uploading. Create a try block for the methods you'll define later, and load the image and convert it to bytes using toByteArray().

    public static void main(String[] args) {

        // Set the BING_SEARCH_V7_SUBSCRIPTION_KEY environment variable with your subscription key,
        // then reopen your command prompt or IDE. If not, you may get an API key not found exception.
        final String subscriptionKey = System.getenv("BING_SEARCH_V7_SUBSCRIPTION_KEY");

        BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

        //runSample(client);
        byte[] imageBytes;

        try {
            imageBytes = ByteStreams.toByteArray(ClassLoader.getSystemClassLoader().getResourceAsStream("image.jpg"));
            visualSearch(client, imageBytes);
            searchWithCropArea(client, imageBytes);
            // wait 1 second to avoid rate limiting
            Thread.sleep(1000);
            searchWithFilter(client);
            searchUsingCropArea(client);
            searchUsingInsightToken(client);
        }
        catch (java.io.IOException f) {
            System.out.println(f.getMessage());
            f.printStackTrace();
        }
        catch (java.lang.InterruptedException f){
            f.printStackTrace();
        }

    }

Install the client library

This quickstart uses the Gradle dependency manager. You can find the client library and information for other dependency managers on the Maven Central Repository.

In your project's build.gradle.kts file, be sure to include the client library as an implementation statement.

dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-visualsearch:1.0.2-beta")
    compile("com.google.code.gson:gson:2.8.5")
}

Code examples

These code snippets show you how to do the following tasks with the Bing Visual Search client library and Java:

Authenticate the client

Note

This quickstart assumes you've created an environment variable for your Bing Visual Search key, named BING_SEARCH_V7_SUBSCRIPTION_KEY.

In your main method, be sure to use your subscription key to instantiate a BingVisualSearchAPI object.

BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

Send a visual search request

In a new method, send the image byte array (which was created in the main() method) using the client's bingImages().visualSearch() method.

    public static void visualSearch(BingVisualSearchAPI client, byte[] imageBytes){
        System.out.println("Calling Bing Visual Search with image binary");
        ImageKnowledge visualSearchResults = client.bingImages().visualSearch()
                .withImage(imageBytes)
                .execute();
        PrintVisualSearchResults(visualSearchResults);

    }

Check if the ImageKnowledge object is null. If not, print the image insights token, the number of tags, the number of actions, and the first action type.

    static void PrintVisualSearchResults(ImageKnowledge visualSearchResults) {
        if (visualSearchResults == null) {
            System.out.println("No visual search result data.");
        } else {
            // Print token

            if (visualSearchResults.image() != null && visualSearchResults.image().imageInsightsToken() != null) {
                System.out.println("Found uploaded image insights token: " + visualSearchResults.image().imageInsightsToken());
            } else {
                System.out.println("Couldn't find image insights token!");
            }

            // List tags

            if (visualSearchResults.tags() != null && visualSearchResults.tags().size() > 0) {
                System.out.format("Found visual search tag count: %d\n", visualSearchResults.tags().size());
                ImageTag firstTagResult = visualSearchResults.tags().get(0);

                // List of actions in first tag

                if (firstTagResult.actions() != null && firstTagResult.actions().size() > 0) {
                    System.out.format("Found first tag action count: %d\n", firstTagResult.actions().size());
                    System.out.println("Found first tag action type: " + firstTagResult.actions().get(0).actionType());
                }
            } else {
                System.out.println("Couldn't find image tags!");
            }
        }
    }

Run the application

You can build the app with:

gradle build

Run the application with the run goal:

gradle run

Next steps