Quickstart: Use the Bing Entity Search client library

Article
03/06/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 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

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

Create a new search client. Add your subscription key by creating a new ApiKeyServiceClientCredentials.
```
var client = new EntitySearchClient(new ApiKeyServiceClientCredentials("YOUR-ACCESS-KEY"));
```
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

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();

Print the description of the main entity

Console.WriteLine(mainEntity.Description);

Next steps

Create a single-page web app

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

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;

Create a variable for your subscription key
```
String subscriptionKey = "your-key-here"
```

Create a search client

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:

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

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

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 {
        //...    
        }
    });
///...

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

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);

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

Build a single-page web app

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

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');

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

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

Create a single-page web app

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

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

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

Send a search request to Bing Entity Search with client.entities.search() and a search query.
```
entity_data = client.entities.search(query="Gibralter")
```

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

Create a single-page web app

What is the Bing Entity Search API?

Quickstart: Use the Bing Entity Search client library

Prerequisites

Create an Azure resource

Create and initialize an application

Create a client and send a search request

Get and print an entity description

Next steps

Prerequisites

Create an Azure resource

Create and initialize a project

Create a search client

Send a request and receive a response

Next steps

Prerequisites

Create an Azure resource

Create and initialize the application

Send a request and receive a response

Next steps

Prerequisites

Create an Azure resource

Create and initialize the application

Send a search request and receive a response

Next steps

Additional resources