SimFin API Tutorial

Update: This tutorial is for our low-level web-API. For our new Python API, click here.

There were a few requests from SimFin users to provide a more detailed introduction on how to use the API, so this tutorial will hopefully make things more clear for people that don’t have extensive API experience yet.

We’ll take Python to exemplify the process, all the code along with one example for R can be found on Github: https://github.com/SimFin/api-tutorial

Get a SimFin API key

Register on SimFin and head to the API page to get your API key: https://simfin.com/data/access/api

You will need this key later in order to make API calls.

Setting up Python

The first thing when working with Python is to install a package manager, we recommend using Conda.

We won’t cover how to install Conda here, it should be fairly easy though if you follow the steps here: https://docs.anaconda.com/anaconda/install/

You can install Conda or Miniconda (much smaller), both will work fine for this.

Once you installed conda, open a command line window and type “conda” to see if everything worked. If you are not getting an error you are ready to proceed.

First, we are now going to create an environment for this python Project. Python is probably running on your operating system anyway already, but maybe it’s an older version and you can’t just upgrade it manually, since some things might just stop working. So it’s always best to just create a new and fresh Python environment in order to not interfere with existing Python installs.

We are now going to create a new Conda environment called “simfin” with Python 3.6, so type in your command line:

conda create -n simfin python=3.6

Press “y” if you need to confirm. After the installation is finished, we just have to activate the environment in order to be able to use it:

Linux/Mac:

source activate simfin

Windows:

activate simfin

Now, create a new python file and call it “example.py” (or something else if you like, just replace “example.py” in the following with your file name then).

Change the directory in your command line to be the same as the file you just created (you can do that by writing “cd PATH” in the command line, where PATH is the path to the directory where your file is located).

Edit example.py (using a program such as Notepad or any other editor) and write

print("hello")

Save the file. Check again that your environment is up- and running (if you closed the command line window you will have to activate the environment again) and type

python example.py

If the output is “hello” everything is working fine and you are ready to proceed.

Making API calls

Getting SimFin IDs

Now we are ready to make our first API calls. The aim of this tutorial will be to provide a list of tickers and to download all the financial statements for these tickers in the standardised data format.

First, let’s create a variable that will save our API Key, so we don’t have to copy paste it for every API call.

Write in your Python file (replace YOUR_API_KEY with the actual key from the SimFin website):

api_key = "YOUR_API_KEY"

Now, let’s define the tickers for which we would like to retrive the information. Let’s pick Apple (AAPL), Nvidia (NVDA) and Wal Mart (WMT).

Write in your Python file:

tickers = ["AAPL","NVDA","WMT"]

The first step is to get the SimFin IDs for these tickers. SimFin IDs are integers that uniquely define a company on SimFin and are needed as parameter for most API calls.

We are going to use a library called “requests” to make the calls, so you will probably have to install it with Conda, so type in the command line (not the Python file):

pip install requests

Now write at the very top of your Python file:

import requests

The endpoint to get SimFin ids is described in detail in the SimFin API documentation: https://simfin.com/api/v1/documentation/#operation/getIdByTicker

As you can see from the documentation, the only parameter needed to get the SimFin ids is the ticker, so we have all the information we need to make this API call.

Write in your Python file:

sim_ids = []
for ticker in tickers:

    request_url = f'https://simfin.com/api/v1/info/find-id/ticker/{ticker}?api-key={api_key}'
    content = requests.get(request_url)
    data = content.json()
    print(data)

The expected output should be:

[{‘simId’: 111052, ‘ticker’: ‘AAPL’, ‘name’: ‘APPLE INC’}]
[{‘simId’: 172199, ‘ticker’: ‘NVDA’, ‘name’: ‘NVIDIA CORP’}]
[{‘simId’: 239962, ‘ticker’: ‘WMT’, ‘name’: ‘WAL MART STORES INC’}]

Each result of the API call is an array of JSON objects, containing each the SimFin id (‘simId’), the ticker and the company name.

Let’s collect the SimFin IDs in the variable “sim_ids” that we created already, change your code like this:

sim_ids = []
for ticker in tickers:

    request_url = f'https://simfin.com/api/v1/info/find-id/ticker/{ticker}?api-key={api_key}'
    content = requests.get(request_url)
    data = content.json()

    if "error" in data or len(data) < 1:
        sim_ids.append(None)
    else:
        sim_ids.append(data[0]['simId'])

print(sim_ids)

We are basically checking if some valid data is returned and if not we are using “None” as SimFin ID, to indicate that the ticker wasn’t found in the database.

Getting financial statements

Now we have all the information needed to retrieve the financial statements. For the sake of simplicity, let’s only retrive the profit & loss statements (it should be easy to extend the code to get balance sheet and cash flow data too).

Let’s also define the time period we want to retrieve data for. Say we want to look at the quarterly data for the past 5 years. Add below “print(sim_ids)”:

print(sim_ids)

# define time periods for financial statement data
statement_type = "pl"
time_periods = ["Q1","Q2","Q3","Q4"]
year_start = 2013
year_end = 2018

Now it’s getting a bit more complicated, you have to be a bit familiar with Python to fully understand the code but what we are doing is basically: create a data dictionary for each ticker to store our information, loop through years and time periods to create a time period identifier and make the API call for each period/year combination and store that information in the dictionary we created for the company.

The API documentation for the standardised financial statements can be found here: https://simfin.com/api/v1/documentation/#operation/getCompStatementStandardised

The code is as follows:

data = {}
for idx, sim_id in enumerate(sim_ids):
    d = data[tickers[idx]] = {"Line Item": []}
    if sim_id is not None:
        for year in range(year_start, year_end + 1):
            for time_period in time_periods:

                period_identifier = time_period + "-" + str(year)

                if period_identifier not in d:
                    d[period_identifier] = []

                request_url = f'https://simfin.com/api/v1/companies/id/{sim_id}/statements/standardised?stype={statement_type}&fyear={year}&ptype={time_period}&api-key={api_key}'

                content = requests.get(request_url)
                statement_data = content.json()

                # collect line item names once, they are the same for all companies with the standardised data
                if len(d['Line Item']) == 0:
                    d['Line Item'] = [x['standardisedName'] for x in statement_data['values']]

                if 'values' in statement_data:
                    for item in statement_data['values']:
                        d[period_identifier].append(item['valueChosen'])
                else:
                    # no data found for time period
                    d[period_identifier] = [None for _ in d['Line Item']]

Saving to XLSX

Now that we have the data saved in memory, let’s also save it as XLSX to facilitate further work with it:

For this we are going to convert our data to a pandas dataframe. Install pandas in the command line using:

pip install pandas

And add the dependency at the very top of our Python file:

import pandas as pd

You might receive an error when running the code for the XLSX conversion, so if you receive an error like “ModuleNotFoundError: No module named ‘xlsxwriter’”, you will have to install that also:

pip install xlsxwriter

Above the “data = {}” from the code block we inserted in the previous step, insert the following line:

writer = pd.ExcelWriter("simfin_data.xlsx", engine='xlsxwriter')

data = {}

and add below the code block:

    # convert to pandas dataframe
    df = pd.DataFrame(data=d)
    # save in the XLSX file configured earlier
    df.to_excel(writer, sheet_name=tickers[idx])

writer.save()
writer.close()

That’s it, the output is an Excel file with all the P&L data for the specified time periods with each ticker having the data on a separate Excel sheet.

You can find all the code here:

https://github.com/SimFin/api-tutorial/blob/master/python-examples/example1.py