GuruFocus.com API Version 3.0.0 (07/23/2015)

In computer programming, an application programming interface (API) is a set of routines, protocols, and tools for building software applications.

GuruFocus.com API is using REST architecture. The format of response is JSON. You can use any programming language you like to build your own winning strategy based on our Guru/Insider/Financial data.

Questions?  Turorial

Trial membership only allow 100 requests.

1. Obtain your personal API Token

GuruFocus API is for Premium and PremiumPLUS Members use only. Please obtain your personal Token now.

2. Company Financial data

Company Financials up to 30 years of annual data and 120 quarters of quarterly data.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/financials
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/financials

Response

Status Response
200 Response will be an object containing the financial data.

Example:

"financials": { "annuals": { "Fiscal Year": [ "1996-01", "1997-01", "1998-01", "1999-01", "2000-01", "2001-01", "2002-01", "2003-01", "2004-01", "2005-01", "2006-01", "2007-01", "2008-01", "2009-01", "2010-01", "2011-01", "2012-01", "2013-01", "2014-01", "2015-01" ], "income_statement": {"Revenue": ["93627", "104859", "117958", "137634", "165013", "191329", "205823", "231577", "258681", "284310", "312101", "348368", "378476", "404374", "408085", "421849", "446950", "468651", "476294", "485651"], "Cost of Goods Sold":["73260", "82047", "91804", "106853", "127289", "147387", "159097", "178299", "198747", "216832", "237649", "263979", "286350", "304056", "304444", "314946", "335127", "352297", "358069", "365086"]... } }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

3. Company key statistics data

Company current key statistics data.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/keyratios
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios

Response

Status Response
200 Response will be an object containing the key statistics data.

Example:

"Price": { "Beta": "0.07", "Float": "1450.1648", "Day's High": "80.88", "Day's Low": "77.85", "Day's Open": "80.61", "3-Month relative to S&P Total Return %": "1.22", "1-Week relative to S&P Total Return %": "-0.26", "6-Month relative to S&P Total Return %": "10.88", "1-Month relative to S&P Total Return %": "6.87", "12-Month relative to S&P Total Return %": "2.22", "YTD relative to S&P Total Return %": "8.50", "10-Year Annualized Total Return %": "8.29", "3-Month Total Return %": "2.52", "1-Week Total Return %": "-1.26", "6-Month Total Return %": "14.28", "3-Year Annualized Total Return %": "4.30", "1-Month Total Return %": "5.67", "12-Month Total Return %": "13.92", "5-Year Annualized Total Return %": "4.61", "YTD Total Return %": "17.90", "Price (3y High)": "90.97", "Price (3y Low)": "56.30", "Price (52w High)": "81.99", "Price (52w Low)": "65.28", "Price (5y High)": "90.97", "Price (5y Low)": "56.30", "Day's Change": "-2.03", "Short Percentage of Float": "2.89", "Short Percentage Of Shares Outstanding": "1.39", "Short Ratio": "5.86", "Avg Daily Trade Volume (2 Months)": "7708980", "Day's Volume": "19119528", "Price (10y High)": "90.97", "Price (10y Low)": "42.09", "Short Interest": "41.9459", "Total 2-Month Average Trade Volume": "7714152", "Total Daily Trade Volume": "16960689", "20-Day SMA": "80.43", "50-Day SMA": "77.68", "200-Day SMA": "73.32", "14-Day RSI": "54.69", "6-Month Price Index": "1.12" }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

4. Stock quote data

Company current quote data.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbols?}/quote
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT,AAPL/quote

Response

Status Response
200 Support at most 100 stocks split by ","(eg. WMT,AAPL). Response will be an object containing the stock quote data.

Example:

[ { "timestamp": "1511297491", "datetime": "2017-11-21 15:51:31 (UTC)", "price": "96.44", "price change": "-1.04", "price pct change": "-1.07", "open": "97.74", "volumn": "9740854", "low": "96.40", "high": "97.92", "currency": "USD" }, { "timestamp": "1511297457", "datetime": "2017-11-21 15:50:57 (UTC)", "price": "173.08", "price change": "3.10", "price pct change": "1.82", "open": "170.78", "volumn": "21765953", "low": "170.78", "high": "173.70", "currency": "USD" } ]
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

5. Stock Historical Price/Unadjusted Price data

Company historical price/unadjusted price data.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/price(or unadjusted_price)
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/price(or unadjusted_price)

Response

Status Response
200 Response will be an object containing the price(or unadjusted price) data. Data format : date , split-adjusted close price

