alpha-vantage-wrapper

This small library wraps around the Alpha Vantage APIs with an easy and cleaner interface. The following documentation is related to the wrapper with recalls to the official documentation.

Install

npm install alphavantage-wrapper

or via Github package

npm install @mirgj/alphavantage-wrapper

Initialisation

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

The wrapper function will initialise with based on the provided configuration, the options available are the following:

After the Initialisation you’ll get the following object with these properties:

Follow the documentation to know more about the single functionalities

exchangeRate

The exchangeRate is used to get the exchange rate from currency A to currency B. Crypto currencies are also supported. The following example shows the conversion rate from BTC (bitcoin) to USD.

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.exchangeRate('BTC', 'USD');

The output of the example will be the following (with parse mode set to transform):

{
  "from":{
    "code":"BTC",
    "name":"Bitcoin"
  },
  "to":{
    "code":"USD",
    "name":"United States Dollar"
  },
  "exchangeRate":"11884.15000000",
  "lastRefresh":"2019-07-08 15:28:15",
  "timeZone":"UTC"
}

if the parse mode is set to clean the output will be following:

{
  "realtimeCurrencyExchangeRate":{
    "from_CurrencyCode":"BTC",
    "from_CurrencyName":"Bitcoin",
    "to_CurrencyCode":"USD",
    "to_CurrencyName":"United States Dollar",
    "exchangeRate":"11887.26000000",
    "lastRefreshed":"2019-07-08 15:32:33",
    "timeZone":"UTC"
  }
}

While in case parse mode is set to none the output will be the same as the API:

{
  "Realtime Currency Exchange Rate":{
    "1. From_Currency Code":"BTC",
    "2. From_Currency Name":"Bitcoin",
    "3. To_Currency Code":"USD",
    "4. To_Currency Name":"United States Dollar",
    "5. Exchange Rate":"11905.29000000",
    "6. Last Refreshed":"2019-07-08 15:37:02",
    "7. Time Zone":"UTC"
  }
}

The last two parse mode are the same for all the other APIs and will not be explained in the next examples as they’re mostly related on how alphavantage provides the output.

In any case, if injectRawResponse is set to true, the original output will be replicated inside a property raw in the output. Example:

{
  "from":{
    "code":"BTC",
    "name":"Bitcoin"
  },
  "to":{
    "code":"USD",
    "name":"United States Dollar"
  },
  "exchangeRate":"11905.29000000",
  "lastRefresh":"2019-07-08 15:37:02",
  "timeZone":"UTC",
  "raw":{
    "Realtime Currency Exchange Rate":{
      "1. From_Currency Code":"BTC",
      "2. From_Currency Name":"Bitcoin",
      "3. To_Currency Code":"USD",
      "4. To_Currency Name":"United States Dollar",
      "5. Exchange Rate":"11905.29000000",
      "6. Last Refreshed":"2019-07-08 15:37:02",
      "7. Time Zone":"UTC"
    }
  }
}

crypto

This module provide functions related to the crypto currencies. The following function are exposed through the module:

Each of the method listed above will have the same signature which is the following: [methodName](symbol: string, market: string) where symbol is the crypto currency code (eg. BTC) and market is the referred market to use as refernce for the convertion (eg. USD)

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.crypto.daily('BTC', 'USD');

The output of the example will be the following (with parse mode set to transform):

{
   "description":"Daily Prices and Volumes for Digital Currency",
   "currency":{
      "code":"BTC",
      "name":"Bitcoin"
   },
   "exchange":{
      "code":"USD",
      "name":"United States Dollar"
   },
   "lastRefreshed":"2019-07-08 23:59:59",
   "timeZone":"UTC",
   "timeSeries":{
      "2019-07-08":{
         "USD":{
            "open":"11481.98207885",
            "high":"12373.74881946",
            "low":"11367.45957574",
            "close":"12311.24952666",
            "marketCap":"933835349.19382334"
         },
         "volume":"75852.19901291"
      }
      // repeted multiple time with all the give days
   }
}

weekly and monthly will be the same but timeSeries will be aggregated based on the week/month.

forex

This module provide functions related to the forex market. The following function are exposed through the module:

