Looking to deliver contextual search results?

In this blog post we continue to explore another Cognitive Services API that belongs to the Search family – the Bing Entity Search.

The Bing Entity Search API lets you send a search query to Bing and fetch contextual results that contain entities and places. What does this mean though?

An entity result can include well-known people, tourist attractions, landmarks, states, countries, games, books, movies and much more. A place result can include a restaurant, hotel or business (note: Places response only supports US Business locations at this time). 

The Entity Search API can enhance your apps by exposing rich data from the Bing Knowledge Graph directly into your apps, and can be used in mobile and web applications, websites, and blogs for a more engaging experience, and augment your existing application’s intelligence.

The API also has features which allow you to present location specific information, ideal if you want to search for “restaurants near X postcode”.

The endpoint

The Bing Entity Search API has one endpoint but can accept a whole range of input parameters and return a rich object graph in the responses it sends. 

Here is the API endpoint for reference: https://api.cognitive.microsoft.com/bing/v7.0/entities

There are a number of input and output parameters (a few too many to list in this blog post), you can read more detailed information about these parameters and response objects here.

That said, you only need to supply two parameters to invoke your first request:

• q – the query / search term you wish to send to the API
• mkt – the market where the results come from

Consuming the Bing Entity Search API

The Bing Entity Search is straightforward to consume and, as always with any API in the Cognitive Service ecosystem, it can be consumed using a language of your choice.

You can use the dedicated SDK or you can manually construct the low-level REST requests and parse any JSON responses manually.

The process involves:

• Getting the relevant Cognitive Services key from your Azure Portal (you can create an account for free).
• Constructing a valid request.
• Processing the JSON message by parsing out the data returned by the Entity Search API.

As I’ve mentioned in the past, I prefer to build my own APIs in C#, that way I have full control over how the data is processed when it’s returned by an API. (You don’t need to do that, this is just my personal preference!)

This approach can mean you need to create custom objects and map JSON to specific properties as the data is returned, but NuGet packages such as JSON.NET and online services like http://jsonutils.com/ can speed this up.

Invoking the Bing Entity Search using Postman

Now that you understand what the Bing Entity Search API is capable of, let’s look at some sample code that shows you how to construct a request for the API and process the results!

I’ve used Postman in previous blog posts in this series so you’re probably familiar with that now. If not, Postman is a tool that lets you quickly test API endpoints with minimal fuss. It has plenty of other features and you can download Postman here.

In this screenshot, I’m ading the subscription key to the Headers Tab:

In this second screenshot, I’m doing the following:

• setting the parameter q to “i might buy a new iphone in the Verizon store in New York”
• setting the parameter mkt to “en-US”

When we send this request by clicking send, the Bing Entity Search API returns the following JSON, the key nodes to look for are:

• originalQuery: our original search term
• places: a collection of Places, each defined with information about a local entity
• _type: type hint, which may be set to (Hotel, Local Business or Restaurant)
• name: the entity’s name
• url: the URL to the entity’s website
• address: the postal address where the entity is located

A quick scan on the above JSON confirms that the API has identified several entities along with their respective address.

To confirm the information is valid from the API, you can take the webSearchURL value and paste this into your browser. The following information will be returned:

In this screenshot above we can see the Location, Zip Code and Phone Number match the data returned by the API!

Invoking the Search Endpoint with C#

We stay with the same search query “i might buy a new iphone in the Verizon store in New York” but this time, use C# to manually construct the web request.

You can see how it takes less than twenty lines of code to construct a request in C# and send it to the Bing Entity Search API in the code extract below:

We can run this Console Application and place a breakpoint on the code then use the JSON Visualiser to examine the data that gets returned from the Bing Entity Search API:

In the above screen shot, you can see I’m expanding the Places attribute which contains four child nodes. We can expand one of these which will show us address information:

What about Entities?

We’ve just ran through some examples that show how the Bing Entity Search API can fetch Place related information.

To see an example of the data that gets returned when Entities have been identified, update the query to contain “satya nadella“. You can do this either in code or in Postman.

When you submit this to the Bing Entity Search API, the JSON below is returned. Key nodes and attributes to look out for are:

• Entities: a collection of Entities
• Name: the entity’s name
• Image: an image of the entity
• Description:a short description of the entity

We just ran through some examples that show you how the Bing Entity Search API can provide you with structured data in the form of Place and Entity related data.

Full source code for this console application can be found on my GitHub repo.

Final Thoughts and Other Ideas

As you have seen, it’s easy to programmatically consume the Bing Entity Search API. Like other APIs we’ve looked at in this series, there is an active developer community, comprehensive set of examples and documentation to help you get up and running quickly.

I have some ideas as to how this API can be deployed:

Enhanced Reporting: Back in 2017 I built a dashboard which displayed Twitter analytics data for a product called Social Opinion. The Bing Entity Search API could be implemented here to surface additional insights in the form of Places or notable Entities within social media data.

Blend the Text Analytics API and Bing Entity Search API: Take this a step further, use the Cognitive Services Text Analytics API and Search Entity API together to identify the sentiment and key phrases, alongside the Places and Entity data. Run the Text Analytics API over online reviews for a given business address, or even aggregate data by postcode/zip code to find the most / least popular business locations.

Anti-Fraud: Sticking with business theme, use data returned from the Entity Search API to help identify fraudulent business locations.

Chatbots: When building chatbots with the Microsoft Bot Framework, use Entity Search within a chat application so users are able to invoke search for entities. For extra intelligence, the Language Understanding Intelligence Service (LUIS) can identify Entities in an Utterance.

See it in action

Visit the Bing Entity Search page to experience the API in action. Below is an example that can use several APIs:

• Entity API to provide information about Yosemite
• Image API to get images of Yosemite
• Local API to get address and locations near it

Summary

In this blog post we’ve introduced the Bing Entity Search API, we’ve explored some of the key features the API has to offer, the data it can return and walked through a code example of it in action.

Are you already using the API?  Drop a message down below!

Are you considering using the Bing Entity Search API in your software project but would benefit from a discussion with one of our Services Team before you start? Call them to discuss your use case: +44 (0)1364 654200.