XBRL US API - Python example

Based on a notebook created by Ties de Kok, this sample Python code queries the XBRL US API (https://xbrl.us/home/use/xbrl-api/)

Enter your XBRL API credentials

Run the cell below, then type your XBRL US Web account email, account password, Client ID, and secret as noted, pressing the Enter key on the keyboard after each entry.

In [1]:
print('XBRL US Web account email:')
import os, re, sys, json
import requests
import pandas as pd
import numpy as np
import getpass
email = input()
print('Account password')
password = getpass.getpass()
print('Client ID:')
clientid = getpass.getpass()
print('Client secret:')
secret = getpass.getpass()
········

Once you've entered your credentials above, Run the cell below to generate an access token.

Request credentials at https://xbrl.us/home/use/xbrl-api-community/#provisioning

In [2]:
body_auth = {'username' : ''.join(email), 
            'client_id': ''.join(clientid), 
            'client_secret' : ''.join(secret), 
            'password' : ''.join(password), 
            'grant_type' : 'password', 
            'platform' : 'ipynb' }
endpoint = 'https://api.xbrl.us'
endpoint_auth = endpoint + '/oauth2/token'
res = requests.post(endpoint_auth, data=body_auth)
auth_json = res.json()
access_token = auth_json['access_token']
print('Your access token is: ' + access_token)
print('This access token expires after 60 minutes. Re-run this cell to generate a new token.')

Make a query

After the access token appears above, you can modify the query below, then use the Cell >> Run All Below menu option from the cell immediately below this text to run the entire query for results.

Once the initial data query is executed, use Run All Below menu option at the highest point on this page where you modified the data query to get updated results.

Refer to XBRL API documentation at https://xbrlus.github.io/xbrl-api/#/Facts/getFactDetails for other endpoints and parameters to filter and return.

Define the fields to be returned

In [4]:
fields = ['period.fiscal-year.sort(DESC)',
         'entity.name.sort(ASC)',
         'concept.local-name.sort(ASC)',
         'fact.value',
         'unit',
         'fact.decimals',
         'report.filing-date'
         ]

Filter the query for specific XBRL elements (tags) to research

In [5]:
XBRL_Elements = ['Assets',
                 'Liabilities',
                 'LiabilitiesAndStockholdersEquity'
                ]

Filter companies for the query

In [6]:
companies_cik = ['0000789019', ## Microsoft (MSFT)
                 '0001018724', ## Amazon (AMZN)
                 '0000320193', ## Apple (AAPL)
                 '0000051143', ## IBM (IBM)
                ]

Filter data by years to return

In [7]:
years = ['2019,2018']

Automatic: assemble API parameters

In [8]:
params = {'fields': ','.join(fields),
         'concept.local-name': ','.join(XBRL_Elements),
         'entity.cik': ','.join(companies_cik),
         'period.fiscal-year': ','.join(years),
         'period.fiscal-period': 'Y',
         'fact.has-dimensions': 'FALSE',
         'fact.ultimus': 'TRUE'
         }
In [9]:
search_endpoint = 'https://api.xbrl.us/api/v1/fact/search'
res = requests.get(search_endpoint, params=params, headers={'Authorization' : 'Bearer {}'.format(access_token)})
res_json = res.json()
res_df = pd.DataFrame(res_json['data'])
In [10]:
res_df
Out[10]:
period.fiscal-year entity.name concept.local-name fact.value unit fact.decimals report.filing-date
0 2019 AMAZON.COM, INC. Assets 225248000000 USD -6 2020-05-01
1 2019 AMAZON.COM, INC. LiabilitiesAndStockholdersEquity 225248000000 USD -6 2020-05-01
2 2019 Apple Inc. Assets 338516000000 USD -6 2020-05-01
3 2019 Apple Inc. Liabilities 248028000000 USD -6 2020-05-01
4 2019 Apple Inc. LiabilitiesAndStockholdersEquity 338516000000 USD -6 2020-05-01
5 2019 INTERNATIONAL BUSINESS MACHINES CORPORATION Assets 152186000000 USD -6 2020-04-28
6 2019 INTERNATIONAL BUSINESS MACHINES CORPORATION Liabilities 131202000000 USD -6 2020-04-28
7 2019 INTERNATIONAL BUSINESS MACHINES CORPORATION LiabilitiesAndStockholdersEquity 152186000000 USD -6 2020-04-28
8 2019 MICROSOFT CORPORATION Assets 286556000000 USD -6 2020-04-29
9 2019 MICROSOFT CORPORATION Liabilities 184226000000 USD -6 2020-04-29
10 2019 MICROSOFT CORPORATION LiabilitiesAndStockholdersEquity 286556000000 USD -6 2020-04-29
11 2018 AMAZON.COM, INC. Assets 162648000000 USD -6 2020-01-31
12 2018 AMAZON.COM, INC. LiabilitiesAndStockholdersEquity 162648000000 USD -6 2020-01-31
13 2018 Apple Inc. Assets 365725000000 USD -6 2019-10-31
14 2018 Apple Inc. Liabilities 258578000000 USD -6 2019-10-31
15 2018 Apple Inc. LiabilitiesAndStockholdersEquity 365725000000 USD -6 2019-10-31
16 2018 INTERNATIONAL BUSINESS MACHINES CORPORATION Assets 123382000000 USD -6 2020-02-25
17 2018 INTERNATIONAL BUSINESS MACHINES CORPORATION Liabilities 106452000000 USD -6 2020-02-25
18 2018 INTERNATIONAL BUSINESS MACHINES CORPORATION LiabilitiesAndStockholdersEquity 123382000000 USD -6 2020-02-25
19 2018 MICROSOFT CORPORATION Assets 258848000000 USD -6 2019-08-01
20 2018 MICROSOFT CORPORATION Liabilities 176130000000 USD -6 2019-08-01
21 2018 MICROSOFT CORPORATION LiabilitiesAndStockholdersEquity 258848000000 USD -6 2019-08-01