Wolfram|Alpha Query Recognizer API Reference

Quickly classify queries and recognize ones that are likely to be handled by Wolfram|Alpha with the  Query Recognizer API.

The Query Recognizer API returns a raw JSON or XML response telling whether a query would be accepted by the Wolfram|Alpha server, and from what domain the answer will most likely come. This API is designed to give developers a quick way to test the viability of different queries in Wolfram|Alpha API applications. It is implemented in a standard REST protocol using HTTP GET requests.

Although the majority of data available through the Wolfram|Alpha website is also available through this API, certain subjects may be restricted by default. To request access to additional topics, contact us. Use of the Query Recognizer API is subject to the API Terms of Use and Commercial Terms of Use.

Getting Started

Signup and Login

To get started, you must register a Wolfram ID and sign in to the Wolfram|Alpha Developer Portal. Upon logging in, go to the "My Apps" tab to start creating your first app.

Obtaining an AppID

Click the “Get an AppID” button to start the app creation process. After a one-time survey about intended usage, the AppID creation dialog will appear. Give your application a name and a simple description to register an AppID. Each application must have its own unique AppID.

Using the Query Recognizer API

Sample Query

Now that you have an AppID, you can make your first query. The base URL for queries is:

http://www.wolframalpha.com/queryrecognizer.jsp/query

Every query requires two pieces of information—an AppID and an input value—in order to be processed correctly. The appid parameter tells your query which AppID to use:

http://www.wolframalpha.com/queryrecognizer.jsp/query?appid=DEMO

The Query Recognizer has two distinct modes, "Default" and "Voice", explained below. For purposes of this sample query, we'll use "Default" mode:

http://www.wolframalpha.com/queryrecognizer.jsp/query?appid=DEMO&mode=Default

Next, use the i parameter to specify the URL-encoded input for your query. For instance, here is a query for "France":

http://www.wolframalpha.com/queryrecognizer.jsp/query?appid=DEMO&mode=Default&i=France

When executed with a valid AppID, this URL will return a web document with information on your query:

{
  "version" : "0.2",
  "spellingCorrection" : "on",
  "buildnumber" : "5579875",
  "query" : [ {
    "i" : "france",
    "accepted" : "true",
    "timing" : "2.5",
    "domain" : "countries",
    "resultsignificancescore" : "70",
    "summarybox" : {
      "path" : "countries/e/br/du/gh"
    }
  } ]
}

URL Parameters and Options

Using the same RESTful style, you can add parameters to customize the behavior and output of the Query Recognizer.

mode

The Query Recognizer is available in two different modes, each of which is configured to accept certain types of inputs. "Default" mode is designed to recognize any query for which Wolfram|Alpha returns a relevant result, with the goal of placing as many answers as possible into results. Some specific types of queries (e.g. phone numbers, IP addresses, product codes) are explicitly filtered, and only inputs with unambiguous linguistics are accepted (e.g. "boston employment" is not accepted but "boston employment rate" is). This tuning up for ambiguity is an on-going improvement.

The "Voice" mode of the Query Recognizer is optimized for spoken input.  It is generally less restrictive than the "Default" mode, meaning that more variation of the input will be accepted.

output

Results from the Query Recognizer are available in both JSON (default) and XML formats using the output parameter. Here is the XML version of the sample query and result from above:

http://www.wolframalpha.com/queryrecognizer.jsp/query?appid=DEMO&mode=Default&i=France&output=xml
<queryrecognizer version="0.2" spellingcorrection="on" buildnumber="5576518">
  <query i="France" accepted="true" timing="2.68" domain="countries" resultsignificancescore="70">
    <summarybox path="countries/e/br/du/gh"/>
  </query>
</queryrecognizer>

Output Parameters

The following is an explanation of the output parameters given in XML and JSON results.

accepted

The primary output of the Query Recognizer, the accepted parameter returns "true" if the input is believed to be an appropriate query for Wolfram|Alpha to process and "false" otherwise.

timing

This parameter gives the CPU time (in milliseconds) used by the Recognizer to process the input.

domain

For accepted inputs (i.e. those that return "true" for the accepted parameter), this parameter indicates the content domain under which the input is categorized. This gives a rough idea of the type of result you'd expect from sending this input to Wolfram|Alpha (either via the website or the other APIs).

resultsignificancescore

This score is an initial estimate of how the Wolfram|Alpha result is expected to rank relative to search engine results, ranging from 100 (best) to 0 (worst, usually accompanied by a "false" value for the accepted parameter). You can think of this as a measure of how certain Wolfram|Alpha is about a result, with higher scores indicating a higher degree of certainty.

summarybox

Shows the path to precomputed "summary boxes" for the input, when appropriate.

Errors

HTTP Status 501

This status is returned if a given input value cannot be interpreted by this API. This is commonly caused by input that is misspelled, poorly formatted or otherwise unintelligible. Because this API is designed to return a single result, this message may appear if no sufficiently short result can be found. You may occasionally receive this status when requesting information on topics that are restricted or not covered.

HTTP Status 400

This status indicates that the API did not find an input parameter while parsing. In most cases, this can be fixed by checking that you have used the correct syntax for including the i parameter.

Invalid appid (Error 1)

This error is returned when a request contains an invalid option for the appid parameter. Double-check that your AppID is typed correctly and that your appid parameter is using the correct syntax.

Appid missing (Error 2)

This error is returned when a request does not contain any option for the appid parameter. Double-check that your AppID is typed correctly and that your appid parameter is using the correct syntax.