`wajs` — Wolfram|Alpha via JS

wajs provides JavaScript bindings for the Wolfram|Alpha web-service API. wajs exposes the Wolfram|Alpha web-service API via a small JavaScript library (Node.js environment). The wajs library also offers an interface for querying Wolfram|Alpha, and manipulating query results programmatically without needing to wrangle raw XML.

_{Created by Clark Feusier}

_{All other language bindings for Wolfram|Alpha can be found here.}

Overview
Installation
Documentation
1. Example Usage
2. API Reference
Roadmap
Contributing
Development Requirements
License

Overview

Here is a list of the core features of wajs:

Full Wolfram|Alpha web-service API coverage
Simple to use 'out of the box', yet easily configurable
Predictable promise interface for query
Powerful utility API on query result
Access to raw XML at each level of query result
Access to JSON representation at each level of query result

If you have directly consumed the Wolfram|Alpha web-service API, you might have appreciation for the features listed above. If you haven't yet interacted with the Wolfram|Alpha API, save yourself some pain and use wajs. Installation instructions, example usage, and API reference can be found below.

Installation

wajs is available as an npm package.

_{* Note: Wolfram|Alpha does not support CORS for serving browser requests. wajs is only available in the Node environment until client-side requests are supported by the Wolfram|Alpha API.}

Install module from command-line

npm install wajs

Require or import module for use in desired file

// commonjs require
var wajs = require('wajs')

// es2015 import
import wajs from 'wajs'

Documentation

Example Usage

// require wajs module -- assuming commonjs/node environment
var wajs = require('wajs')
 
// the Wolfram|Alpha App Id -- generated in Wolfram|Alpha developer portal
// NOTE: copy your app id and set your WA_APP_ID environment variable
// from the command-line, as follows:
// `export WA_APP_ID='<YOUR APP ID GOES HERE>'`
var waAppId = process.env.WA_APP_ID
 
// create a client to query the Wolfram|Alpha web-service
// NOTE: you can create as many clients as you want, though you only need one
var waClient = new wajs(waAppId)
 
// the only required argument to `<wajs-client>.query` is a query string
var queryString = 'weather' // maybe this comes from user input
 
// if you want to customize the query further, provide query options
// for documentation on query options, please see
// the API Reference for `<wajs-client>.query`
// NOTE: this is an optional argument
var queryOptions = {
  format: 'image,plaintext,sound,wav',
  units: 'metric'
}
 
// use the client to send a query
waClient.query(queryString, queryOptions)
.then(function(resp) {
  // do something with the `<query-result>` response
  // for documentation on `<query-result>`, please see
  // the API reference for `<query-result>`
})
.catch(function(err) {
  // do something with the `<query-error>` response
})

API Reference

wajs
<wajs-client>.query
- options
<query-result>
<pod>

wajs

`new wajs(appId: string): wajs-client<T>`

This is the constructor function for generating a <wajs-client>.

appId:
- required
- type: string
- Obtain an appId from Wolfram|Alpha

<wajs-client>.query

`<wajs-client>.query(input: string, options: object): Promise<T>`

This method will query the Wolfram|Alpha web-service API with the provided query.

input:
- required
- type: string
options:
- optional
- type: object
- API Reference for options

// query with string and default options
waClient.query('whatever')
.then(function(qr) {
  // qr === <query-result>
})
.catch(function(err) {})

// query with string and custom options
waClient.query('pi', {
  format: 'image,plaintext,sound,wav',
  assumption: '*C.pi-_*Movie-',
  width: '900',
  maxWidth: '1200'
})
.then(function(qr) {
  // qr === <query-result>
})
.catch(function(err) {})

options

