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.
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.
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.
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 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.
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.
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.
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 |
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 |
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 |
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.
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.
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.
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.
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.
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.
free non-commercial development account
flexible commercial licensing with low monthly plans available