The Wolfram|Alpha Full Results API provides a web-based API allowing the computational and presentation capabilities of Wolfram|Alpha to be integrated into web, mobile, desktop and enterprise applications.
The API allows clients to submit free-form queries similar to the queries one might enter at the Wolfram|Alpha website, and for the computed results to be returned in a variety of formats. It is implemented in a standard REST protocol using HTTP GET requests. Each result is returned as a descriptive XML or JSON structure wrapping the requested content format.
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 Full Results API is subject to the API Terms of Use.
To get started, you must register a Wolfram ID and sign in at 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. The base URL for queries is:
http://api.wolframalpha.com/v2/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://api.wolframalpha.com/v2/query?appid=DEMO
Next, use the input parameter to specify the URL-encoded input for your query. For instance, here is a query for “population of France”:
http://api.wolframalpha.com/v2/query?appid=DEMO&input=population%20of%20france
When executed with a valid AppID, this URL will return an XML document with informational elements (referred to as pods relating to the input. Here is the XML output for the "population of France" query, with most elements collapsed for brevity:
<queryresult success="true" error="false" numpods="5" datatypes="Country" timedout="Data,Percent,Unit,AtmosphericProperties,UnitInformation,Music,Geometry" timedoutpods="" timing="6.272" parsetiming="0.27" parsetimedout="false" version="2.6">
<pod title="Input interpretation" scanner="Identity" id="Input" position="100" error="false" numsubpods="1">...</pod>
<pod title="Result" scanner="Data" id="Result" position="200" error="false" numsubpods="1" primary="true">
<subpod title="">
<plaintext>
64.1 million people (world rank: 21st) (2014 estimate)
</plaintext>
<img src="http://www1.wolframalpha.com/Calculate/MSP/MSP291g37h8915724h4b800004ec2h0de24da9sbp?MSPStoreType=image/gif&s=12" alt="64.1 million people (world rank: 21st) (2014 estimate)" title="64.1 million people (world rank: 21st) (2014 estimate)" width="313" height="18"/>
</subpod>
</pod>
<pod title="Recent population history" scanner="Data" id="RecentHistory:Population:CountryData" position="300" error="false" numsubpods="1">...</pod>
<pod title="Long-term population history" scanner="Data" id="LongTermHistory:Population:CountryData" position="400" error="false" numsubpods="1">...</pod>
<pod title="Demographics" scanner="Data" id="DemographicProperties:CountryData" position="500" error="false" numsubpods="1">...</pod>
<warnings count="1">...</warnings>
<sources count="1">...</sources>
</queryresult><queryresult success="true" error="false" numpods="5" datatypes="Country" timedout="Data,Percent,Unit,AtmosphericProperties,UnitInformation,Music,Geometry" timedoutpods="" timing="6.272" parsetiming="0.27" parsetimedout="false" version="2.6">
<pod title="Input interpretation" scanner="Identity" id="Input" position="100" error="false" numsubpods="1">...</pod>
<pod title="Result" scanner="Data" id="Result" position="200" error="false" numsubpods="1" primary="true">
<subpod title="">
<plaintext>
64.1 million people (world rank: 21st) (2014 estimate)
</plaintext>
<img src="http://www1.wolframalpha.com/Calculate/MSP/MSP291g37h8915724h4b800004ec2h0de24da9ife?MSPStoreType=image/gif&s=12" alt="64.1 million people (world rank: 21st) (2014 estimate)" title="64.1 million people (world rank: 21st) (2014 estimate)" width="313" height="18"/>
</subpod>
</pod>
<pod title="Recent population history" scanner="Data" id="RecentHistory:Population:CountryData" position="300" error="false" numsubpods="1">...</pod>
<pod title="Long-term population history" scanner="Data" id="LongTermHistory:Population:CountryData" position="400" error="false" numsubpods="1">...</pod>
<pod title="Demographics" scanner="Data" id="DemographicProperties:CountryData" position="500" error="false" numsubpods="1">...</pod>
<warnings count="1">...</warnings>
<sources count="1">...</sources>
</queryresult>
All URLs used to make queries must be URL encoded (e.g. spaces represented as "%20" and backslashes represented as "%5c").
For mathematical queries, Wolfram|Alpha will also accept input formatted using presentation LaTeX or MathML. This can be useful when passing information back and forth between the API and a website or application using one of these formats.
You can add URL-encoded parameters to customize output. For instance, if you only wanted the "Result" pod from the above output, you could use the includepodid parameter:
http://api.wolframalpha.com/v2/query?appid=DEMO&input=population%20france&includepodid=Result
This way, only pods with that exact ID are returned in the XML output:
<queryresult success="true" error="false" numpods="1" datatypes="" timedout="" timedoutpods="" timing="0.895" parsetiming="0.277" parsetimedout="false" recalculate="" id="MSPa201c626hgh07fd2ee900003c1966c16708edi1" host="http://www1.wolframalpha.com" server="13" related="http://www1.wolframalpha.com/api/v2/relatedQueries.jsp?id=MSPa211c626hgh07fd2ee90000368i61d9578b12h4&s=13" version="2.6">
<pod title="Result" scanner="Data" id="Result" position="100" error="false" numsubpods="1" primary="true">
<subpod title="">
<plaintext>
64.1 million people (world rank: 21st) (2014 estimate)
</plaintext>
<img src="http://www1.wolframalpha.com/Calculate/MSP/MSP221c626hgh07fd2ee900004eagdagf39fchhhg?MSPStoreType=image/gif&s=13"
alt="64.1 million people (world rank: 21st) (2014 estimate)"
title="64.1 million people (world rank: 21st) (2014 estimate)"
width="313" height="18"/>
</subpod>
</pod>
<sources count="1">...</sources>
</queryresult>
Note that this result returns both a <plaintext> element and an <img> element. You can select which output type you prefer using the format parameter:
http://api.wolframalpha.com/v2/query?appid=DEMO&input=population%20france&includepodid=Result&format=plaintext
By using parameters in your queries, you can reduce the output to just the pieces you need. Notice how much shorter this output is than that of the original query:
<queryresult success="true" error="false" numpods="1" datatypes="" timedout="" timedoutpods="" timing="0.723" parsetiming="0.266" parsetimedout="false" recalculate="" id="MSPa1751g37h8915724h4b80000365icce2he8ca3g1" host="http://www1.wolframalpha.com" server="12" related="http://www1.wolframalpha.com/api/v2/relatedQueries.jsp?id=MSPa1761g37h8915724h4b80000267ba77dbgig0651&s=12" version="2.6">
<pod title="Result" scanner="Data" id="Result" position="100" error="false" numsubpods="1" primary="true">
<subpod title="">
<plaintext>
64.1 million people (world rank: 21st) (2014 estimate)
</plaintext>
</subpod>
</pod> <sources count="1">...</sources>
</queryresult>
A list of possible parameters is included below.
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
input | URL-encoded text specifying the input string | "5+largest+countries", "Doppler%20shift", "pascal%27s%20triangle" | N/A (Queries without an input value will fail) | Required parameter |
appid | An ID provided by Wolfram Research that identifies the application or organization making the request | X7WEHY-W45KYJL3C9 | N/A (Queries without an AppID will fail) | Required parameter |
format | The desired format for individual result pods | "image", "imagemap", "plaintext", "minput", "moutput", "cell", "mathml", "sound", "wav" | Return basic text and image formats ("plaintext,image") | All possible values for this parameter are listed here. For multiple formats, separate values with a comma. |
output | The desired format for full results | "xml", "json" | Return an XML document | All possible values for this parameter are listed here |
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
includepodid | Specifies a pod ID to include in the result | "Result", "BasicInformation:PeopleData", "DecimalApproximation" | All pods included | To specify multiple elements, use multiple instances of the parameter |
excludepodid | Specifies a pod ID to exclude from the result | "Result", "BasicInformation:PeopleData", "DecimalApproximation" | No pods excluded | To specify multiple elements, use multiple instances of the parameter |
podtitle | Specifies a pod title to include in the result | "Basic+Information", "Image", "Alternative%20representations" | All pods returned | To specify multiple elements, use multiple instances of the parameter. Use * as a wildcard to match zero or more characters in pod titles. |
podindex | Specifies the index(es) of the pod(s) to return | "1", "7", "5,12,13" | All pods returned | To specify multiple elements, separate values with a comma |
scanner | Specifies that only pods produced by the given scanner should be returned | "Numeric", "Data", "Traveling" | Pods from all scanners returned | To specify multiple elements, use multiple instances of the parameter |
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
ip | Specifies a custom query location based on an IP address | "192.168.1.1", "127.0.0.1" | Use caller's IP address for location | Only one location parameter may be used at a time. IPv4 and IPv6 addresses are supported. |
latlong | Specifies a custom query location based on a latitude/longitude pair | "40.42,-3.71", "40.11, -88.24", "0,0" | Use caller's IP address for location | Only one location parameter may be used at a time |
location | Specifies a custom query location based on a string | "Boston, MA", "The North Pole", "Beijing" | Use caller's IP address for location | Only one location parameter may be used at a time |
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
width | Specify an approximate width limit for text and tables | "200", "500" | Width set at 500 pixels | This parameter does not affect plots or graphics. Width values are approximate; behavior may vary for different content. |
maxwidth | Specify an extended maximum width for large objects | "200", "500" | Width set at 500 pixels | This parameter does not affect plots or graphics. Width values are approximate; behavior may vary for different content. |
plotwidth | Specify an approximate width limit for plots and graphics | "100", "200" | Plot width set at 200 pixels | This parameter does not affect text or tables. Width values are approximate; behavior may vary for different content. |
mag | Specify magnification of objects within a pod | "0.5", "1.0", "2.0" | Magnification factor of 1.0 | Changing this parameter does not affect the overall size of pods |
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
scantimeout | The number of seconds to allow Wolfram|Alpha to compute results in the "scan" stage of processing | "0.5", "5.0" | Scan stage times out after 3.0 seconds | This parameter effectively limits the number and breadth of subtopics that will be included in a result |
podtimeout | The number of seconds to allow Wolfram|Alpha to spend in the "format" stage for any one pod | "0.5", "5.0" | Individual pods time out after 4.0 seconds | This parameter can be used to prevent a single pod from dominating too much processing time, or to return only the "quick" information in your result |
formattimeout | The number of seconds to allow Wolfram|Alpha to spend in the "format" stage for the entire collection of pods | "0.5", "5.0" | Format stage times out after 8.0 seconds | Use this parameter in conjunction with podtimeout to balance between returning a few large results and numerous quick results |
parsetimeout | The number of seconds to allow Wolfram|Alpha to spend in the "parsing" stage of processing | "0.5", "5.0" | Parsing stage times out after 5.0 seconds | Queries that time out in this phase will return a <queryresult> element with success=false and parsetimeout=true. Very few queries will exceed the default. |
totaltimeout | The total number of seconds to allow Wolfram|Alpha to spend on a query | "0.5", "5.0" | Queries time out after 20.0 seconds | Combine with other timeout parameters to define a last-resort time limit for queries. |
async | Toggles asynchronous mode to allow partial results to return before all the pods are computed | "true", "false", "3.0" | Asynchronous mode disabled ("false") | Specifying a number sets the time limit (in seconds) for returning partial results |
PARAMETER NAME | FUNCTION | SAMPLE VALUES | DEFAULT VALUES | NOTES |
---|---|---|---|---|
reinterpret | Whether to allow Wolfram|Alpha to reinterpret queries that would otherwise not be understood | "true", "false" | Do not reinterpret queries ("false") | This parameter will force the API to decide among <didyoumeans> and similar XML results |
translation | Whether to allow Wolfram|Alpha to try to translate simple queries into English | "true", "false" | Do not attempt translation ("false") | Translation attempts are displayed as <translation> warnings in XML results |
ignorecase | Whether to force Wolfram|Alpha to ignore case in queries | "true", "false" | Do not ignore case ("false") | This can be useful for differentiating abbreviations, acronyms and titles |
sig | A special signature that can be applied to guard against misuse of your AppID | N/A | No signature applied | For access to this feature, contact us |
assumption | Specifies an assumption, such as the meaning of a word or the value of a formula variable | "*C.pi-_*Movie", "DateOrder_**Day.Month.Year--" | Assumptions made implicitly by the API | Values for this parameter are given by the input properties of <value> subelements of <assumption> elements in XML results |
podstate | Specifies a pod state change, which replaces a pod with a modified version, such as displaying more digits of a large decimal value | "WeatherCharts:WeatherData__Past+5+years", "2@DecimalApproximation__More+digits" | Pod states generated implicitly by the API | Specify consecutive state changes with the @ symbol (e.g. podstate=2@DecimalApproximation__More+digits) |
units | Lets you specify the preferred measurement system, either "metric" or "nonmetric" (US customary units) | "metric", "nonmetric" | Chosen based on caller's IP address | Using location parameters will affect the units displayed for a query) |