Quickstart: Use the Bing Entity Search client library

Use this quickstart to begin searching for entities with the Bing Entity Search client library for C#. 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

• Any edition of Visual Studio 2017 or later.
• The Json.NET framework, available as a NuGet package.
• If you are using Linux/MacOS, this application can be run using Mono.
• The Bing News Search SDK NuGet package. Installing this package also installs the following:
  • Microsoft.Rest.ClientRuntime
  • Microsoft.Rest.ClientRuntime.Azure
  • Newtonsoft.Json

To add the Bing Entity Search client library to your Visual Studio project, use the Manage NuGet Packages option from Solution Explorer, and add the Microsoft.Azure.CognitiveServices.Search.EntitySearch package.

Create an Azure resource

Start using the Bing Entity Search API by creating one of the following Azure resources.

Bing Entity Search resource

• Available through the Azure portal until you delete the resource.
• Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
• Bing Entity Search is also offered in paid tiers of the Bing Search v7 resource.

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 an application

1. create a new C# console solution in Visual Studio. Then add the following into the main code file.

   using System;
   using System.Linq;
   using System.Text;
   using Microsoft.Azure.CognitiveServices.Search.EntitySearch;
   using Microsoft.Azure.CognitiveServices.Search.EntitySearch.Models;
   using Newtonsoft.Json;
   

Create a client and send a search request

1. Create a new search client. Add your subscription key by creating a new ApiKeyServiceClientCredentials.

   var client = new EntitySearchClient(new ApiKeyServiceClientCredentials("YOUR-ACCESS-KEY"));
   

2. Use the client's Entities.Search() function to search for your query:

   var entityData = client.Entities.Search(query: "Satya Nadella");
   

Get and print an entity description

1. If the API returned search results, get the main entity from entityData.

   var mainEntity = entityData.Entities.Value.Where(thing => thing.EntityPresentationInfo.EntityScenario == EntityScenario.DominantEntity).FirstOrDefault();
   

2. Print the description of the main entity

   Console.WriteLine(mainEntity.Description);
   

Next steps

• What is the Bing Entity Search API?

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 an Azure resource

Start using the Bing Entity Search API by creating one of the following Azure resources.

Bing Entity Search resource

• Available through the Azure portal until you delete the resource.
• Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
• Bing Entity Search is also offered in paid tiers of the Bing Search v7 resource.

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

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. You can use the global endpoint below, or the custom subdomain endpoint displayed in the Azure portal for your resource.

   public static EntitySearchAPIImpl getClient(final String subscriptionKey) {
       return new EntitySearchAPIImpl("https://api.cognitive.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?

Use this quickstart to begin searching for entities with the Bing Entity Search client library for JavaScript. 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 latest version of Node.js.
• The Bing Entity Search SDK for JavaScript
  • To install, run npm install @azure/cognitiveservices-entitysearch
• The CognitiveServicesCredentials class from @azure/ms-rest-azure-js package to authenticate the client.
  • To install, run npm install @azure/ms-rest-azure-js

Create an Azure resource

Start using the Bing Entity Search API by creating one of the following Azure resources.

Bing Entity Search resource

• Available through the Azure portal until you delete the resource.
• Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
• Bing Entity Search is also offered in paid tiers of the Bing Search v7 resource.

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 the application

1. Create a new JavaScript file in your favorite IDE or editor, and add the following requirements.

   const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
   const EntitySearchAPIClient = require('@azure/cognitiveservices-entitysearch');
   

2. Create an instance of CognitiveServicesCredentials using your subscription key. Then create an instance of the search client with it.

   let credentials = new CognitiveServicesCredentials('YOUR-ACCESS-KEY');
   let entitySearchApiClient = new EntitySearchAPIClient(credentials);
   

Send a request and receive a response

1. Send an entities search request with entitiesOperations.search(). After receiving a response, print out the queryContext, number of returned results, and the description of the first result.

   entitySearchApiClient.entitiesOperations.search('seahawks').then((result) => {
       console.log(result.queryContext);
       console.log(result.entities.value);
       console.log(result.entities.value[0].description);
   }).catch((err) => {
       throw err;
   });
   

Next steps

• What is the Bing Entity Search API?

Use this quickstart to begin searching for entities with the Bing Entity Search client library for Python. 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

• Python 2.x or 3.x

• The Bing Entity Search SDK for Python

It is recommended that you use a Python virtual environment. You can install and initialize a virtual environment with the venv module. You can install virtualenv with:

python -m venv mytestenv

Install the Bing Entity Search client library with:

cd mytestenv
python -m pip install azure-cognitiveservices-search-entitysearch

Create an Azure resource

Start using the Bing Entity Search API by creating one of the following Azure resources.

Bing Entity Search resource

• Available through the Azure portal until you delete the resource.
• Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
• Bing Entity Search is also offered in paid tiers of the Bing Search v7 resource.

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 the application

1. Create a new Python file in your favorite IDE or editor, and add the following import statements.

   from azure.cognitiveservices.search.entitysearch import EntitySearchClient
   from azure.cognitiveservices.search.entitysearch.models import Place, ErrorResponseException
   from msrest.authentication import CognitiveServicesCredentials
   

2. Create a variable for your subscription key and endpoint. Instantiate the client by creating a new CognitiveServicesCredentials object with your key.

   subscription_key = "YOUR-SUBSCRIPTION-KEY"
   endpoint = "YOUR-ENDPOINT"
   client = EntitySearchclient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))
   

Send a search request and receive a response

1. Send a search request to Bing Entity Search with client.entities.search() and a search query.

   entity_data = client.entities.search(query="Gibralter")
   

2. If entities were returned, convert entity_data.entities.value to a list, and print the first result.

   if entity_data.entities.value:
   
       main_entities = [entity for entity in entity_data.entities.value
                        if entity.entity_presentation_info.entity_scenario == "DominantEntity"]
   
       if main_entities:
           print(main_entities[0].description)
   

Next steps

• What is the Bing Entity Search API?