Unfortunately I don't have an answer... but I was just struggling with a similar problem. I was looking at dividend_yield and forward_dividend_yield, sorted by dividend_yield descending where dividend_yield > 0, and came up with a list that kind of made sense, but I don't know where the values are coming from. For 1/28, the following values came up:
COWN, Cowen Group, 3.1391
2016-01-28INFO CBIO, Catalyst Biosciences, 1.7323
2016-01-28INFO NATDF, North Atlantic Drilling, 0.2667
2016-01-28INFO LGCY, Legacy Reserves, 1.2696

These don't seem to match up with any data I can see on morningstar (as I understand it, the source of the data). Not sure what to make of this.

Hey Kevin, how did you print out the data? I'm still trying to figure this out. I thought the API just gives you a list of stocks fitting the filters, but without actual access to the data.

def before_trading_start(context, data):  
    log.info("Test-before_trading_start")  
    dividendList = get_fundamentals(  
         query(  
             fundamentals.company_reference.short_name,  
             fundamentals.company_reference.primary_symbol,  
             fundamentals.valuation_ratios.payout_ratio,  
             fundamentals.valuation_ratios.dividend_yield  
        )  
         .filter(  
             fundamentals.valuation_ratios.dividend_yield > 0  
         )  
         .order_by(  
             fundamentals.valuation_ratios.forward_dividend_yield.desc()  
         )  
         .limit(100)  
    )  
    for stock in dividendList:  
        log.info(str(dividendList[stock]['primary_symbol'] )+ ", " + dividendList[stock]['short_name'] + ", " + str(dividendList[stock]['dividend_yield']) );  

Which then results in the following output:

2016-01-28before_trading_start:8INFOTest-before_trading_start  
2016-01-28before_trading_start:27INFOCOWN, Cowen Group, 3.1391  
2016-01-28before_trading_start:27INFOCBIO, Catalyst Biosciences, 1.7323  
2016-01-28before_trading_start:27INFONATDF, North Atlantic Drilling, 0.2667  
2016-01-28before_trading_start:27INFOLGCY, Legacy Reserves, 1.2696  
2016-01-28before_trading_start:27INFOSXE, Southcross Energy, 2.5806  
2016-01-28before_trading_start:27INFOENRJ, Enerjex Resources, 2.1701  
2016-01-28before_trading_start:27INFOEVEP, EV Energy Partners, 0.8621  
2016-01-28before_trading_start:27INFOPER, SandRidge Permian, 0.7813  
2016-01-28before_trading_start:27INFOCLF, Cliffs Natural Resources, 1.306  
2016-01-28before_trading_start:27INFOFELP, Foresight Energy, 0.7273  
2016-01-28before_trading_start:27INFOTOO, Teekay Offshore Partners, 0.5229  
2016-01-28before_trading_start:27INFOEMES, Emerge Energy Services, 1.0769  
2016-01-28before_trading_start:27INFOMVO, MV Oil, 0.1739  
2016-01-28before_trading_start:27INFOGRH, GreenHunter Resources, 0.431  
2016-01-28before_trading_start:27INFOLGCY, Legacy Reserves, 0.7547  
2016-01-28before_trading_start:27INFOLGCY, Legacy Reserves, 0.7067  
2016-01-28before_trading_start:27INFOSDLP, Seadrill Partners, 0.8021  
2016-01-28before_trading_start:27INFOVOC, VOC Energy, 0.1822  
2016-01-28before_trading_start:27INFOABG, Abengoa, 0.6465  
2016-01-28before_trading_start:27INFOAZUR, Azure Midstream Partners, 0.6385  
2016-01-28before_trading_start:27INFONone, Royce Micro-Cap Trust, 0.1978  

You need to see the data to some extent, unless they are very specific about the actual format they are using. I wanted to print it out to see if yield was going to be expressed as a plain number or as a percentage value (IE if an 8.1% yield was going to be represented by the number 8.1 or .081). You always need some manual verification of the data, otherwise you will be flying blind!

