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:
apiKey: string
(required): The API key to usebaseUrl: string
(optional): The base URL to use to make the request (default value: https://www.alphavantage.co/query
ideally will never change but is configurable)injectRawResponse: boolean
(optional): To use in case the parse mode is set to transform
or clean
to inject the raw response from the service into the output inside a property defined as raw
(default value: false
)convert: boolean
(optional): Define whether the user would like to convert the vales from the service in numbers rather than strings (default value: false
)validate: boolean
(optional): Define whether the user input should be validated (default value: false
); eg. validate currencies input, duration etc; to set to false if you're sure the input provided are correctparse: 'none'|'clean'|'transform'
(optional): Define the parse mode to be used handling the response from the APIs. none
will keep the original output, clean
will keep the original structure but clean the keys to be used easily. transform
will change the structure/keys with a new one more friendly (default value: 'transform'
)
After the Initialisation you'll get the following object with these properties:
exchangeRate: function
: Provides the exchange rate from currency to currecy (or also crypto currency to FIAT or crypto to crypto)crypto: object
: Provides a set of functions for the crypto marketforex: object
: Provides a set of functions for the forex marketstock: object
: Provides a set of functions for the stock marketsectors: function
: Provides the sectors statisticsutils: object
: Provides some utils to be used anytime- (TODO: more to add)
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:
daily
: returns daily rates of the give crypto currencyweekly
: returns weekly rates of the give crypto currencymonthly
: returns monthly rates of the give crypto currency
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"
}
}
}
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:
intraday(from_currency: string, to_currency: string, interval?: IntervalType, outputSize?: OutputSizeType, dataType?: DataTypeType)
: provides intraday rates for the given currenciesdaily(from_currency: string, to_currency: string, outputSize?: OutputSizeType, dataType?: DataTypeType)
: provides daily rates for the given currenciesweekly(from_currency: string, to_currency: string, dataType?: DataTypeType)
: provides weekly rates for the given currenciesmonthly(from_currency: string, to_currency: string, dataType?: DataTypeType)
: provides monthly rates for the given currencies
These are the relative parameters with the specific meaning (defined also in the service docs):
from_currency
: Currency symbol value (eg: USD)to_currency
: Currency symbol value (eg: EUR)interval
: Time interval between two consecutive data points in the time series. The following values are supported: 1min
, 5min
, 15min
, 30min
, 60min
(default: 5min)outputSize
: Accepts compact
or full
and will affect the number of output; compact will returns only the last 100 data points (default: compact)dataType
: Accepts json
or csv
and will affect the output of the API call (default: json)
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"
},
}
}
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:
intraday(symbol: string, interval?: IntervalType, outputSize?: OutputSizeType, dataType?: DataTypeType)
: provides the intraday stock value based on the given symboldaily(symbol: string, outputSize?: OutputSizeType, dataType?: DataTypeType)
: provides the daily stock value based on the given symboldaily_adjusted(symbol: string, outputSize?: OutputSizeType, dataType?: DataTypeType)
: provides the daily stock value based on the given symbol including splits and dividendweekly(symbol: string, dataType?: DataTypeType)
: provides the weekly stock value based on the given symbolweekly_adjusted(symbol: string, dataType?: DataTypeType)
: provides the weekly stock value based on the given symbol including dividendmonthly(symbol: string, dataType?: DataTypeType)
: provides the monthly stock value based on the given symbolmonthly_adjusted(symbol: string, dataType?: DataTypeType)
: provides the monthly stock value based on the given symbol including dividendquote(symbol: string, dataType?: DataTypeType)
: provides the quote rates for the given symbol/ticker
These are the relative parameters with the specific meaning (defined also in the service docs):
symbol
: Stock symbol value (eg: MSFT)interval
: Time interval between two consecutive data points in the time series. The following values are supported: 1min
, 5min
, 15min
, 30min
, 60min
(default: 5min)outputSize
: Accepts compact
or full
and will affect the number of output; compact will returns only the last 100 data points (default: compact)dataType
: Accepts json
or csv
and will affect the output of the API call (default: json)
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"
}
}
}
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"
}
}
}
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
: a small utility function that will remove the space or non standard chars from your json keys, convert it to a friendly object key and give it back. It's used internally in case of parse mode set to clean
. It can be used again in case you'd like to use the library without parse mode set to none or in case you'd like to use it for any other functionality
cleaner
Example
console.log(
q.utils.cleaner({
'not nice key': 'value',
}),
);
the output will be a string with the following:
{
notnicekey: 'value';
}