Wolfram|Alpha Fast Query Recognizer API Reference

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

The Fast Query Recognizer API returns a raw XML or JSON 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 Fast 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 Sign up to get your first 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 Fast 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/query.jsp

Every query requires three pieces of information—an AppID, a mode 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/query.jsp?appid=DEMO

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

http://www.wolframalpha.com/queryrecognizer/query.jsp?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/query.jsp?appid=DEMO&mode=Default&i=France

When executed with a valid AppID, this URL will return an image with informational elements relating to the input:

<queryrecognizer version="0.2" spellingcorrection="on" buildnumber="5649936">
  <query i="France" accepted="true" timing="2.18" domain="countries" resultsignificancescore="70">
    <summarybox path="countries/e/br/du/gh"/>
  </query>
</queryrecognizer>

URL Parameters and Options

You can add URL-encoded parameters to customize the behavior and output of the Fast Query Recognizer.

mode

The Fast 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 ongoing improvement.

The "Voice" mode of the Fast 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 Fast Query Recognizer are available in both XML (default) and JSON formats using the output parameter. Here is the JSON version of the sample query and result from above:

http://www.wolframalpha.com/queryrecognizer/query.jsp?appid=DEMO&mode=Default&i=France&output=json
{
  "version" : "0.2",
  "spellingCorrection" : "on",
  "buildnumber" : "5649936",
  "query" : [ {
    "i" : "France",
    "accepted" : "true",
    "timing" : "2.65",
    "domain" : "countries",
    "resultsignificancescore" : "70",
    "summarybox" : {
      "path" : "countries/e/br/du/gh"
    }
  } ]
}

Output Parameters

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

accepted

The primary output of the Fast 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 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 you have entered an AppID 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 you have entered an AppID and that your appid parameter is using the correct syntax.