From 3a082b68d8e9196525d48d4e941be82a8c04c94f Mon Sep 17 00:00:00 2001 From: Gadi Cohen Date: Wed, 24 May 2017 16:42:23 +0200 Subject: [PATCH] update README, add some (temporary) warnings to all methods --- README.md | 219 ++++----------------------------------------------- lib/index.js | 14 ++++ lib/quote.js | 5 ++ 3 files changed, 36 insertions(+), 202 deletions(-) diff --git a/README.md b/README.md index 435aa8b..0e77fd8 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,13 @@ The library handles fetching, parsing, and cleaning of CSV data and returns JSON Also check out [google-finance](https://github.com/pilwon/node-google-finance). +## NB: Yahoo API + +Yahoo's API has completely changed recently. This interim release is intended to get you up and running again quickly, but we're still working on it. Note also that Yahoo have stopped supporting their API for developers, so no guarantees can be made about service availability. This package relies entirely on open source contributions. ## Installation - $ npm install yahoo-finance + $ npm install --save yahoo-finance ## Usage @@ -26,16 +29,23 @@ yahooFinance.historical({ //... }); -yahooFinance.snapshot({ +// This replaces the deprecated snapshot() API +yahooFinance.quote({ symbol: 'AAPL', - fields: ['s', 'n', 'd1', 'l1', 'y', 'r'], -}, function (err, snapshot) { - //... + modules: [ 'price', 'summaryDetail' ] // see the docs for the full list +}, function (err, quotes) { + // ... }); + ``` * [See more comprehensive examples here.](https://github.com/pilwon/node-yahoo-finance/tree/master/examples) +* See the [full quote() docs](docs/quote.md) for the list of all possible +modules and the data they return. + +* See also the [deprecated snapshot() API](docs/snapshot.md) docs, for +reference. ## API @@ -137,201 +147,6 @@ yahooFinance.historical({ }); ``` -### Download Snapshot Data (single symbol) - -```js -yahooFinance.snapshot({ - symbol: SYMBOL, - fields: FIELDS // ex: ['s', 'n', 'd1', 'l1', 'y', 'r'] -}, function (err, snapshot) { - /* - { - symbol: 'AAPL', - name: 'Apple Inc.', - lastTradeDate: '11/15/2013', - lastTradePriceOnly: '524.88', - dividendYield: '2.23', - peRatio: '13.29' - } - */ -}); -``` - -### Download Snapshot Data (multiple symbols) - -```js -yahooFinance.snapshot({ - symbols: [SYMBOL1, SYMBOL2], - fields: FIELDS // ex: ['s', 'n', 'd1', 'l1', 'y', 'r'] -}, function (err, snapshot) { - /* - { - AAPL: { - symbol: 'AAPL', - name: 'Apple Inc.', - lastTradeDate: '11/15/2013', - lastTradePriceOnly: '524.88', - dividendYield: '2.23', - peRatio: '13.29' - }, - GOOGL: { - symbol: 'GOOGL', - name: 'Google Inc.', - lastTradeDate: '11/15/2013', - lastTradePriceOnly: '1034.23', - dividendYield: 'N/A', - peRatio: '28.17' - } - } - */ -}); -``` - - - -### Fields - -``` -s: Symbol -``` - -#### Pricing - -``` -a: Ask -b: Bid -b2: Ask (Realtime) -b3: Bid (Realtime) -p: Previous Close -o: Open -``` - -#### Dividends - -``` -y: Dividend Yield -d: Dividend Per Share -r1: Dividend Pay Date -q: Ex-Dividend Date -``` - -#### Date - -``` -c1: Change -c: Change And Percent Change -c6: Change (Realtime) -k2: Change Percent (Realtime) -p2: Change in Percent -d1: Last Trade Date -d2: Trade Date -t1: Last Trade Time -``` - -#### Averages - -``` -c8: After Hours Change (Realtime) -c3: Commission -g: Day’s Low -h: Day’s High -k1: Last Trade (Realtime) With Time -l: Last Trade (With Time) -l1: Last Trade (Price Only) -t8: 1 yr Target Price -m5: Change From 200-day Moving Average -m6: Percent Change From 200-day Moving Average -m7: Change From 50-day Moving Average -m8: Percent Change From 50-day Moving Average -m3: 50-day Moving Average -m4: 200-day Moving Average -``` - -#### Misc - -``` -w1: Day’s Value Change -w4: Day’s Value Change (Realtime) -p1: Price Paid -m: Day’s Range -m2: Day’s Range (Realtime) -g1: Holdings Gain Percent -g3: Annualized Gain -g4: Holdings Gain -g5: Holdings Gain Percent (Realtime) -g6: Holdings Gain (Realtime) -``` - -#### 52 Week Pricing - -``` -k: 52-week High -j: 52-week Low -j5: Change From 52-week Low -k4: Change From 52-week High -j6: Percent Change From 52-week Low -k5: Percebt Change From 52-week High -w: 52-week Range -``` - -#### System Info - -``` -i: More Info -j1: Market Capitalization -j3: Market Cap (Realtime) -f6: Float Shares -n: Name -n4: Notes -s1: Shares Owned -x: Stock Exchange -j2: Shares Outstanding -``` - -#### Volume - -``` -v: Volume -a5: Ask Size -b6: Bid Size -k3: Last Trade Size -a2: Average Daily Volume -``` - -#### Ratio - -``` -e: Earnings Per Share -e7: EPS Estimate Current Year -e8: EPS Estimate Next Year -e9: EPS Estimate Next Quarter -b4: Book Value -j4: EBITDA -p5: Price per Sales -p6: Price per Book -r: PE Ratio -r2: PE Ratio (Realtime) -r5: PEG Ratio -r6: Price Per EPS Estimate Current Year -r7: Price Per EPS Estimate Next Year -s7: Short Ratio -``` - -#### Misc - -``` -t7: Ticker Trend -t6: Trade Links -i5: Order Book (Realtime) -l2: High Limit -l3: Low Limit -v1: Holdings Value -v7: Holdings Value (Realtime) -s6: Revenue -e1: Error Indication (returned for symbol changed or invalid) -``` - - ### Specifying request options Optionally request options (such as a proxy) can be specified by inserting an @@ -353,9 +168,9 @@ yahooFinance.historical({ }); -yahooFinance.snapshot({ +yahooFinance.quote({ symbol: SYMBOL, - fields: FIELDS // ex: ['s', 'n', 'd1', 'l1', 'y', 'r'] + modules: MODULES // ex: ['price', 'summaryDetail'] }, httpRequestOptions, function (err, snapshot) { // Result }); diff --git a/lib/index.js b/lib/index.js index 0fa696a..af173f7 100644 --- a/lib/index.js +++ b/lib/index.js @@ -230,6 +230,12 @@ function historical(options, optionalHttpRequestOptions, cb) { optionalHttpRequestOptions = undefined; } + console.warn("[yahoo-finance] Warning, Yahoo completely changed their API " + + "recently. We've done our best to maintain backwards compatibility in " + + "historical(), but please keep an eye out to ensure results are what you " + + "expect and report any issues. This warning will be removed in our next " + + "release."); + return getCrumb(symbols[0]) .then(function(crumb) { return Promise.map(symbols, function (symbol) { @@ -268,6 +274,14 @@ function historical(options, optionalHttpRequestOptions, cb) { } function snapshot(options, optionalHttpRequestOptions, cb) { + throw new Error("[yahoo-finance] snapshot() is not available in this " + + "release. Yahoo have completely changed their API recently. In our " + + "next release, we will have a compatibility-layer in place so that " + + "snapshot() works as expected for SOME options. Unfortunately, Yahoo's " + + "new API does not provide all the same data, so 100% compatibility is " + + "impossible. For this reason, please be advised that snapshot() is " + + "DEPRECATED. See our in-progress quote() API for an alternative."); + var symbols = options.symbols || _.flatten([options.symbol]); options = _.clone(options); _sanitizeSnapshotOptions(options); diff --git a/lib/quote.js b/lib/quote.js index d452e0e..8a7a484 100644 --- a/lib/quote.js +++ b/lib/quote.js @@ -45,6 +45,11 @@ function transformDates(result) { } function quote(options, optionalHttpRequestOptions, cb) { + console.warn("[yahoo-finance] Warning, Yahoo completely changed their API " + + "recently. quote() replaces the deprecated snapshot(), but is brand " + + "new. Please report any issues. This notice will be removed in the " + + "next release."); + if (_.isString(options)) { options = { symbol: options }; if (_.isArray(optionalHttpRequestOptions)) {