Wolfram|Alpha Conversational API Reference

Get results optimized for back-and-forth dialog with the Conversational API.

The Conversational API returns a text result phrased in full sentence form, along with a token for making a related follow-up query. This API provides an easy interface for personal assistants, reference apps and other situations that call for a continuous dialog. It is implemented in a standard REST protocol using HTTP GET requests.

Because this API is designed to return individual results, queries may fail if no concise result can be found. 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 Conversational 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 Conversational API

Sample Query

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

http://api.wolframalpha.com/v1/conversation.jsp

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://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO

Next, use the i parameter to specify the URL-encoded input for your query. For instance, here is a query for "How much does the Earth weigh?":

http://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO&i=How+much+does+the+earth+weigh%3f

When executed with a valid AppID, this URL will return a line of conversational text with a computed response to your query, along with an identifier and a host URL for continuing your conversation. In rare cases, an additional s parameter will also be returned:

{"result" : "The answer is about 5.97 times 10 to the 24th power kilograms.", 
"conversationID" : "MSP6171ce6c8h9c1d8941900003cc43ebfa8972fg3", 
"host" : "www4b.wolframalpha.com",
"s" : "3"}

To build a follow-up query, replace api.wolframalpha.com with the new host URL (appending/api) and pass in the conversationID and s values using the conversationid and s input parameters, respectively. The i value for this query should relate directly to the previous output, as in this example: "What is that in pounds?"

http://www4b.wolframalpha.com/api/v1/conversation.jsp?appid=DEMO&conversationid=MSP4121cd79fgi58bd5f7400002d93dcbeh2i65abi&i=What+is+that+in+pounds%3f&s=3

This will compute an answer based on your query and the previous result:

{"result" : "The answer is about 1.32 times 10 to the 25th power pounds", 
"conversationID" : "MSP9981gad12e6fe7c79da000052hb52d0id3f6dc5", 
"host" : "www4b.wolframalpha.com"}

Using the new values supplied by each successive query, you can continue this conversation indefinitely.

URL Parameters and Options

You can add URL-encoded parameters to customize behavior and output. Since the output for this API is plain text, only basic parameters are available.

geolocation

This parameter lets you specify a latitude/longitude pair like "40.42,-3.71". Although this is the most exact way to specify a location, it will fail if no valid data is available nearby for the query. Negative latitude values indicate south, and negative longitude values indicate west:

http://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO&i=What+is+the+nearest+lake%3f&geolocation=40.11,-88.28
{"result" : "The answer is Homer Lake", 
"conversationID" : "MSP6081cd79fgi58bd5f7400001586c30h5d1h7571", 
"host" : "www4b.wolframalpha.com"}

ip

Set the IP address of the caller, which will be used to determine a location. If you are forwarding calls from your own web visitors to the API, you can propagate their IP addresses with this parameter:

http://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO&i=What+is+the+high+temperature+today%3f&ip=203.0.113.10
{"result" : "The answer is 69 degrees Fahrenheit", 
"conversationID" : "MSP3811gaeg0eeiih56eg0000068iehc21b6ia0aa6", 
"host" : "www4b.wolframalpha.com"}

units

Use this parameter to manually select what system of units to use for measurements and quantities (either "metric" or "imperial"). By default, the system will use your location to determine this setting. Adding "units=metric" to this query displays the result in meters instead of feet:

http://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO&i=How+tall+is+michael+jordan%3f&units=metric
{"result" : "Michael Jordan's height is 1.98 meters", 
"conversationID" : "MSP6081cd79fgi58bd5f7400001586c30h5d1h7571", 
"host" : "www4b.wolframalpha.com"}

s

This parameter should only be used in the rare case that your result includes the s output parameter:

http://api.wolframalpha.com/v1/conversation.jsp?appid=DEMO&i=When+was+Isaac+Newton+born%3f
{"result" : "Isaac Newton was born on Sunday, December 25, 1642", 
"conversationID" : "MSP7451bi53ge536cadca8000054ihb2h764g39d2g", 
"host" : "www4b.wolframalpha.com",
"s" : "3"}

When present, this value must be propagated to the next query to ensure continuity of conversations:

http://www4b.wolframalpha.com/api/v1/conversation.jsp?appid=DEMO&conversationid=MSP7451bi53ge536cadca8000054ihb2h764g39d2g&i=How+long+ago+was+that%3f&s=3
{"result" : "The answer is 290 years 1 month 11 days", 
"conversationID" : "MSP13741bi53ge47cd896fa00002eg6gai764c04dhc", 
"host" : "www4b.wolframalpha.com"}

Output Parameters

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

result

The latest text response from Wolfram|Alpha in the current conversation. The API will take this value into account when computing an answer to the next query in this conversation.

conversationID

A string that serves as a unique identifier for the current conversation. Passing this value into a subsequent query (using the conversationid input parameter) will continue the current conversation, computing a result based on both the new query and the previous result.

host

The URL of the specific Wolfram|Alpha server processing the current conversation, to be used as the base URL for followup queries. This value should stay the same throughout a conversation.

s

This parameter only appears in rare circumstances. When present, this value must be passed into the s input parameter to continue a conversation.

error

If no input is given, or if no answer can be computed, the error parameter is returned with a value describing the issue. Specific error messages are described in detail below.

Errors

"No result is available"

This value for the error parameter 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.

"No input."

This value for the error parameter 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 you have entered an AppID and that your appid parameter is using the correct syntax.