Exploring the finnhub.io API

The changing face of market data providers

Over the last few years, a number of new market data providers have come online. They tend to have modern websites, broad coverage, and well-documented RESTful APIs. Their services are often priced very competitively – especially for personal use – and usually have generous free tiers.

One such newcomer is finnhub.io . Its offering includes stock, bond, crpto, and FX historical price data and real time trades and quotes. Their fundamental data offering is noticably broad and includes current values and point-in-time snapshots for numerous metrics. There are also some interesting alternative data sets including measures of social media sentiment, insider transactions and insider sentiment, senate lobbying, government spending, and others. In addition, there’s a real-time newsfeed delivered over websockets.

The free tier is quite generous and offers more than enough for doing proof of concept work and testing ideas. While you only get a year’s worth of historical data per API call on the free tier (more if you specify a lower resolution, like monthly), you can make up to 50 calls per minute.

In this post, we’ll explore the finnhub.io free tier via its REST API.

Get started

A nice python library for working with the finnhub.io is available: pip install finnhub-python

To access the API, you’ll need an API key. Get one here.

To get started, import the libraries we need and set up a finnhub.Client with your API key:

OHLCV stock prices

The stock prices endpoint requires a symbol, a resolution (‘D’ for daily data), and a date range consisting of ‘from’ and ‘to’ values as UNIX timestamps.

We’ll get a week’s worth of AAPL data from February 2023.

The data comes down as a dictionary of lists. The docs state that prices are adjusted for splits. Spot checking some data against other sources suggests it’s also adjusted for dividends.

The dictionary keys consist of letters that represent:

• c: close prices
• h: high prices
• l: low prices
• o: open prices
• s: status
• t: timestamps
• v: volume traded

We’ll want to transform that response data into a pandas DataFrame:

Looks good!

Fundamental data

The basic company financials endpoint serves quite a lot of data. The response object is a dictionary of dictionaries that includes current values for various metrics (under the metric outer key) as well as historical point-in-time snapshots (under the series outer key).

Current metrics

Let’s check out how many current metrics we have and display the first ten:

That looks quite comprehensive! For this ticker, we have values for 117 fundamental metrics.

Historical point-in-time snapshots

The historical point-in-time data is under the series outer key. The data is further organised into annual and quarterly metrics, like this:

{
    'annual': {
        'annual_metric1': [
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            ... 
            etc
        ],
        'annual_metric2': [
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            ... 
            etc
        ],
    },
    'quarterly': {
        'quarterly_metric1': [
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            ... 
            etc
        ],
        'quarterly_metric2': [
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            {'period': date_string, 'v': value}, 
            ... 
            etc
        ],
    }
}

Let’s first look at what annual series we get:

Again, pretty comprehensive. Let’s put that data into a dataframe:

Pretty handy… we have 23 years worth of annual company fundamentals.

Let’s do the same thing with the quarterly series. First, what metrics do we get?

Let’s stick this data into a dataframe:

Looks like we have essentially the same data as for the annual series, but at a quarterly resolution. Neat!

Restatements

One thing to be aware of with this sort of data is that sometimes companies will “restate” their reported financials after the initial filing, usually to correct an error.

Using a dataset based on restatements can introduce some bias into an analysis because you’d be using data that you didn’t have available at the time you thought you had it.

To correct for that, you’d need an “as reported” dataset – something that recorded that information available at each point in time, and not corrected retrospectively.

The finnhub.io API docs don’t specify whether the endpoint I used here contains restatements. However, I suspect that it doesn’t because there’s an additional endpoint called “Financials As Reported”, which isn’t available on the free tier.

Alternative data

finnhub.io serves some interesting alternative data:

• Insider sentiment
• Social media sentiment
• Senate lobbying disclosures
• Government spending
• Visa applications submitted by companies
• Many others

Example: insider sentiment

The “Insider Sentiment” endpoint serves the Monthly Share Purchase Ratio (MSPR), which is a measure of whether insider transactions are dominated by buying (a value closer to 100) or selling (a value closer to -100) over the previous month. You can read about the MSPR and how it’s calculated here.

For now, let’s just grab 10 years worth of this data for a single stock and plot it against the stock’s forward returns on the understanding that we don’t have enough data to say anything meaningful (around 120 observations total).

This API can understand human-readable date strings, unlike the prices API.

Notice that we have some missing data – above we don’t have a record for month 5. We’ll need to deal with that later.

I’ll also need to lag the mspr field (the sentiment score) to align it with the date on which it would have been actionable. We’ll do this once we have some price data.

Next we’ll grab some monthly price data and munge it for our needs:

You can see that our data isn’t going to overlap neatly. There are some months in our sentiment dataframe that are missing from our prices dataframe and vice versa.

I’ll merge the two dataframes using an outer join – this will preserve all of our data and insert NaN into any record that’s missing.

From there, I can lag the sentiment score appropriately. Only then can I remove records that contain NaN (doing so prior would misalign some of our data).

Now we can calculate close-to-close monthly returns and lag the sentiment score:

An easy way to look for a relationship between this sentiment metric and next month’s returns is to just scatter plot them:

Unfortunately, we don’t see much of any kind of relationship.

The sentiment metric does jump around quite a bit – let’s see if smoothing it with a 3-month moving average reveals anything interesting:

The relationship is still super noisy. If anything, it’s a little opposite to what we’d expect, especially at the extreme values of our smoothed metric.

Maybe the SEC is succeeding in stamping out insider trading.

The reality is that insiders buy and sell for all sorts of reasons, many of which have nothing to do with their views on the stock itself.

As I mentioned, there aren’t a whole lot of data points here – perhaps this would be interesting to revisit using a broader universe of stocks.

Conclusion

finnhub.io is a modern market data service with a well-documented REST API, open source client libraries, broad coverage, interesting data sets, and a generous free tier.

What’s your preferred source of market data and why? Let me know in the comments!