NAV
HTTP JavaScript

Bing Knowledge Graph API

Enhance any app by leveraging Bing’s world-class Knowledge Graph API to identify the things (entities) your users search for, and augment those entities with rich information and relationships from the Bing Knowledge Graph.

For illustration only; the real API has more information and structure than this example.

{
  "name": "Bill Gates",
  "born": 1955,
  "children": ["Jennifer", "Phoebe", "Rory"],
  "writtenWorks": ["The Road Ahead", ...],
  "alsoSearchedFor": ["Steve Jobs", "Warren Buffett", ...]
}

For instance, if I search for Bill Gates, the Bing Knowlege Graph API will tell me he was born in 1955, that he has three children, that he has a relationship to “The Road Ahead” (a book he authored), and that people who search for Bill Gates also search for Steve Jobs and Warren Buffett.

The Bing Knowledge Graph API uses common Web technologies like HTTP, JSON, and OAuth. This makes the API easy to consume from any programming language with an HTTP stack (i.e., all of them).

A couple quick pointers for getting started:

  1. Check out the 5-minute quickstart to make your first few API calls in less than five minutes (less than a minute if you already have HTTP tools installed).
  2. Use the pane to the right to see examples in your language of choice. If there is no pane to the right, you can change the language in the menu (collapsed to the left).

5-Minute Quickstart

To try out the Bing Knowledge Graph API, simply use the URL https://api.cognitive.microsoft.com/bing/v5.0/knowledge?q=who+is+bill+gates&detectEntities=true&subscription-key=791795f2ae234e3da503354bbafeafce.

You can use subscription key 791795f2ae234e3da503354bbafeafce to experiment with the Bing Knowledge Graph API. This key works against the real API, but it is restricted to a small set of predefined search terms.

# Note: On Windows '\' needs to be replaced with '^'.
$ curl https://api.cognitive.microsoft.com/bing/v5.0/knowledge\
?q=who+is+bill+gates\
&detectEntities=true\
&subscription-key=791795f2ae234e3da503354bbafeafce
$.get("https://api.cognitive.microsoft.com/bing/v5.0/knowledge?q=who+is+bill+gates&detectEntities=true&subscription-key=791795f2ae234e3da503354bbafeafce");

Getting started with the Bing Knowledge Graph API is incredibly simple. In fact, if you have Postman installed (Chrome | Windows x64 | Mac), you can get started with just a click!

Run in Postman

If you don’t have Postman, you can use your HTTP tool of choice: cURL, Fiddler (Windows | Mac/Linux), Charles, or even your Web browser.

To query Bing Search, supply two key pieces of data:

  1. A subscription key. You can get a feel for the API with the experimental subscription key 791795f2ae234e3da503354bbafeafce. This key will only allow a few different searches, so for anything beyond the basics you’ll want to sign up for your own app id.
  2. A query. Usually it’s best to use q={{query}} and detectEntities=true.

SDKs

Even though the Bing Knowledge Graph API is pure HTTP + JSON, accessing the API via an SDK simplifies many common tasks, especially if you’re using the OAuth flow for authentication.

We are currently hard at work on SDKs for JavaScript and .NET.

Authentication

You have two options for authenticating against the Bing Knowledge Graph API:

  1. Traditional API key approach, which is a simple approach if you have an intermediary server layer.
  2. OAuth 2.0, which is a great option if you are writing a client that will directly access the Bing Knowledge Graph API.

In either case, you’ll need a subscription key to get started. During the preview you can use the same subscription key you use for the Bing Web Search API. If you don’t have a subscription key yet, you can sign up via Microsoft Cognitive Services.

Subcription Key (AKA API Key)

# Note: On Windows '\' needs to be replaced with '^'.
# Query string parameter usage:
$ curl https://api.cognitive.microsoft.com/bing/v5.0/knowledge\
?q=who+is+bill+gates\
&detectEntities=true\
&subscription-key=791795f2ae234e3da503354bbafeafce

# Header usage:
$ curl https://api.cognitive.microsoft.com/bing/v5.0/knowledge\
?q=who+is+bill+gates\
&detectEntities=true
 --header "Ocp-Apim-Subscription-Key=791795f2ae234e3da503354bbafeafce"

Once you have a subscription key, you can use it in one of two places: the Ocp-Apim-Subscription-Key header or the subscription-key query string parameter.

Experimental Key

The experimental key (791795f2ae234e3da503354bbafeafce) may be used to get a feel for the API even before committing to sign up for a trial API key. The experimental key is constrained in two ways:

  1. The experimental key can only be used for a few queries per second. If other developers are trying out the API with the experimental key, a 429 response may be returned. If you’re not able to try the API within a reasonable period of time, please let us know.
  2. The experimental key is restricted to searching for a few predefined query terms. This will let you get a feel for the type of information the API will return, but obviously encourages developers to sign up for a trial API key.

Get A Key

You can request a trial subscription key by visiting the Cognitive Services subscriptions page and signing up for the Bing Web Search API. For the preview period, this subscription key will allow you to access the Bing Knowledge Graph API.

OAuth 2.0

// TODO: Coming soon

API Reference

The Bing Knowledge Graph API definition is also available from the Azure API Management endpoint, or it can be downloaded in Swagger or WADL format.

Endpoint

The endpoint for the Bing Knowledge Graph API is https://api.cognitive.microsoft.com/bing/{version}/knowledge. The only current supported version is v5.0.

Response Formats

The Bing Knowledge Graph API supports JSON responses. The API will default to returning JSON if the Accept header is set to */*. To explicitly request a JSON response, set the Accept header to application/json.

Basic Query

The query string parameter q is required for all requests. The parameter value is the string that will be used to detect entities.

Detecting entities

Another important query string parameter is detectEntities. If set to false, entity detection will be very basic, returning entities in the case where the majority of the query constitutes an entity. If set to true, more sophisticated entity detection will apply. This will delay the response some, but will have more success at finding entities in the query text.

Additional Headers

Request

Header Required Example QSP Alternative Description
Accept No Accept:application/json responseFormat Controls the response format. If unspecified, defaults to application/json. Supported values: application/json, application/ld+json.
Accept-Language No Accept-Language:en-us setLang Controls the language of UI strings in the response. If unspecified, defaults to en-us. Other locales are currently unsupported.
Ocp-Apim-Subscription-Key Yes Ocp-Apim-Subscription-Key:791795f2ae234e3da503354bbafeafce None Contains the subscription key used to access the Bing Knowledge Graph API.

Response

// TODO

Additional Query String Parameters

// TODO

Full Schema

// TODO

Common Errors

Error Description Action
200 Success
401 Unauthorized Verify that the subscription key is supplied in query string parameter or header.
403 Quota Exceeded The monthly quota has been exceeded. Consider upgrading subscription.
429 Rate Limit Exceeded Queries are being sent too quickly. Consider upgrading subscription.

//TODO

You’ve probably noticed that there are a lot of gaps in the current documentation and preview API. This is a preview in every sense of the word. We are hard at work improving all aspects of this API.

In the meanwhile, we’d love to hear your feedback either via a GitHub issue or by sending us e-mail.