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?

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 20 years of annual data and 80 quarters of quarterly data.

Request

Method URL
GET https://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/financials
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/keyratios
Example https://www.gurufocus.com/api/public/user/{your personal token?}/stock/WMT/keyratios

Response

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

Example:

"Performance": { "1-W Change (%)": "-1.06", "4-W Change (%)": "0.49", "12-W Change (%)": "-5.82", "24-W Change (%)": "-14.55", "52-W Change (%)": "-2.66", "3-Y Change (%)": "2.88", "5-Y Change (%)": "9.89", "10-Y Change (%)": "5.58", "YTD Change (%)": "-13.74", "Beta": "0.75", "Short Ratio": "2.94", "Trade Volume": "9336754" }
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://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/quote
Example https://www.gurufocus.com/api/public/user/{your personal token?}/stock/WMT/quote

Response

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

Example:

{ "timestamp": "1461006301", "datetime": "2016-04-18 19:05:01 (UTC)", "price": "107.16", "price change": "-2.69", "price pct change": "-2.45", "open": "108.89", "volumn": "47665590", "low": "106.94", "high": "108.95", "currency": "USD" }
200 If Authorization is wrong, will return "Authorization required. Please follow the document."

5. Stock Historical Price data

Company historical price data.

Request

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

Response

Status Response
200 Response will be an object containing the 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://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/summary
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/gurus
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/stock/{symbol?}/insider
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/guru/{ids?}/picks/{date?}
Example https://www.gurufocus.com/api/public/user/{your personal token?}/guru/7/picks/2014-09-30

Type Params Values
GET {id}

Guru id got from https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/guru/{ids?}/aggregated
Example https://www.gurufocus.com/api/public/user/{your personal token?}/guru/7/aggregated

Type Params Values
GET {id}

Guru id got from https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/exchange_list
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/public/user/{your personal token?}/exchange_stocks/{exchange_name?}
Example https://www.gurufocus.com/api/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://www.gurufocus.com/api/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."

JAVA Code Sample

The following code using JAVA to output the P/E ratio in Valuation ratios 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://www.gurufocus.com/api/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 P/E ratio:

14.64

C# Code Sample

The following code using C# to output the P/E ratio in Valuation ratios 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://www.gurufocus.com/api/public/user/{your personal token?}/stock/WMT/keyratios";
    var json = webClient.DownloadString(URL);
    dynamic array = JsonConvert.DeserializeObject(json);

    var valuation = array.Valuation;

    Console.WriteLine(valuation["P/E"]);
  }


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

The C# output of P/E ratio:

14.61

Python Code Sample

The following code using Python 3+ to output the P/S ratio in Valuation ratios for WMT.

import urllib.request, json

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

content = response.read()
data = json.loads(content.decode('utf8'))
print(data['Valuation']['P/S'])


The Python output of P/S 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 ratios for WMT.

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

print_r($arr['Valuation']);

The output PHP array:

Array
(
     [P/E] => 14.74
     [P/S] => 0.49
     [P/B] => 3.07
     [P/E(NRI)] => 14.90
     [PEG] => 2.22
     [NCAV] => -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] => 10.70
     [Shiller P/E] => 15.02
     [EV/EBIT] => 10.54
     [EV/EBITDA] => 7.83
     [Price to Tangible Book] => 3.99
     [Yield On Cost] => 4.88
     [Price to Oprt. Cash Flow] => 8.79
     [Price to Free Cash Flow] => 15.93
     [Historical Median Price to Oprt. Cash Flow] => 9.76
     [Intrinsic Value: DCF (Earnings Based)] => 63.77
     [Intrinsic Value: DCF (FCF Based)] => 130.67
     [Intrinsic Value: Projected FCF] => 62.87
     [Forward P/E] => 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://www.gurufocus.com/api/public/user/{your personal token?}/stock/AAPL/keyratios"), "/Valuation", "")

The output will be:

R Code Sample

The following code using R to output the P/E ratio in Valuation ratios for WMT.

Prerequest Libraries:
jsonlite
curl

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

The output object of P/E ratio:

16.26
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)
FEEDBACK