A standard to retrieve XBRL data

The XBRL API (Application Program Interface) is a set of endpoints developed to help data users access timely, highly granular, structured XBRL data. This standardized API allows developers and data utilities, with limited XBRL knowledge, to learn a single interface to access data from any database that contains XBRL data, including the XBRL US Database of Public Filings, which includes facts, report and taxonomy details and Data Quality Committee (DQC) error messages for all SEC-submitted filings. All of this data can be accessed by using XBRL APIs.

Start using as-filed data


The Google Add-on is the easiest way to get started retrieving data with the XBRL API from the Database of Public Filings. Check the sidebar or Data Community page for free Google Sheet templates. You can also request to be able to create Client ID & secret pairs for Excel or your applications.

Unless otherwise agreed to in writing, any and all use of the XBRL API to authenticate and retrieve data from the XBRL US Database of Public Filings implies user consent and agreement with the XBRL US API Agreement. If you are unable to agree to these terms, do not use the XBRL API.

Data below is a sample preview - login to return details from the latest 10-K XBRL filings (inline or instance) submitted to the SEC, stored in the XBRL US Database of Public Filings and retrieved with the XBRL API.

Report for company (CIK) plus filing detail & select reported facts Accepted (ET)
10-K for Amerityre Corp (0000945828)Fri, 9/14 9:32 AM
Inline document on EDGAR
Generated by iC(tm) - CompSci Interactive Converter - http://www.compsciresources.com
 Cash And Cash Equivalents At Carrying Value as of July 1, 2018
$
213,854
 Retained Earnings Accumulated Deficit as of July 1, 2018
$
-61,438,919
 Cash And Cash Equivalents At Carrying Value as of July 1, 2018
$
213,854
 Liabilities And Stockholders Equity as of July 1, 2018
$
1,787,446
10-K for INTUIT INC (0000896878)Fri, 8/31 5:05 PM
Inline document on EDGAR
XBRL Document Created with Wdesk from Workiva
 Liabilities And Stockholders Equity as of August 1, 2018
$
5,178,000,000
 Cash And Cash Equivalents At Carrying Value as of August 1, 2018
$
1,464,000,000
 Retained Earnings Accumulated Deficit as of August 1, 2018
$
8,101,000,000
 Cash And Cash Equivalents At Carrying Value as of August 1, 2018
$
1,464,000,000

Additional real-time examples of the XBRL API retrieving data show filing results by company and aggregate results of filings scanned with Data Quality Committee Approved Rules.

The API documentation is essential to understanding the framework for the APIs and building complex queries, and also has details for getting connected to a stand alone REST client – use the above to request provisioning for your account, so you can use a client or start integrating the API into software or displaying on web sites or apps like the example above, generated with the code similar to what’s posted below.

Interested in learning more about how to work with the APIs? Get involved in the XBRL Data Community – this knowledge-sharing opportunity includes member-only web meetings plus a dedicated forum to exchange ideas and tips. The Community is designed to help developers, analysts and business intelligence professionals connect and use the XBRL API, Public Filings Database, Google Sheet resources and other tools more effectively.

What is the XBRL US database? This database was created to demonstrate the kind of structured data that is available, and to give startup organizations an opportunity to test out using XBRL-formatted information.

Our database contains nearly 10 years of public company data submitted to the US Securities and Exchange Commission (SEC), including US GAAP data from U.S. issuers, and IFRS data from foreign private issuers (now available since the SEC has approved the IFRS Taxonomy). In the coming months, XBRL US will be adding more public company data from filers in Japan, Denmark, the Netherlands, and other jurisdictions that require XBRL reporting. And over the next year, we will begin collecting data from banks reporting to the FDIC, and mutual funds reporting to the SEC.

Can the XBRL API be used with other databases?

Yes – any database that contains XBRL data can be accessed by using the the XBRL API. The XBRL API is a free open source tool – any data provider can offer their users the XBRL APIs to extract information from their dataset. If you have a commercial database and are interested in learning how you can incorporate the APIs into your offering, review the documentation provided and contact us at info@xbrl.us.

Code sample – XBRL API from PHP to HTML

<?php