var queryOptions = {
  // podTitle
  // repeatable, globable, comma-separated
  // default: all pod titles
  podTitle: '',
 
  // podIndex
  // repeatable, globable, comma-separated
  // default: all pod indices
  podIndex: '',
 
  // format
  // repeatable, comma-separated
  // default: 'image,plaintext'
  // possible options:
    // image
    // plaintext
    // minput
    // moutput
    // cell
    // mathml
    // imagemap
    // sound
    // wav
  format: '',
 
  // assumption
  // single string -- must match an assumption string from Wolfram|Alpha assumptions
  assumption: '',
 
  // includePodId
  // list of strings or single string, globable
  // default: all pod ids
  includePodId: [], // '',
 
  // excludePodId
  // list of strings or single string, globable
  // default: none are excluded
  excludePodId: [], // '',
 
  // scanner
  // list of strings or single string, globable
  // default: all scanners
  scanner: [], // ''
 
  // async
  // boolean -- if set to true, results will contain 'async' flags for the
  // properties that require another request to get content. If you want all the query
  // results in a single response, do not use the async flag
  // default: false
  async: true,
 
  // ip
  // string -- should represent the ip address to be used for restricting the query
  // default: the requesting ip address
  ip: '',
 
  // location
  // string -- should represent the location to be used for
  // restricting the query, e.g., 'CA'
  // default: none
  location: '',
 
  // coordinates
  // string -- should represent the latitude and longitude pair
  // to be used for restricting the query, e.g., '40.42,-3.71'
  // default: none
  coordinates: '',
 
  // podState
  // string -- should match a pod state string from a Wolfram|Alpha pod
  // default: none
  podState: '',
 
  // units
  // string
  // default: based on requesting location
  // possible options:
    // 'metric'
    // 'nonmetric'
  units: '',
 
  // width
  // string
  // default: '500'
  width: '',
 
  // maxWidth
  // string
  // default: '500'
  maxWidth: '',
 
  // plotWidth
  // string
  // default: '200'
  plotWidth: '',
 
  // magnitude
  // string
  // default: '1.0'
  magnitude: '',
 
  // scanTimeout
  // string
  // default: '3.0'
  scanTimeout: '',
 
  // podTimeout
  // string
  // default: '4.0'
  podTimeout: '',
 
  // parseTimeout
  // string
  // default: '5.0'
  parseTimeout: '',
 
  // formatTimeout
  // string
  // default: '8.0'
  formatTimeout: '',
 
  // reinterpret
  // boolean -- if true, and there are no results for a query, Wolfram|Alpha
  // can switch to a related query for which some results are available
  // default: false
  reinterpret: '',
 
  // translation
  // boolean -- if false, auto-translation of simple queries is turned off
  // default: true
  translation: '',
 
  // ignoreCase
  // boolean -- if true, case will not be significant for the given query
  // default: false
  ignoreCase: '',
 
  // sig
  // string -- used to sign and validate identity of request/response
  // default: none
  sig: ''
}

<query-result>

When the promise, returned by <wajs-client>.query, resolves, the resolution handler function is provided a <query-result> instance, with the following API.

<query-result>.succeeded

`<query-result>.succeeded(): boolean`

This method will return a boolean indicating the success of the query operation (not the success of the overall HTTP request, which is indicated by the query promise resolution).

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.succeeded())
})
 
// output
true

<query-result>.failed

`<query-result>.failed(): boolean`

This method will return a boolean indicating the failure of the query operation (not the failure of the overall HTTP request, which is indicated by the query promise rejection).

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.failed())
})
 
// output
false

<query-result>.error

`<query-result>.error(): { Error, null }`

This method will return an Error object if the query operation failed, and null otherwise.

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.error())
})
 
// output
null

<query-result>.numPods

`<query-result>.numPods(): number`

This method will return the number of pods in the given query result.

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.numPods())
})
 
// output
8

<query-result>.dataTypes

`<query-result>.dataTypes(): array<DataType>`

This method will return a list of DataType strings representing the categories and types of data represented in the query result.

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.dataTypes())
})
 
// output
['MathematicalFunctionIdentity']

<query-result>.toJson

`<query-result>.toJson(): json-string`

This method will convert the entire query result to JSON.

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.toJson())
})
 
// output (truncated)
{
  "pod":[...],
  "assumptions":[...],
  "success":"true",
  "error":"false",
  "numpods":"8",
  "datatypes":"MathematicalFunctionIdentity",
  "timedout":"Numeric",
  "timedoutpods":"",
  "timing":"3.4170000000000003",
  "parsetiming":"0.14",
  "parsetimedout":"false",
  "recalculate":"http://www4b.wolframalpha.com/api/v2/recalc.jsp?id=...",
  "id":"...",
  "host":"http://www4b.wolframalpha.com",
  "server":"30",
  "related":"http://www4b.wolframalpha.com/api/v2/relatedQueries.jsp?id=...",
  "version":"2.6"
}

<query-result>.rawXml

