iex.js JavaScript Library#

iex.js (iexjs) is a client library for querying IEX Cloud Financial Data and for operating on Apperate resources, such as data, datasets, data sources, and more. The easy-to-use JavaScript methods wrap IEX Cloud Financial Data endpoints, so you can more easily tap into your purchased Data Bundles and workspace datasets, and manage Apperate resources.

Installation for Running with NodeJS#

If you want to use iexjs in a NodeJS environment, you can install iexjs with npm.

npm install @apperate/iexjs

Note

iexjs can also run in the browser via native fetch and eventsource, or from node via cross-fetch and eventsource.

Initializing a Client#

The iexjs Client object is initialized with your API token (API key) and the API version (e.g., v1) you want to use.

Here’s one way to initialize a client.

const {Client} = require("@apperate/iexjs")
const client = new Client({api_token: "TOKEN", version: "VERSION"});

Another way to in itialize a client is to preset your API token in the IEX_TOKEN environment variable.

For example, set the variable in your commandline environment.

export IEX_TOKEN="sk_abc123"

Then initialize a Client, like this:

const client = new Client({version: "v1"});

iexjs sets the above client’s API token to the IEX_TOKEN value automatically by default.

Example Endpoint Calls#

Here are a couple calls to get IEX Cloud data.

Get a Stock Quote#

client.apperate.queryData({
    workspace: "CORE",
    id: "QUOTE",
    key: "AMZN"}).then((res) => {
        console.log());
});

The above call uses the Apperate class’s queryData method to query for Amazon’s latest stock quote. The queryData method retrieves data from the QUOTE dataset (id: "QUOTE"). iexjs calls on IEX Cloud Financial Data’s QUOTE dataset (accessible via the Stock Quote endpoint) to get the latest quote record matching the symbol AMZN (key: "AMZN") and then prints the response.

Here’s what the quote query looks like in a script for executing using NodeJS.

Script:

const {Client} = require("@apperate/iexjs");

async function yourFunction() {
    const client = new Client({version: "v1"});
    client.apperate.queryData({workspace: "CORE", id: "QUOTE", key: "AMZN"}).then((data) => {
        console.log("AMZN " + data[0].latestPrice + " at " + new Date(data[0].latestUpdate));
    });
}

yourFunction();

Execution:

node your-script.sh

Output:

[
  {
    avgTotalVolume: 64433399,
    calculationPrice: 'tops',
    change: -3.035,
    changePercent: -0.02879,
    close: null,
    closeSource: 'official',
    closeTime: null,
    companyName: 'Amazon.com Inc.',
    currency: 'USD',
    //more data fields ...
    lastTradeTime: 1682955665097,
    latestPrice: 102.395,
    latestSource: 'IEX real time price',
    latestTime: '11:41:05 AM',
    latestUpdate: 1682955665097,
    latestVolume: 33793684,
    // more data fields ...
  }
]

The query response is in JSON and is an array containing a quote object. The above response is shortened for example purposes.

Note

You can retrieve data from your workspace endpoints and from IEX Cloud Financial Data endpoints of data bundles you’ve purchased. The Stock Quote endpoint is part of the Equities Market Data bundle.

Get Company Cashflow Data#

Similar to getting a stock quote, can get use other endpoints to get other types of financial details. The code below gets Apple’s latest quarterly cashflow details and prints the cashflow amount, frequency period, and date.

const data = await client.apperate.queryData({
    workspace: "CORE",
    id: "CASH_FLOW",
    key: "AMZN",
    subkey: "quarterly"});
if (data.length > 0) {
    console.log(
        "AMZN " + data[0].subkey +
        " cashflow is " + data[0].cashFlow +
        " at " + new Date(data[0].date));
}

Output:

AMZN quarterly cashflow is 4788000000 at Fri Mar 31 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

The Cash Flow endpoint takes a stock symbol as a key and a frequency as an optional subkey.

Stock quotes and cashflow details are a couple of the many kinds of financial data available in IEX Cloud Financial Data. See the IEX Cloud Financial Data endpoints for more rich data.

Open Source Project#

iexjs is an open source project available at https://www.npmjs.com/package/@apperate/iexjs.

What’s Next#

Querying Data with iex.js demonstrates getting data from a dataset.

Write Data in Real Time with the apperate.write() JS Method demonstrates writing data using apperate.write().

Apperate IEXJS describes the Apperate iexjs JavaScript methods for querying IEX Cloud financital data and operating on Apperate resources.