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.
Trial membership only allow 100 requests.
| Membership | API request limit |
|---|---|
| Premium | 2,000 |
| PremiumPlus | 20,000 |
| Profassional | 50,000 |
| Profassional with unlimited api query | Unlimited |
Video Tutorial
GuruFocus API is for 
Premium and
PremiumPLUS 
Members use only. Please obtain your personal Token
now.
Company Financials up to 30 years of annual data and 120 quarters of quarterly data.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the financial data. Different companies have different financial templates, and each template has different financial fields. GuruFocus now changes the new financial API to be in accordance with the template shown in 30-Y financials page, effective 2020-01-03. Any recent financial API or 30-year financials data changes can be found HERE.
Example:
"financials": {
"financial_template_parameters": {
"ind_template": "N",
"REITs": "N",
"IsDirect": "Indirect Method"
},
"annuals": {
"Fiscal Year": [
"1989-12",
"1990-12",
"1991-12",
"1992-12",
"1993-12",
"1994-12",
"1995-12",
"1996-12",
"1997-12",
"1998-12",
"1999-12",
"2000-12",
"2001-12",
"2002-12",
"2003-12",
"2004-12",
"2005-12",
"2006-12",
"2007-12",
"2008-12",
"2009-12",
"2010-12",
"2011-12",
"2012-12",
"2013-12",
"2014-12",
"2015-12",
"2016-12",
"2017-12",
"2018-12",
"TTM"
],
"Preliminary": [],
"per_share_data_array": {
"Revenue per Share": [],
"EBITDA per Share": [],
"EBIT per Share": [],
"Earnings per Share (Diluted)": [],
"EPS without NRI": [],
"Owner Earnings per Share (TTM)": [],
"Free Cash Flow per Share": [],
"Operating Cash Flow per Share": [],
"Dividends per Share": [],
"Book Value per Share": [],
"Tangible Book per Share": [],
"Total Debt per Share": [],
"Month End Stock Price": []
},
"common_size_ratios": {
"ROE %": [],
"ROE % Adjusted to Book Value": [],
"ROA %": [],
"Return-on-Tangible-Equity": [],
"Return-on-Tangible-Asset": [],
"ROC (Joel Greenblatt) %": [],
"ROC (ROIC) %": [],
"WACC %": [],
"Effective Interest Rate on Debt %": [],
"Gross Margin %": [],
"Operating Margin %": [],
"Net Margin %": [],
"FCF Margin %": [],
"Debt-to-Equity": [],
"Equity-to-Asset": [],
"Debt-to-Asset": [],
"Gross-Profit-to-Asset %": [],
"Asset Turnover": [],
"Dividend Payout Ratio": [],
"Days Sales Outstanding": [],
"Days Payable": [],
"Days Inventory": [],
"Cash Conversion Cycle": [],
"Inventory Turnover": [],
"COGS-to-Revenue": [],
"Inventory-to-Revenue": []
},
"income_statement": {},
"balance_sheet": {},
"cashflow_statement": {},
"valuation_ratios": {},
"valuation_and_quality": {}
},
"quarterly": {}
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Company current key statistics data.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the key statistics data.
Example:
"Basic": {
"Price Updated Time": "2019-06-07 15:31:06 (EDT)"
},
"Fundamental": {
"Currency": "USD",
"Total Assets (Current)": "234544.000",
"Book Value per Share": "23.63",
"Cash-to-Debt": "0.16",
"Cash-to-Debt (10y High)": "0.29",
"Cash-to-Debt (10y Low)": "0.00",
"Cash-to-Debt (10y Median)": "0.12",
"Share Class Description": "",
"Headquarter Country": "USA",
"Current Ratio": "0.77",
"Current Ratio (10y High)": "1.86",
"Current Ratio (10y Low)": "0.73",
"Current Ratio (10y Median)": "0.92",
"Days Inventory": "42.42",
"Days Inventory (10y High)": "45.30",
"Days Inventory (10y Low)": "40.07",
"Days Inventory (10y Median)": "43.11",
"Days Sales Outstanding": "3.78",
"Days Sales Outstanding (10y High)": "5.27",
"Days Sales Outstanding (10y Low)": "3.78",
"Days Sales Outstanding (10y Median)": "4.46",
"Debt-to-Equity": "0.85",
"Debt-to-Revenue": "0.11",
"EPS": "2.89",
"Equity-to-Asset": "0.29",
"Equity-to-Asset (10y High)": "0.48",
"Equity-to-Asset (10y Low)": "0.29",
"Equity-to-Asset (10y Median)": "0.39",
"Enterprise Value (Current M)": "360302.040",
"Enterprise Value ($M)": "360302.040",
"Piotroski F-Score": 5,
"Piotroski F-Score (10y High)": 9,
"Piotroski F-Score (10y Low)": 2,
"Piotroski F-Score (10y Median)": 6,
"Insider Ownership": "1.75",
"Institutional Ownership": "45.64",
"Interest Coverage": "8.74",
"Interest Coverage (10y High)": "12.33",
"Interest Coverage (10y Low)": "8.74",
...
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Company current quote data.
| 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 |
| 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": 1559935866,
"Price Updated Time": "2019-06-07 15:31:06 (EDT)",
"Current Price": 106.06,
"Day's Change": 0.9,
"open": 105.23,
"Day's Volume": 6621731,
"low": 105.05,
"high": 106.36,
"Currency": "USD",
"Symbol": "WMT",
"Exchange": "NYSE",
"Price Change": 0.95
},
{
"timestamp": 1559935837,
"Price Updated Time": "2019-06-07 15:30:37 (EDT)",
"Current Price": 190.15,
"Day's Change": 2.66,
"open": 186.51,
"Day's Volume": 30610492,
"low": 185.77,
"high": 191.92,
"Currency": "USD",
"Symbol": "AAPL",
"Exchange": "NAS",
"Price Change": 4.93
}
]
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Company historical price/unadjusted price data.
| 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) |
| 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." |
Company current price, valuations ratios and ranks, summary information.
| 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 |
| 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." |
Real-time Guru stock trades and current holdings data for specific companies.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the guru picks data.
Example:
{
"WMT": {
"picks": [
{
"guru": "VANGUARD GROUP INC",
"date": "2019-03-31",
"action": "Add",
"impact": "0",
"price_min": "92.86",
"price_max": "102.2",
"Avg": "97.26",
"comment": "Add 0.43%",
"current_shares": "129186475",
"guru_id": "2402"
},
{
"guru": "BlackRock Inc.",
"date": "2019-03-31",
"action": "Add",
"impact": "0",
"price_min": "92.86",
"price_max": "102.2",
"Avg": "97.26",
"comment": "Add 0.25%",
"current_shares": "87313606",
"guru_id": "2453"
}
]
}
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Company Real-time insider trades data.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the insider data.
Example:
{
"WMT": [
{
"position": "10% Owner",
"date": "2019-05-23",
"type": "S",
"trans_share": "841,920",
"final_share": "1,439,840,492",
"price": "101.44",
"cost": "85404.4",
"insider": "WALTON JIM C",
"change": "4.55"
},
{
"position": "10% Owner",
"date": "2019-05-23",
"type": "S",
"trans_share": "841,920",
"final_share": "1,429,086,992",
"price": "101.44",
"cost": "85404.4",
"insider": "WALTON ALICE L",
"change": "4.55"
}
}
]
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
List all gurus and personlized gurus.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/gurulist |
| 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." |
List guru stock picks using guru id and date.
| 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/2019-03-31 |
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the list of gurus stock picks.
Example:
{
"Warren Buffett": {
"port": [
{
"symbol": "JPM",
"exchange": "NYSE",
"company": "JPMorgan Chase & Co",
"price": 109.16,
"currency": "$",
"GuruName": "Warren Buffett",
"type": "quarterly",
"RecmDate": "2019-03-31",
"RecmAction": "Add",
"trans_share": 0.48,
"RecmPrice": 103,
"price_min": 97.11,
"price_max": 107.19,
"change": 5.98,
"share_current": 59514932,
"industry": "Banks - Global",
"sector": "Financial Services",
"symbol_ori": "JPM",
"currency_txt": "USD",
"comment": "Add 18.75%"
},
...
]
}
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
List aggregated portfolios.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the list of gurus portfolios.
Example:
{
"7": {
"summary": {
"firm": "Berkshire Hathaway",
"num_new": 1,
"number_of_stocks": 48,
"equity": 199484,
"turnover": 1,
"country": "USA",
"date": "2019-05-15"
},
"port": [
{
"13f_date": "2019-03-31",
"share": 249589329,
"symbol": "AAPL",
"exchange": "NAS",
"industry": "Consumer Electronics",
"sector": "Technology",
"company": "Apple Inc",
"price": 190.15,
"currency": "$",
"52l": 33.91,
"52h": 18.55,
"mktcap": "874894.420",
"pe": "16.00",
"yield": "1.56",
"change": 0,
"value": 47409494,
"position": 23.77,
"impact": 0,
"pct": 5.42,
"symbol_ori": "AAPL",
"currency_txt": "USD"
}
...
]
}
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
List worldwide exchanges.
| 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 |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the list of exchanges.
Example:
{
"USA": [
"NAS",
"NYSE",
"OTCPK",
"",
"OTCBB",
"AMEX",
"ARCA",
"IEXG",
"BATS",
"GREY"
],
"Canada": [
"TSXV",
"TSX",
"XCNQ",
"NEOE"
]
...
}
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Get list of all stocks of a particular exchange.
| 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 |
| 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",
"industry": "Medical Diagnostics & Research",
"sector": "Healthcare",
"subindustry": "Diagnostics & Research"
},
{
"symbol": "AA",
"exchange": "NYSE",
"company": "Alcoa Corp",
"currency": "USD",
"industry": "Metals & Mining",
"sector": "Basic Materials",
"subindustry": "Aluminum"
}
...
]
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Get list of latest insider trades ordered by insider transctions time.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/insider_updates |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the list of insider trades ordered by
transction date.
Example:
[
{
"symbol": "NAS:TECD",
"exchange": "NAS",
"position": "Director",
"date": "2019-06-07",
"type": "S",
"trans_share": 2200,
"final_share": 10637,
"price": 95.29,
"cost": 209.6,
"insider": "HARCZAK HARRY J JR"
},
{
"symbol": "NYSE:WCC",
"exchange": "NYSE",
"position": "Director",
"date": "2019-06-07",
"type": "S",
"trans_share": 1513,
"final_share": 11151,
"price": 48.97,
"cost": 74.1,
"insider": "UTTER LYNN M"
}
...
]
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Get 30 years dividend history data of a stock.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/dividend |
| 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." |
Get Analyst Estimate data of a stock.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/stock/{symbol?}/analyst_estimate |
| 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." |
Get list of personal portfolios.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/portfolio/my_portfolios |
| Status | Response |
|---|---|
| 200 | Response will be an object containing the list of stocks in the exchange.
Example:
[
{
"id": "123456",
"uid": "654321",
"portid": "123456",
"portname": "Portfolio 1",
"modified": "1541386018",
"intro": "764850",
"private": 0,
"email": "0",
"alert": "",
"settings": "",
"created": "2018-11-04 20:46:58",
"num_stocks": 10,
"p_all": null,
"p_1m": null,
"p_3m": null,
"p_6m": null,
"p_12m": null,
"p_3y": null,
"p_5y": null,
"p_10y": null,
"p_rel_sp500": null,
"is_article": null,
"is_deleted": "0",
"deleted_time": null,
"description": "All-In-One Guru Screener - GuruFocus.com http://gurufocus.com/screener/",
"detail": [
{
"id": "5057214",
"symbol": "OTCPK:ALRT",
"in_price": "0.05",
"price": "0.04",
"currency": "USD",
"pettm": "0.00",
"ps": "0.00",
"pb": "0.00",
"gain": "0",
"gain_p": "-20%",
"gain_today": "0",
"p_change": "0.00",
"p_pct_change": "-5.67",
"open": "0.05",
"high": "0.05",
"low": "0.04",
"volume": "284119",
"date_add": "11/04/2018",
"cost_per_share": "0.05",
"shares": 0,
"company": "ALR Technologies Inc"
},
{
"id": "5057215",
"symbol": "OTCPK:BIIO",
"in_price": "0.28",
"price": "0.35",
"currency": "USD",
"pettm": "0.00",
"ps": "0.00",
"pb": "0.00",
"gain": "0",
"gain_p": "25%",
"gain_today": "0",
"p_change": "0.00",
"p_pct_change": "0.00",
"open": "0.00",
"high": "0.00",
"low": "0.00",
"volume": "0",
"date_add": "11/04/2018",
"cost_per_share": "0.28",
"shares": 0,
"company": "Bionovate Technologies Corp"
},
...
}}
]
|
| 200 | If Authorization is wrong, will return "Authorization required. Please follow the document." |
Get a list of stocks with fundamental data that has been updated since your customized date within a week.
| Method | URL |
|---|---|
| GET | https://api.gurufocus.com/public/user/{your personal token?}/funda_updated/{time} |
| Example | https://api.gurufocus.com/public/user/{your personal token?}/funda_updated/2019-01-01 |
| Status | Response |
|---|---|
| 200 | Response will be an array containing the list of stocks ticker.
Example:
[
"OTCPK:SGTZY",
"LTS:0RL4",
"FRA:2ZP",
"NAS:ELGX",
"NYSE:LMT",
"AMEX:CVU",
"AMEX:UAVS",
"XTER:WDC",
"NYSE:GIS",
"ASX:CSL",
"LSE:50IT.PFD",
"NAS:PLCE"
]
|
| 200 | If Authorization is wrong, will return "{"error":"You don't have authorization to check this."}" |
The following code using JAVA to output the EPV in Valuation for WMT.
Prerequest Libraries:
org-json-java
Commons
IO
The output JAVA String of EPV:
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/
The C# output of PE Ratio:
The following code using Python 3+ to output the PS Ratio in Valuation Ratio for WMT.
The Python output of PS Ratio:
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.
The following code using PHP to output the Valuation Ratio for WMT.
The output PHP array:
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:
For example, if you want to use GuruFocus API to get valuation ratios in Google Spreadsheet, just try the following function in your spreadsheet
The output will be:
The following code using R to output the EPV in Valuation for WMT.
Prerequest Libraries:
jsonlite
curl
The output object of EPV:
Excel Add-In GURUF
My Portfolios
Create New Portfolio
Portfolio Contest
My Gurus
Personalize
My Gurus