`<query-result>.rawXml(): xml-string`

This method will return the entire original xml query result.

// e.g.,
waClient.query('pi').then(function(qr) {
  console.log(qr.rawXml())
})

<!-- output (truncated) -->
<?xml version='1.0' encoding='UTF-8'?>
<queryresult
  success='true'
  error='false'
  numpods='8'
  ...>
  <pod title='Input'>...</pod>
  <assumptions count='1'>...</assumptions>
</queryresult>

<query-result>.pods

`<query-result>.pods(xmlFormat: boolean): array<pod>`

This method return a list of pod objects from the query result.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of pods will be a list of xml string representations of the pods

// e.g., default
waClient.query('pi').then(function(qr) {
  console.log(qr.pods())
})
 
// output (truncated)
[
  {
    subpod: [ [subpod1...] ],
    title: 'Input',
    scanner: 'Identity',
    id: 'Input',
    position: '100',
    error: 'false',
    numsubpods: '1',
    __parent: ...
  },
  ...
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  console.log(qr.pods(true))
})
 
// output (truncated)
[
  '<pod title="Input" scanner="Identity" id="Input" position="100" error="false" numsubpods="1">...</pod>',
  ...
]

<query-result>.assumptions

`<query-result>.assumptions(xmlFormat: boolean): array<assumption>`

This method return a list of assumption objects from the query result.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of assumptions will be a list of xml string representations of the assumptions

// e.g., default
waClient.query('pi').then(function(qr) {
  console.log(qr.assumptions())
})
 
// output (truncated)
[
  {
    value: [[...], [...], [...], [...], [...], [...]],
    type: 'Clash',
    word: 'pi',
    template: 'Assuming "${word}" is ${desc1}. Use as ${desc2} instead',
    count: '6',
    __parent: ...
  }
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  console.log(qr.assumptions(true))
})
 
// output (truncated)
[
  '<assumption type="Clash" word="pi" template="Assuming &quot;${word}&quot; is ${desc1}. Use as ${desc2} instead" count="6">...</assumption>',
  ...
]

<query-result>.sources

`<query-result>.sources(xmlFormat: boolean): array<source>`

This method return a list of source objects from the query result.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of sources will be a list of xml string representations of each source object

// e.g., default
waClient.query('weather').then(function(qr) {
  console.log(qr.sources())
})
 
// output (truncated)
[
  {
    source: [[...], [...], [...], [...]],
    count: '4'
  },
  ...
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  console.log(qr.sources(true))
})
 
// output (truncated)
[
  '<sources count="4">...</sources>',
  ...
]

<query-result>.warnings

`<query-result>.warnings(xmlFormat: boolean): array<warning>`

This method return a list of warning objects from the query result.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of warnings will be a list of xml string representations of each warning object

// e.g., default
waClient.query('pi').then(function(qr) {
  console.log(qr.warnings())
})
 
// output (truncated)
undefined // (there are no warnings for this query result)
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  console.log(qr.warnings(true))
})
 
// output (truncated)
undefined // (there are no warnings for this query result)

<pod>

Each <query-result> provides a .pods() method to access the <query-result> pods, if any. Each <pod> provides the following API.

<pod>.succeeded

`<pod>.succeeded(): boolean`

This method returns true if the pod was loaded successfully from Wolfram|Alpha.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.succeeded())
})
 
// output (truncated)
true // this pod was fetched successfully

<pod>.failed

`<pod>.failed(): boolean`

This method returns true if the pod was not successfully fetched from Wolfram|Alpha.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.failed())
})
 
// output (truncated)
false // this pod was fetched successfully

<pod>.getTitle

`<pod>.getTitle(): string`

This method returns the title of the pod, represented as a string.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getTitle())
})
 
// output (truncated)
'Example Pod Title'

<pod>.numSubPods

`<pod>.numSubPods(): number = 0`

This method returns the number of <subPods> contained by the <pod>.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.numSubPods())
})
 
// output (truncated)
2

<pod>.rawXml

`<pod>.rawXml(): xml-string`

This method returns the raw XML string representation of the <pod>.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.rawXml())
})

<!-- output (truncated) -->
<pod title='Input'>...</pod>

<pod>.getScanner

`<pod>.getScanner(): string`

This method returns a string representation of the <pod>'s scanner.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getScanner())
})
 
// output (truncated)
'Numeric'