These are the relative parameters with the specific meaning (defined also in the service docs):

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.forex.intraday('USD', 'EUR');

The output of the example will be the following (with parse mode set to transform):

{
   "description":"FX Intraday (5min) Time Series",
   "from":{
      "code":"USD"
   },
   "to":{
      "code":"EUR"
   },
   "lastRefreshed":"2019-07-09 14:55:00",
   "timeZone":"UTC",
   "interval":"5min",
   "outputType":"Compact",
   "timeSeries":{
      "2019-07-09 14:55:00":{
         "open":"0.8924",
         "high":"0.8924",
         "low":"0.8920",
         "close":"0.8920"
      },
      // many others based on the interval value
   }
}

daily, weekly and monthly will be the same but the timeSeries will be aggregated based on the day/week/month.

These methods supports also csv output based on the signature defined above. In that case the wrapper will return you the string as the service without any sort of manipulation. Feel free to use libraries like CSVTOJSON or similar to handle the csv.

Example

const output = await q.forex.monthly('USD', 'EUR', 'csv');

the output will be a string with the following:

timestamp,open,high,low,close
2019-07-10,0.8794,0.8930,0.8792,0.8887
2019-06-30,0.8953,0.8967,0.8761,0.8794

stock

This module provide functions related to the stock market. The following function are exposed through the module:

These are the relative parameters with the specific meaning (defined also in the service docs):

intraday, daily, weekly, monthly

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.stock.intraday('MSFT');

The output of the example will be the following (with parse mode set to transform):

{
   "description":"Intraday (5min) open, high, low, close prices and volume",
   "symbol":"MSFT",
   "interval":"5min",
   "lastRefreshed":"2019-07-12 16:00:00",
   "timeZone":"US/Eastern",
   "outputType":"Compact",
   "timeSeries":{
      "2019-07-12 16:00:00":{
         "close":"138.8900",
         "high":"138.9800",
         "low":"138.6800",
         "open":"138.6800",
         "volume":"1736475"
      }
      // many others based on the interval value
   }
}

This output will be the same for the some of the other methods (daily, weekly, monthly) just the timeSeries data points will be related to the required frequency.

daily_adjusted, weekly_adjusted, monthly_adjusted

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.stock.intraday('MSFT');

The output of the example will be the following (with parse mode set to transform):

{
   "description":"Daily Time Series with Splits and Dividend Events",
   "symbol":"MSFT",
   "lastRefreshed":"2019-07-12",
   "timeZone":"US/Eastern",
   "outputType":"Compact",
   "timeSeries":{
      "2019-07-12":{
         "close":"138.9000",
         "adjustedClose":"138.9000",
         "high":"139.1300",
         "low":"138.0099",
         "open":"138.8500",
         "volume":"18936832",
         "dividendAmount":"0.0000",
         "splitCoefficient":"1.0000"
      }
      // many others based on the interval value
   }
}

quote

Example:

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.stock.quote('MSFT');

The output of the example will be the following (with parse mode set to transform):

{
   "symbol":"MSFT",
   "change":"0.5000",
   "changePercent":"0.3613%",
   "high":"139.1300",
   "latestTradingDay":"2019-07-12",
   "low":"138.0100",
   "open":"138.8500",
   "previousClose":"138.4000",
   "price":"138.9000",
   "volume":"17725458"
}

sectors

The sectors will be used to get the statistics about the sectors and their performance over the time as per API spec.

import alphavantagewrapper from 'alphavantage-wrapper';

const q = alphavantagewrapper({
  apiKey: '<your API key>',
});

const output = await q.sectors();

The output of the example will be the following (with parse mode set to transform):

