Quickstart: Use the Bing Entity Search Java client library

Use this quickstart to begin searching for entities with the Bing Entity Search client library for Java. While Bing Entity 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 sample can be found on GitHub.

Prerequisites

• The Java Development Kit (JDK).

• The Bing Entity Search client library for Java.

Install the Bing Entity Search client library dependencies by using Maven, Gradle, or another dependency management system. The Maven POM file requires the declaration:

<dependency>
  <groupId>com.microsoft.azure.cognitiveservices</groupId>
  <artifactId>azure-cognitiveservices-entitysearch</artifactId>
  <version>1.0.2</version>
</dependency>

Create and initialize a project

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

   import com.microsoft.azure.cognitiveservices.entitysearch.*;
   import com.microsoft.azure.cognitiveservices.entitysearch.implementation.EntitySearchAPIImpl;
   import com.microsoft.azure.cognitiveservices.entitysearch.implementation.SearchResponseInner;
   import com.microsoft.rest.credentials.ServiceClientCredentials;
   import okhttp3.Interceptor;
   import okhttp3.OkHttpClient;
   import okhttp3.Request;
   import okhttp3.Response;
   
   import java.io.IOException;
   import java.util.ArrayList;
   import java.util.List;
   

2. Create a variable for your subscription key.

   String subscriptionKey = "your-key-here"
   

Create a search client

1. Implement the dominantEntityLookup client, which requires your API endpoint, and an instance of the ServiceClientCredentials class.

   public static EntitySearchAPIImpl getClient(final String subscriptionKey) {
       return new EntitySearchAPIImpl("https://api.bing.microsoft.com/bing/v7.0/",
               new ServiceClientCredentials() {
               //...
               }
   )};
   

   To implement the ServiceClientCredentials, follow these steps:

   1. Override the applyCredentialsFilter() function, with a OkHttpClient.Builder object as a parameter.

      //...
      new ServiceClientCredentials() {
              @Override
              public void applyCredentialsFilter(OkHttpClient.Builder builder) {
              //...
              }
      //...
      

   2. Within applyCredentialsFilter(), call builder.addNetworkInterceptor(). Create a new Interceptor object, and override its intercept() method to take a Chain interceptor object.

      //...
      builder.addNetworkInterceptor(
          new Interceptor() {
              @Override
              public Response intercept(Chain chain) throws IOException {
              //...    
              }
          });
      ///...
      

   3. Within the intercept function, create variables for your request. Use Request.Builder() to build your request. Add your subscription key to the Ocp-Apim-Subscription-Key header, and return chain.proceed() on the request object.

      //...
      public Response intercept(Chain chain) throws IOException {
          Request request = null;
          Request original = chain.request();
          Request.Builder requestBuilder = original.newBuilder()
                  .addHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
          request = requestBuilder.build();
          return chain.proceed(request);
      }
      //...
      

Send a request and receive a response

1. Create a new instance of the search client with your subscription key. Use client.entities().search() to send a search request for the search query satya nadella, and get a response.

   EntitySearchAPIImpl client = getClient(subscriptionKey);
   SearchResponseInner entityData = client.entities().search(
           "satya nadella", null, null, null, null, null, null, "en-us", null, null, SafeSearch.STRICT, null);
   

2. If any entities were returned, convert them into a list. Iterate through them, and print the dominant entity.

   if (entityData.entities().value().size() > 0){
       // Find the entity that represents the dominant entity
       List<Thing> entries = entityData.entities().value();
       Thing dominateEntry = null;
       for(Thing thing : entries) {
           if(thing.entityPresentationInfo().entityScenario() == EntityScenario.DOMINANT_ENTITY) {
               System.out.println("\r\nSearched for \"Satya Nadella\" and found a dominant entity with this description:");
               System.out.println(thing.description());
               break;
           }
       }
   }
   

Next steps

• What is the Bing Entity Search API?