Example:

[ [ "01-02-1990", 5.891 ], [ "01-03-1990", 5.891 ], [ "01-05-1990", 5.859 ] ]
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

6. Stock Summary Data

Company current price, valuations ratios and ranks, summary information.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/summary
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/summary

Response

Status Response
200 Response will be an object containing the stock summary data.

Example:

"ratio": { "Current Ratio": { "indu": { "global_rank": "245", "indu_med": "1.21", "indu_tot": "336" }, "value": "0.89", "status": "1", "his": { "low": "0.80", "high": "1.64" } }, "Quick Ratio": { "indu": { "global_rank": "314", "indu_med": "0.75", "indu_tot": "336" }, "value": "0.23", "status": "1", "his": { "low": "0.12", "high": "0.28" } } ...... }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

7. Real-time Guru Trades of Specific Companies

Real-time Guru stock trades and current holdings data for specific companies.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/gurus
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/gurus

Response

Status Response
200 Response will be an object containing the guru picks data.

Example:

{ "WMT": { "picks": [ { "guru": "Warren Buffett", "date": "2015-03-31", "action": "Reduce", "impact": "0", "price_min": "80.69", "price_max": "90.47", "Avg": "85.11", "comment": "Reduce 0.00%", "current_shares": "60385293" }, { "guru": "Dodge & Cox", "date": "2015-03-31", "action": "Add", "impact": "0.01", "price_min": "80.69", "price_max": "90.47", "Avg": "85.11", "comment": "Add 0.37%", "current_shares": "30876839" } } }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

8. Real-Time Insider Trades of Specific Companies

Company Real-time insider trades data.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/insider
Example https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/insider

Response

Status Response
200 Response will be an object containing the insider data.

Example:

{ "WMT": [ { "insider": "Whaley Steven P", "position": "Senior Vice President", "date": "2015-03-05", "type": "S", "trans_share": "2,400", "final_share": "28,189", "price": "83.28", "cost": "199.9", "change": "-13.39" }, { "insider": "BREWER ROSALIND G", "position": "Executive Vice President", "date": "2014-11-25", "type": "S", "trans_share": "7,000", "final_share": "181,535", "price": "84.96", "cost": "594.7", "change": "-15.1" } ] }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

9. Guru List

List all gurus and personlized gurus.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/gurulist

Response

Status Response
200 Response will be an object containing the list of guru names with ids.

Example:

{ "all": { "us": [ [ "1", "Vanguard Health Care Fund" ] ] ...}
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

10. Guru Stock Picks

List guru stock picks using guru id and date.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/guru/{ids?}/picks/{date?}
Example https://api.gurufocus.com/public/user/{your personal token?}/guru/7/picks/2014-09-30

Type Params Values
GET {id}

Guru id got from https://api.gurufocus.com/public/user/{your personal token?}/gurulist

string
GET {date?}

Starting date for guru picks. Ending date is current date. Date format is YYYY-mm-dd.

 string

Response

Status Response
200 Response will be an object containing the list of gurus stock picks.

Example:

{ "Jean-Marie Eveillard": { "port": [ { "symbol": "ARQL", "exchange": "NAS", "company": "Arqule Inc", "price": "2.09", "currency": null, "GuruName": "Jean-Marie Eveillard", "type": "realtime", "RecmDate": "2015-04-29", "RecmAction": "Add", "trans_share": "0.02", "RecmPrice": "2.05", "price_min": "2.05", "price_max": "2.05", "change": "2", "share_current": "8719968", "industry": "Biotechnology", "sector": "Healthcare", "symbol_ori": "ARQL", "currency_txt": "USD", "comment": "Add 96.18%" } ] ...} }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

11. Guru Aggregated Portfolio

List aggregated portfolios.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/guru/{ids?}/aggregated
Example https://api.gurufocus.com/public/user/{your personal token?}/guru/7/aggregated

Type Params Values
GET {id}

Guru id got from https://api.gurufocus.com/public/user/{your personal token?}/gurulist

string

Response

Status Response
200 Response will be an object containing the list of gurus portfolios.

Example:

{ "7": { "summary": { "firm": "Berkshire Hathaway", "num_new": "2", "number_of_stocks": "47", "equity": "109365", "turnover": "3", "country": "", "date": "2014-12-31" }, "port": [ { "13f_date": "2014-12-31", "share": "463458123", "symbol": "WFC", "exchange": "NYSE", "industry": "Banks - Global", "sector": "Financial Services", "company": "Wells Fargo & Co", "price": "55.61", "currency": null, "52l": "16.5", "52h": "1.2", "mktcap": "286051.100", "pe": "13.50", "yield": "2.50", "change": "0.00", "value": "25406800.00", "position": "23.2", "impact": "0", "pct": "9.00", "symbol_ori": "WFC", "currency_txt": "USD" } ]... } }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

12. Exchange List

List worldwide exchanges.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/exchange_list
Example https://api.gurufocus.com/public/user/{your personal token?}/exchange_list

Response

Status Response
200 Response will be an object containing the list of exchanges.

Example:

{ "USA": [ "NAS", "NYSE", "OTCPK", "", "OTCBB", "AMEX", "ARCA", "ASE" ], "Canada": [ "TSXV", "TSX", "XCNQ" ], ... }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

13. Stock List in Exchange

Get list of all stocks of a particular exchange.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/exchange_stocks/{exchange_name?}
Example https://api.gurufocus.com/public/user/{your personal token?}/exchange_stocks/NYSE

Response

Status Response
200 Response will be an object containing the list of stocks in the exchange.

Example:

[ { "symbol": "A", "exchange": "NYSE", "company": "Agilent Technologies Inc", "currency": "USD" }, { "symbol": "AA", "exchange": "NYSE", "company": "Alcoa Inc", "currency": "USD" } ... ]
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

14. Latest Insider Trades

Get list of latest insider trades ordered by insider transctions time.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/insider_updates

Response

Status Response
200 Response will be an object containing the list of insider trades ordered by transction date.

Example:

[ { "insider": "Black Mark A", "position": "EVP", "trans_date": "2016-04-11", "type": "S", "trans_share": "2,678", "final_share": "43,586", "price": "248.16", "cost": "664.6" }, { "insider": "Blachar Doron", "position": "CFO", "trans_date": "2016-04-11", "type": "S", "trans_share": "13,158", "final_share": "0", "price": "40.37", "cost": "531.2" }, ... ]
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

15. Dividend History

Get 30 years dividend history data of a stock.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/dividend

Response

Status Response
200 Response will be an object containing the list of dividend history object.

Example:

[ { "amount": "0.510", "ex_date": "2017-12-07", "record_date": "2017-12-08", "pay_date": "2018-01-02", "type": "Cash Div.", "currency": "USD" }, { "amount": "0.510", "ex_date": "2017-08-09", "record_date": "2017-08-11", "pay_date": "2017-09-05", "type": "Cash Div.", "currency": "USD" }, { "amount": "0.510", "ex_date": "2017-05-10", "record_date": "2017-05-12", "pay_date": "2017-06-05", "type": "Cash Div.", "currency": "USD" }, { "amount": "0.510", "ex_date": "2017-03-08", "record_date": "2017-03-10", "pay_date": "2017-04-03", "type": "Cash Div.", "currency": "USD" }, ... { "amount": "0.002", "ex_date": "1985-06-17", "record_date": "1985-06-21", "pay_date": "1985-07-09", "type": "Cash Div.", "currency": "USD" }, { "amount": "0.002", "ex_date": "1985-03-18", "record_date": "1985-03-22", "pay_date": "1985-04-10", "type": "Cash Div.", "currency": "USD" }, { "amount": "0.002", "ex_date": "1984-12-07", "record_date": "1984-12-13", "pay_date": "1985-01-04", "type": "Cash Div.", "currency": "USD" } ]
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

16. Analyst Estimate

Get Analyst Estimate data of a stock.

Request

Method URL
GET https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/analyst_estimate

Response

Status Response
200 Response will be an object containing the annual and quarter estimate data.

Example:

{ "annual": { "date": [ "2019-01", "2020-01" ], "revenue_estimate": [ 510691.5, 520968.1 ], "ebit_estimate": [ 23043.48, 23188.01 ], "ebitda_estimate": [ 33599.2, 33668 ], "dividend_estimate": [ 2.136, 2.1367 ], "per_share_eps_estimate": [ 4.9189, 5.0805 ], "eps_nri_estimate": [ 4.9189, 5.0805 ], "eps_growth_rate_estimate": 5.88 }, "quarter":{ ... } }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

JAVA Code Sample

The following code using JAVA to output the EPV in Valuation for WMT.

Prerequest Libraries:
org-json-java
Commons IO

import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;
import org.apache.commons.io.IOUtils;
import org.json.JSONException;
import org.json.JSONObject;
import org.json.JSONTokener;

public class GuruFocusAPI {
  public static void main(String[] args) throws MalformedURLException, JSONException, IOException {
    JSONObject jo = (JSONObject) new JSONTokener(IOUtils.toString(new URL("https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios"))).nextValue();
    JSONObject valuation = jo.getJSONObject("Valuation");
    String epv = valuation.getString("EPV");
    System.out.println(epv);
  }

}

The output JAVA String of EPV:

85.68

C# Code Sample

The following code using C# to output the PE Ratio in Valuation Ratio for WMT.

First, we will need to download the json.net library from https://json.codeplex.com/

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;


namespace gurufocus
{
 class Program
 {
 static void Main(string[] args)
 {
  using (var webClient = new System.Net.WebClient())
  {
    String URL = "https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios";
    var json = webClient.DownloadString(URL);
    dynamic array = JsonConvert.DeserializeObject(json);

    var valuation = array.["Valuation Ratio"];

    Console.WriteLine(valuation["PE Ratio"]);
  }


  Console.WriteLine("Press any key to exit.");
  Console.ReadKey();
 }
 }
}

The C# output of PE Ratio:

14.61

Python Code Sample

The following code using Python 3+ to output the PS Ratio in Valuation Ratio for WMT.

import urllib.request, json

response = urllib.request.urlopen('https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios')

content = response.read()
data = json.loads(content.decode('utf8'))
print(data['Valuation Ratio']['PS Ratio'])


The Python output of PS Ratio:

0.49

If you encountered "403 Forbidden error", please see this page.

This is probably because of mod_security or some similar server security feature which blocks known spider/bot user agents (urllib uses something like python urllib/3.3.0, it's easily detected). Try setting a known browser user agent.

PHP Code Sample

The following code using PHP to output the Valuation Ratio for WMT.

$url = 'https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios';
$content = file_get_contents($url);
$arr = json_decode($content, true);

print_r($arr['Valuation Ratio']);

The output PHP array:

Array
(
     [PE Ratio] => 14.74
     [PS Ratio] => 0.49
     [PB Ratio] => 3.07
     [PE Ratio without NRI] => 14.90
     [PEG Ratio] => 2.22
     [Net Current Asset Value] => -27.55
     [Median PS Value] => 79.38
     [Graham Number] => 45.72
     [Peter Lynch Fair Value] => 26.91
     [Earnings Yield %] => 9.49
     [Forward Rate of Return (Yacktman) %] => 10.70
     [Shiller PE Ratio] => 15.02
     [EV-to-EBIT] => 10.54
     [EV-to-EBITDA] => 7.83
     [Price-to-Tangible-Book] => 3.99
     [Price-to-Operating-Cash-Flow] => 8.79
     [Price-to-Free-Cash-Flow] => 15.93
     [Price-to-Operating-Cash-Flow (10y Median)] => 9.76
     [Intrinsic Value: DCF (Earnings Based)] => 63.77
     [Intrinsic Value: DCF (FCF Based)] => 130.67
     [Intrinsic Value: Projected FCF] => 62.87
     [Forward PE Ratio] => 15.17
)

How to use GuruFocus API in Google Spreadsheet in less than 5 minutes

Using the awesome ImportJSON tool in combination with this wonderful script, you are able to get the GuruFocus API data into a google spreadsheet in a matter of minutes. Here’s how:

  1. Create a new Google Spreadsheet.
  2. Click on Tools -> Script Editor.
  3. Click Create script for Spreadsheet.
  4. Delete the placeholder content and paste the code from this script.
  5. Rename the script to ImportJSON.gs and click the save button.
  6. Back in the spreadsheet, in a cell, you can type “=ImportJSON()” and begin filling out it’s parameters.

For example, if you want to use GuruFocus API to get valuation ratios in Google Spreadsheet, just try the following function in your spreadsheet

=ImportJSON(("https://api.gurufocus.com/public/user/{your personal token?}/stock/AAPL/keyratios"), "/Valuation", "")

The output will be:

R Code Sample

The following code using R to output the EPV in Valuation for WMT.

Prerequest Libraries:
jsonlite
curl

library(jsonlite)
document <- fromJSON("https://api.gurufocus.com/public/user/{your personal token?}/stock/WMT/keyratios");
epv <- document$Valuation$`EPV`
cat(epv)

The output object of EPV:

85.68
Get WordPress Plugins for easy affiliate links on Stock Tickers and Guru Names | Earn affiliate commissions by embedding GuruFocus Charts
GuruFocus Affiliate Program: Earn up to $400 per referral. ( Learn More)

GF Chat

{{numOfNotice}}
FEEDBACK