{
   "description":"US Sector Performance (realtime & historical)",
   "lastRefreshed":"10:37 AM ET 07/12/2019",
   "realTimePerformance":{
      "communicationServices":"-0.02%",
      "consumerDiscretionary":"0.74%",
      "consumerStaples":"0.19%",
      "energy":"0.62%",
      "financials":"0.06%",
      "healthCare":"-0.97%",
      "industrials":"1.13%",
      "informationTechnology":"0.27%",
      "materials":"0.79%",
      "realEstate":"-0.44%",
      "utilities":"-0.79%"
   },
   "oneDayPerformance":{
      "communicationServices":"-0.09%",
      "consumerDiscretionary":"0.16%",
      "consumerStaples":"0.25%",
      "energy":"0.18%",
      "financials":"0.60%",
      "healthCare":"0.02%",
      "industrials":"0.71%",
      "informationTechnology":"0.34%",
      "materials":"0.43%",
      "realEstate":"-1.21%",
      "utilities":"0.04%"
   },
   "fiveDaysPerformance":{
      "communicationServices":"0.74%",
      "consumerDiscretionary":"1.19%",
      "consumerStaples":"0.07%",
      "energy":"1.89%",
      "financials":"0.23%",
      "healthCare":"-0.98%",
      "industrials":"-1.05%",
      "informationTechnology":"0.53%",
      "materials":"-2.34%",
      "realEstate":"-0.37%",
      "utilities":"0.36%"
   },
   "oneMonthPerformance":{
      "communicationServices":"6.87%",
      "consumerDiscretionary":"5.66%",
      "consumerStaples":"2.42%",
      "energy":"5.31%",
      "financials":"3.20%",
      "healthCare":"2.71%",
      "industrials":"1.96%",
      "informationTechnology":"4.94%",
      "materials":"0.73%",
      "realEstate":"1.58%",
      "utilities":"2.96%"
   },
   "threeMonthsPerformance":{
      "communicationServices":"4.34%",
      "consumerDiscretionary":"4.89%",
      "consumerStaples":"6.29%",
      "energy":"-4.69%",
      "financials":"6.25%",
      "healthCare":"1.88%",
      "industrials":"1.85%",
      "informationTechnology":"5.47%",
      "materials":"0.85%",
      "realEstate":"3.39%",
      "utilities":"5.92%"
   },
   "oneYearPerformance":{
      "communicationServices":"12.45%",
      "consumerDiscretionary":"9.57%",
      "consumerStaples":"13.51%",
      "energy":"-16.95%",
      "financials":"3.52%",
      "healthCare":"7.55%",
      "industrials":"4.75%",
      "informationTechnology":"12.17%",
      "materials":"-2.74%",
      "realEstate":"14.36%",
      "utilities":"17.32%"
   },
   "yearToDatePerformance":{
      "communicationServices":"22.25%",
      "consumerDiscretionary":"24.82%",
      "consumerStaples":"17.62%",
      "energy":"12.04%",
      "financials":"17.99%",
      "healthCare":"8.10%",
      "industrials":"19.69%",
      "informationTechnology":"29.86%",
      "materials":"14.44%",
      "realEstate":"21.61%",
      "utilities":"15.23%"
   },
   "threeYearsPerformance":{
      "communicationServices":"-6.68%",
      "consumerDiscretionary":"52.38%",
      "consumerStaples":"7.47%",
      "energy":"-6.66%",
      "financials":"51.13%",
      "healthCare":"27.20%",
      "industrials":"30.34%",
      "informationTechnology":"94.58%",
      "materials":"23.13%",
      "utilities":"15.99%"
   },
   "fiveYearsPerformance":{
      "communicationServices":"5.94%",
      "consumerDiscretionary":"83.09%",
      "consumerStaples":"31.97%",
      "energy":"-34.26%",
      "financials":"53.00%",
      "healthCare":"52.04%",
      "industrials":"40.12%",
      "informationTechnology":"121.73%",
      "materials":"15.79%",
      "utilities":"41.18%"
   },
   "tenYearsPerformance":{
      "communicationServices":"73.48%",
      "consumerDiscretionary":"461.42%",
      "consumerStaples":"158.62%",
      "energy":"36.67%",
      "financials":"212.80%",
      "healthCare":"262.58%",
      "industrials":"258.60%",
      "informationTechnology":"409.33%",
      "materials":"148.31%",
      "utilities":"126.03%"
   }
}

utils

This module provides utilities functions that can be used based at any time. The following function are exposed through the module:

cleaner

Example

console.log(
  q.utils.cleaner({
    'not nice key': 'value',
  }),
);

the output will be a string with the following:

{
  notnicekey: 'value';
}