<pod>.getPosition

`<pod>.getPosition(): number = 0`

This method returns a number representation of the <pod>'s position in the <query-result>.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getPosition())
})
 
// output (truncated)
1

<pod>.asyncEndpoint

`<pod>.asyncEndpoint(): string`

This method returns a string representation of the <pod>'s asynchronous url -- the endpoint for asynchronously fetching the <pod>'s data, assuming the query used async=true.

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.asyncEndpoint())
})
 
// output (truncated)
'http://www1.wolframalpha.com/api/v2/asyncPod.jsp?id=MSPa1071c679e3ea1d0h94h00002h3ggc950ehaibf9&s=13'

<pod>.subPods

`<pod>.subPods(xmlFormat: boolean): array<subpod>`

This method returns a list of <subpod>s from the pod.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of subpods will be a list of xml string representations of each subpod object

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.subPods())
})
 
// output (truncated)
[
  {
    "title" : "",
    "img" : {
      "src" : "http:\/\/www4c.wolframalpha.com\/Calculate\/MSP\/MSP4541i6ff0cbeghe4a6a0000248ahgicidag8e12?MSPStoreType=image\/gif&s=61",
      "alt" : "",
      "title" : "",
      "width" : 300,
      "height" : 56
    },
      "plaintext" : ""
  }
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.subPods(true))
})
 
// output (truncated)
[
  '<subpod title=''...>...</subpod>'
]

<pod>.getStates

`<pod>.getStates(xmlFormat: boolean): array<state>`

This method returns a list of <state>s from the pod.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of state objects will be a list of xml string representations of each state object

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getStates())
})
 
// output (truncated)
[
  {
    "name" : "Fraction form",
    "input" : "ContinuedFraction__Fraction form"
  }
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getStates(true))
})

// output (truncated)
<states count='1'>
  <state name='More'
    input='AlternativeRepresentations:MathematicalFunctionIdentityData__More'
  />
</states>

<pod>.getInfos

`<pod>.getInfos(xmlFormat: boolean): array<info>`

This method returns a list of <info>s from the pod.

xmlFormat:
- type: boolean
- optional
- default: false
- if true, the list of info objects will be a list of xml string representations of each info object

// e.g.,
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getInfos())
})
 
// output (truncated)
[
  {
    "text" : "(n\nm) is the binomial coefficient",
    "img" : {
      "src" : "http:\/\/www4b.wolframalpha.com\/Calculate\/MSP\/MSP22591ca2276efe0853cd000045fid320b029578h?MSPStoreType=image\/gif&s=61",
      "alt" : "(n\nm) is the binomial coefficient",
      "title" : "(n\nm) is the binomial coefficient",
      "width" : "204",
      "height" : "36"
    },
    "links" : [
      {
        "url" : "http:\/\/reference.wolfram.com\/language\/ref\/Binomial.html",
        "text" : "Documentation",
        "title" : "Mathematica"
      },
      {
        "url" : "http:\/\/functions.wolfram.com\/GammaBetaErf\/Binomial",
        "text" : "Properties",
        "title" : "Wolfram Functions Site"
      },
      {
        "url" : "http:\/\/mathworld.wolfram.com\/BinomialCoefficient.html",
        "text" : "Definition",
        "title" : "MathWorld"
      }
    ]
  }
]
 
// e.g., xmlFormat is true
waClient.query('pi').then(function(qr) {
  const [pod] = qr.pods()
  console.log(pod.getInfos(true))
})

// output (truncated)
<infos count='1'>
  <info text='i is the imaginary unit'>
    <img src='http://www5b.wolframalpha.com/Calculate/MSP/MSP11872374eggi4a3i61a900000eg99g28e5669i23?MSPStoreType=image/gif&amp;s=32'
      alt='i is the imaginary unit'
      title='i is the imaginary unit'
      width='147'
      height='18'
    />
    <link url='http://reference.wolfram.com/language/ref/I.html'
      text='Documentation'
      title='Documentation'
    />
    <link url='http://mathworld.wolfram.com/i.html'
      text='Definition'
      title='MathWorld'
    />
  </info>
</infos>

Roadmap

The future of wajs is managed through this repository's Issues — view the roadmap here.

Contributing to wajs

I welcome contributions, but please submit an issue before beginning so that I don't duplicate your work. The development requirements and instructions are below.

