Wolfram|Alpha Summary Box API Reference

Quickly view the main points about a topic with the Summary Box API.

The Summary Box API returns configurable, pre-generated boxes that summarize the available Wolfram|Alpha knowledge for a subject. It is designed to provide a simple starting point for exploration of general topics such as countries, chemicals, dates or people. This process involves using Fast Query Recognizer API lookups to determine the path for each summary box. The Summary Box API is implemented in a standard REST protocol using HTTP GET requests.

Use of the Summary Box 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 Summary Box API

Sample Query

Now that you have an AppID, you can make your first query. Start with a Fast Query Recognizer API request to retrieve the path for a particular summary box. The base URL for the Fast Query Recognizer API 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 API has two distinct modes, "Default" and "Voice". For this 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 "Norway":

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

When executed with a valid AppID, this URL will return an XML form that includes the summary box path for this subject:

<queryrecognizer version="0.2" spellingcorrection="on" buildnumber="5662971">
  <query i="Norway" accepted="true" timing="2.18" domain="countries" resultsignificancescore="70">
    <summarybox path="countries/e/l5/vw/el"/>
  </query>
</queryrecognizer>

Now you can retrieve the summary box for this path. The base URL for Summary Box API queries is:

http://www.wolframalpha.com/summaryboxes/v1/query

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

http://www.wolframalpha.com/summaryboxes/v1/query?appid=DEMO

Next, use the path parameter to specify a topic for your query. For instance, here is a query using the summary box path for "Norway":

http://www.wolframalpha.com/summaryboxes/v1/query?appid=DEMO&path=countries/e/l5/vw/el

When executed with a valid AppID, this URL will return the XHTML summary box for Norway:

Summary Box Overview

Summary boxes provide a rundown of some basic information available on a particular topic. Each summary box represents either an entity (e.g. "Norway") or an entity property (e.g. "population of Norway") within the Wolfram|Alpha system.

Summary Box Paths

Exact values for the path parameter can be retrieved by requesting a topic through the Fast Query Recognizer API. For instance, here is the request and response for the input value "Norway":

http://www.wolframalpha.com/queryrecognizer/query.jsp?appid=DEMO&mode=Default&i=Norway
<queryrecognizer version="0.2" spellingcorrection="on" buildnumber="5662971">
  <query i="Norway" accepted="true" timing="2.18" domain="countries" resultsignificancescore="70">
    <summarybox path="countries/e/l5/vw/el"/>
  </query>
</queryrecognizer>

The value returned for the path parameter of the summarybox element represents the path to the summary box for that query, if one exists.

Formatting Output

Summary boxes are returned as highly structured XHTML documents, allowing the user to define styles as appropriate. Here is the same "Norway" result from above with CSS styling applied:

The next section summarizes the XHTML classes that the API provides for semantic and formatting purposes. Additional HTML styling elements such as <i>, <b>, <sup> and <sub> may also be used as appropriate throughout content.

Layout Elements

Class Name Elements Description
wasb div Overall summary box
wasb-thumbcol div Thumbnail column
wasb-title div Title section
wasb-propcol div Property column
wasb-ans-title div, span Title section for an entity property summary box, emphasizing the answer
wasb-ans div, span Answer section for an entity property box

Link Elements

Class Name Elements Description
wasb-link a Normal hyperlink within a box
wasb-invlink a "Invisible" hyperlink for supplementary information links
wasb-complete div Container for an anchor to complete Wolfram|Alpha results

Content Elements

Class Name Elements Description
wasb-nobullet ul Column of content
wasb-prop span Property label (e.g. "population:")
wasb-propval span Property value (e.g. "4.86 million people")
wasb-thumb img Individual thumbnail image
wasb-captionblock div Container for an image with a caption
wasb-caption-left-top div Image caption, with location (e.g. left-bottom, right-top)
wasb-anno span General annotation
wasb-title-anno span Annotation for main title
wasb-ans-anno span Annotation for answer

Errors and Troubleshooting

Failed queries will return a raw XML result with <result success="false">, along with an error element containing a numerical code and a brief explanatory message. Below is a list of common messages that may occur when using this API.

SummaryBox not found (Error 404)

This error is returned if the specified summary box does not exist. Use the Fast Query Recognizer API to make sure that the summary box path in your query is valid and correctly formatted.

path parameter not present in query (Error 1001)

This error indicates that the API did not find a path parameter while parsing. In most cases, this can be fixed by checking that you have used the correct syntax for including the path 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 you have entered an AppID and that your appid parameter is using the correct syntax.

Account cannot request Summary Boxes (Error 13)

This error indicates that the account associated with the AppID used for a query does not have permission to use this API. Double-check that you have developer access to the API and that your subscription has not expired.