Python wrapper for xbrl.us API
Project description
About
The XBRL US Python Wrapper is a powerful tool for interacting with the XBRL US API, providing seamless integration of XBRL data into Python applications. This wrapper simplifies the process of retrieving and analyzing financial data in XBRL format, enabling users to access a wide range of financial information for companies registered with the U.S. Securities and Exchange Commission (SEC).
It’s important to note that while the XBRL US Python Wrapper is free and distributed under the permissive MIT license, the usage of the underlying XBRL US API is subject to the policies and terms defined by XBRL US. These policies govern the access, usage, and restrictions imposed on the API data and services. Users of the XBRL US Python Wrapper should review and comply with the XBRL US policies to ensure appropriate usage of the API and adherence to any applicable licensing terms.
Tutorial ✏️📖📚
This tutorial will guide you through using the XBRL-US Python library to interact with the XBRL API. The XBRL-US library provides a convenient way to query and retrieve financial data from the XBRL API using Python.
1. Prerequisites
Before you begin, ensure you have the following:
Python installed on your system. The XBRL-US library supports Python 3.8 and above.
XBRL-US API credentials. You can obtain your credentials by registering for a free XBRL-US account at https://xbrl.us/home/use/xbrl-api/.
XBRL-US OAuth2 Access. You can obtain your client ID and client secret by registering for a filling the request form at https://xbrl.us/home/use/xbrl-api/access-token/.
You can install this package using pip:
pip install xbrl-us
If you are using Jupyter Notebook, you can install the package using the following command:
!pip install xbrl-us
Documentation
For detailed information about the XBRL-US Python library, you can refer to the documentation at https://python-xbrl-us.readthedocs.io/en/latest/.
Official Documentation
For more information about the XBRL API and its endpoints, refer to the original API documentation at https://xbrlus.github.io/xbrl-api.
2. Choose Your Preferred Approach
There are two distinct ways to use the XBRL-US Python package:
Code-Based Approach: Import the XBRL-US Python package directly into your Python environment for in-depth, custom analysis (see Code-Based Approach)
Browser Interface: For a no-code experience, navigate to the Browser Interface. This interface allows for easy exploration and analysis of XBRL data directly in your web browser.
2.1. Code-Based Approach
Import the XBRL Library
To start using the XBRL-US library, you need to import it into your Python script:
from xbrl_us import XBRL
Create an Instance of XBRL Class
Next, you need to create an instance of the XBRL class, providing your authentication credentials (client ID, client secret, username, and password) as parameters:
xbrl = XBRL(
client_id='Your client id',
client_secret='Your client secret',
username='Your username',
password='Your password'
)
Make sure to replace Your client id, Your client secret, Your username, and Your password with your actual credentials.
Query the XBRL API
The XBRL-US library provides a query method to search for data from the XBRL API. You can specify various parameters and fields to filter and retrieve the desired data.
Here’s an example of using the query method to search for specific financial facts:
response = xbrl.query(
method='fact search',
parameters={
"concept.local-name": [
'OperatingIncomeLoss',
'GrossProfit',
'OperatingExpenses',
'OtherOperatingIncomeExpenseNet'
],
"period.fiscal-year": [2009, 2010],
"report.sic-code": range(2800, 2899)
},
fields=[
'report.accession',
'period.fiscal-year',
'period.end',
'period.fiscal-period',
'fact.ultimus',
'unit',
'concept.local-name',
'fact.value',
'fact.id',
'entity.id',
'entity.cik',
'entity.name',
'report.sic-code',
],
limit=100,
as_dataframe=True
)
In this example, we are searching for facts related to specific concepts, fiscal years, and SIC codes. We are also specifying the fields we want to retrieve in the response. The limit parameter restricts the number of facts returned to 100, and as_dataframe=True ensures the response is returned as a Pandas DataFrame.
Alternatively, you can use the Parameters and Fields classes provided by the library to make the query more readable, less prone to errors, and easier to maintain:
from xbrl_us.utils import Parameters, Fields
response = xbrl.query(
method='fact search',
parameters=Parameters(
concept_local_name=[
'OperatingIncomeLoss',
'GrossProfit',
'OperatingExpenses',
'OtherOperatingIncomeExpenseNet'
],
period_fiscal_year=[2009, 2010],
report_sic_code=range(2800, 2899)
),
fields=[
Fields.REPORT_ACCESSION,
Fields.PERIOD_FISCAL_YEAR,
Fields.PERIOD_END,
Fields.PERIOD_FISCAL_PERIOD,
Fields.FACT_ULTIMUS,
Fields.UNIT,
Fields.CONCEPT_LOCAL_NAME,
Fields.FACT_VALUE,
Fields.FACT_ID,
Fields.ENTITY_ID,
Fields.ENTITY_CIK,
Fields.ENTITY_NAME,
Fields.REPORT_SIC_CODE,
],
limit=100,
as_dataframe=True
)
This alternative approach also allows you to take advantage of the autocomplete feature of your IDE to easily find the parameters and fields.
Perform Additional Queries
You can use the same query method to call other API endpoints by changing the method parameter and providing the relevant parameters and fields.
Here’s an example of using the query method to search for a specific fact by its ID:
response = xbrl.query(
method='fact id',
parameters={'fact.id': 123},
fields=[
'report.accession',
'period.fiscal-year',
'period.end',
'period.fiscal-period',
'fact.ultimus',
'unit',
'concept.local-name',
'fact.value',
'fact.id',
'entity.id',
'entity.cik',
'entity.name',
'report.sic-code',
],
as_dataframe=False
)
Congratulations! You have learned how to use the XBRL-US Python library to interact with the XBRL API. In this example you will receive the data in json format as the as_dataframe parameter is set to False.
2.2 Browser Interface 🖥️
This feature is designed to make our package even more user-friendly, allowing users to interact and work with XBRL data directly through a graphical interface, in addition to the existing code-based methods.
The browser interface streamlines data visualization, simplifies navigation, and enhances user interactions. With this intuitive, user-friendly interface, you can easily explore, interpret, and analyze XBRL data in real-time, right from your web browser.
Key Features:
Create Real-time queries right in your browser
Intuitive navigation and search features
Filtering and sorting options
Seamless integration with the existing XBRL-US Python API
Getting started is as simple as ever. Update your XBRL-US Python package to the latest version and launch the new Browser Interface from the package menu.
Getting Started with the Browser Interface
Getting started is as simple as ever. First, ensure you have the latest version of xbrl-us installed by running the following code:
pip install xbrl-us --upgrade
or if you are on a Jupyter Notebook:
!pip install xbrl-us --upgrade
Next, launch the new Browser Interface from the package menu:
python -m xbrl_us
or if you are on a Jupyter Notebook:
!python -m xbrl_us
That is it! You should now see the new Browser Interface open in your default web browser.
Happy data exploring!
Development
To run all the tests run:
tox
Note, to combine the coverage data from all the tox environments run:
Windows |
|
---|---|
Other |
|
Changelog
0.0.40 (2023-08-03)
Improved Browser Interface
improved error handling for requests
Bug fixes
0.0.32 (2023-07-17)
Improved Browser Interface
Added unique keyword to query method
Bug fixes
0.0.31 (2023-07-14)
fixed dependency issues
Bug fixes
0.0.3 (2023-07-14)
Backward compatibility with Python 3.8 and 3.9
Bug fixes
0.0.2 (2023-07-12)
Bug fixes
Enhanced error handling
Improved methods attributes
Added the ability to print the query string
Implemented a feature to handle queries with large limits
NEW: Introduced a web interface for the API, making it even easier to use
0.0.1 (2023-07-09)
First release on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.