Development Requirements

JavaScript Engine:

node > 0.10.x

Package Manager:

npm > 2.x.x

Global Packages:

webpack

Project Package Dependencies:

bluebird
cheerio
popsicle
traverse
xml2js

Development Package Dependencies:

babel-core
babel-loader
babel-plugin-transform-runtime
babel-polyfill
babel-preset-es2015
babel-preset-stage-0
babel-runtime
watch
webpack-node-externals

Installing Dependencies

Install Node (bundled with npm) using Homebrew:

brew install node

Install global project dependencies using npm:

npm install -g webpack

Install all local project dependencies using npm:

npm install

Running Tests

After installing the above dependencies, tests can be run using the following command:

npm run test

Building

For a one-off build, run the following command:

npm run build

For a continuous build on changes during development, run the following command:

npm run build:watch

License

MIT LICENSE

wajs -- JavaScript bindings for the Wolfram|Alpha web-service API

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

wajs

wajs — Wolfram|Alpha via JS

Overview

Installation

Documentation

Example Usage

API Reference

wajs

new wajs(appId: string): wajs-client<T>

<wajs-client>.query

<wajs-client>.query(input: string, options: object): Promise<T>

options

<query-result>

<query-result>.succeeded

<query-result>.succeeded(): boolean

<query-result>.failed

<query-result>.failed(): boolean

<query-result>.error

<query-result>.error(): { Error, null }

<query-result>.numPods

<query-result>.numPods(): number

<query-result>.dataTypes

<query-result>.dataTypes(): array<DataType>

<query-result>.toJson

<query-result>.toJson(): json-string

<query-result>.rawXml

<query-result>.rawXml(): xml-string

<query-result>.pods

<query-result>.pods(xmlFormat: boolean): array<pod>

<query-result>.assumptions

<query-result>.assumptions(xmlFormat: boolean): array<assumption>

<query-result>.sources

<query-result>.sources(xmlFormat: boolean): array<source>

<query-result>.warnings

<query-result>.warnings(xmlFormat: boolean): array<warning>

<pod>

<pod>.succeeded

<pod>.succeeded(): boolean

<pod>.failed

<pod>.failed(): boolean

<pod>.getTitle

<pod>.getTitle(): string

<pod>.numSubPods

<pod>.numSubPods(): number = 0

<pod>.rawXml

<pod>.rawXml(): xml-string

<pod>.getScanner

<pod>.getScanner(): string

<pod>.getPosition

<pod>.getPosition(): number = 0

<pod>.asyncEndpoint

<pod>.asyncEndpoint(): string

<pod>.subPods

<pod>.subPods(xmlFormat: boolean): array<subpod>

<pod>.getStates

<pod>.getStates(xmlFormat: boolean): array<state>

<pod>.getInfos

<pod>.getInfos(xmlFormat: boolean): array<info>

Roadmap

Contributing to wajs

Development Requirements

Installing Dependencies

Running Tests

Building

License

Back to Top

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

`wajs` — Wolfram|Alpha via JS

`new wajs(appId: string): wajs-client<T>`

`<wajs-client>.query(input: string, options: object): Promise<T>`

`<query-result>.succeeded(): boolean`

`<query-result>.failed(): boolean`

`<query-result>.error(): { Error, null }`

`<query-result>.numPods(): number`

`<query-result>.dataTypes(): array<DataType>`

`<query-result>.toJson(): json-string`

`<query-result>.rawXml(): xml-string`

`<query-result>.pods(xmlFormat: boolean): array<pod>`

`<query-result>.assumptions(xmlFormat: boolean): array<assumption>`

`<query-result>.sources(xmlFormat: boolean): array<source>`

`<query-result>.warnings(xmlFormat: boolean): array<warning>`

`<pod>.succeeded(): boolean`

`<pod>.failed(): boolean`

`<pod>.getTitle(): string`

`<pod>.numSubPods(): number = 0`

`<pod>.rawXml(): xml-string`

`<pod>.getScanner(): string`

`<pod>.getPosition(): number = 0`

`<pod>.asyncEndpoint(): string`

`<pod>.subPods(xmlFormat: boolean): array<subpod>`

`<pod>.getStates(xmlFormat: boolean): array<state>`

`<pod>.getInfos(xmlFormat: boolean): array<info>`

Weekly Downloads