Currently, most data points are for the most recently reported quarter. Other metrics are reported more frequently (monthly or daily). But none of the metrics are TTM or twelve months (we don't yet surface that data).

For all metrics, there's an accompany field -- the "as of" date field. You can append _as_of to any column name and you'll get the as of date. The as of date is the date to which the data applies. So an as of date of 3/31 will be a Q1 metric. 6/30 will be a Q2 metric and so forth.

Thanks Josh. That field helped explain a bit. Digging further, it looks like old data is being returned for dividends and that helps explain why the numbers are off from what I expect:

def before_trading_start(context, data):  
    log.info("Test-before_trading_start")  
    dividendList = get_fundamentals(  
         query(  
             fundamentals.company_reference.short_name,  
             fundamentals.company_reference.primary_symbol,  
             fundamentals.valuation_ratios.payout_ratio,  
             fundamentals.earnings_report.dividend_per_share,  
             fundamentals.valuation_ratios.dividend_yield,  
             fundamentals.valuation_ratios.dividend_yield_as_of,  
             fundamentals.valuation_ratios.forward_dividend_yield  
        )  
         .filter(  
             fundamentals.earnings_report.dividend_per_share > 0  
         )  
         .order_by(  
             fundamentals.valuation_ratios.forward_dividend_yield.desc()  
         )  
         .limit(100)  
    )  
    for stock in dividendList:  
        log.info(str(dividendList[stock]['primary_symbol'] ) + ", "  
                 + dividendList[stock]['short_name'] + ", "  
                 + str(dividendList[stock]['dividend_per_share']) + ", "  
                 + str(dividendList[stock]['dividend_yield'] * 100) + ", "  
                 + str(dividendList[stock]['forward_dividend_yield'] * 100) + ", "  
                 + str(dividendList[stock]['dividend_yield_as_of'])  
)

For example produces some output like this:

2016-01-28before_trading_start:35INFO PER, SandRidge Permian, 0.423, 78.13, 153.37, 2016-01-26  
2016-01-28before_trading_start:35INFO CLF, Cliffs Natural Resources, 0.4375, 130.6, 130.6, 2016-01-26  
2016-01-28before_trading_start:35INFO FELP, Foresight Energy, 0.38, 72.73, 94.32, 2016-01-26  

I normalized the yields to be percentages, just to make comparisons easier, and then printed the actual dividend_per_share being used. It seems to be consistently behind by a quarter. FELP for example, last had a 38 cent dividend in August, their last quarterly distribution was in November for 17 cents. If you assume its using that 38 cent figure... the forward yield will then be $1.52, and this stock is now at $1.80, but was recently trading between $1.60-$1.80... I am not sure what price is being used, but now at least the 94% yield has some connection to reality, even if it is wrong. Now I just need to figure out why the dividend data seems so out of sync :).

Gary, looking again at your question, a little less bleary eyed than last night, I would guess that those numbers are quarterly, since cash flow and income statements are only released quarterly. By printing the values as I showed, you should be able to confirm that. Let me know what you find!

Thanks for the responses and the sample code. This API is very exciting and I have a lot of ideas that I want to try out.

Given the cyclical nature of quarterly numbers, I'm trying to figure out how to create TTM values. I thought of storing old values, but the get_fundamentals function can give a different set of stocks each time. What would be a good way to approach this?

Within an algorithm for backtesting, the best way to access a time series of these values is through the pipeline API which also provides access to this data. Check out the help documents for some examples.

Hello Josh and all here,

I need your help please as I need to access fundamental data on a given date from 5 years back. So, if I run a backtest on day d, I need to know what was the value for a fundamental 5x252 days ago.

I have attempted doing the above using custom factors, but as I needed to specify a window_length of 5x252, I got a memory error and backtest stopped. So, i am looking for a more optimal way for directly accessing the required value on a given date in the past.

I was thinking about the _as_of feature, but as I can see above, it is not the right solution.

Thank you for your help,

Tsiresi