// NOTES: Highlighted rows correspond to sample
//        query parameters ( $args ) for the two most recent
//        inline 10-Ks and fact endpoints ( $recent_filings ).
// OAuth logic is omitted from this example. 

// Whitespace/breaks in $concepts variable is for illustrative purposes only.
 
    $limit = 2;
    if (isset($args['limit']) && $args['limit'] !='' ) {
        $limit = $args['limit'];
    }
    $api = new XBRLUSCall ();

    $concepts = '
       CashAndCashEquivalentsAtCarryingValue,
       LiabilitiesAndStockholdersEquity,
       RetainedEarningsAccumulatedDeficit';

    $args = array('fields' => "
     report.accepted-timestamp.sort(DESC),
     concept.local-name.sort(ASC),
     entity.cik,
     fact.value,
     fact.decimals, 
     period.instant,
     report.creation-software,
     report.document-type,
     report.entity-name,
     report.entry-type, 
     report.sec-url,
     report.limit(" . $limit . "),",
           'concept.local-name' => $concepts,
           'fact.has-dimensions' => 'false',
           'period.fiscal-year' => '2019',
           'report.document-type' => '10-K',
           'report.is-most-current' => 'true'
    );

    $recent_filings = $api->call ( 
    '/api/v1/report/fact/search', 'GET', $args );

    $recent_filings = json_decode ( $recent_filings, true );
            $output = "

<!-- return api results as html -->

			<table class=api-sample>
            <thead><tr><th class=api-row-head>
            Report for company (CIK) plus filing detail & select reported facts</th><th class=api-row-head style=text-align:right;>
            Accepted (ET)</th></tr></thead>";

    if (! isset ( $recent_filings ['error'] ) && count ( $recent_filings['data'] ) > 0) {
        $num = 0;
        foreach ( 
        $recent_filings['data'] as $recent_row ) { 
        $date = strtotime($recent_row ['report.accepted-timestamp']);
            $output .= "

<!-- row 1 - document type, entity, cik, date accepted -->

			<tr class=api-background>";
            $output .= "<td class=api-row-1 style='font-weight:600;'>" .
              $recent_row ['report.document-type'] . " for " .
              $recent_row ['report.entity-name'] . " (" .
              $recent_row ['entity.cik'] . ")</td>";
		            $output .= "<td class=api-row-1 nowrap style=text-align:right>" .
              date('D, n/j g:i A', $date) . "</td>";
            $output .= "</tr>

<!-- row 2 - entry (instance or inline), link to EDGAR, report software used -->

			<tr class=api-background>";
			$output .= "<td class=api-row-2 colspan=2><a href=" .
              $recent_row ['report.sec-url'] . " target=blank>" .
              ucfirst ($recent_row ['report.entry-type']) . " document on EDGAR <i class='fa fa-external-link' aria-hidden='true'></i></a><div style='text-align:right;float:right'>" .
              $recent_row ['report.creation-software'] . "</div></td>";
			$output .= "</tr><tr class=api-background><td colspan=2 class=api-row-data><table class=api-row-detail>

<!-- row 3+ - each queried element, instance date, amount-->

			<tr class=api-background>";
        foreach ( 
        $recent_row['fact']['data'] as $fact ) {
        $period = strtotime($fact['period.instant']);
        $element = preg_replace('/(?<!\ )[A-Z]/', ' $0', $fact['concept.local-name']);
        $value = $fact['fact.value'];
        $decimals = abs($fact['fact.decimals']);
        $amount = str_pad($value , $decimals , '0' , STR_PAD_RIGHT);
            $output .= "<tr><td class=api-cell-element><pre>" .
              $element . " as of " .
              date('F j, Y', $period) . "</pre></td><td class=api-cell-element><pre>$</pre></td><td class=api-cell-value><pre style=text-align:right>" . 
              number_format($amount) . "</pre></td></tr>" ; }
            $output .= "</tr></table></td></tr>";
        }
    } else {
        $output .= "<tr><td colspan=2>Youz might need to log in again to refresh your view of the data in this report <em>OR</em> no filings have been submitted matching these query parameters.</td></tr>";
    }
		$output .= "</table>

<!-- end api results as html -->

";";

    return $output;
} ?>

Comment