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.

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.

Data below is a sample preview - login to return details from the latest 10-K inline XBRL filings submitted to the SEC.

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
 Retained Earnings Accumulated Deficit as of July 1, 2018
 Cash And Cash Equivalents At Carrying Value as of July 1, 2018
 Liabilities And Stockholders Equity as of July 1, 2018
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
 Cash And Cash Equivalents At Carrying Value as of August 1, 2018
 Retained Earnings Accumulated Deficit as of August 1, 2018
 Cash And Cash Equivalents At Carrying Value as of August 1, 2018

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.

In addition to corporate datasets, the XBRL US Database also contains details from the US GAAP Financial Reporting Taxonomy such as the metadata associated with individual concepts; and Data Quality Committee (DQC) error messages from historically submitted US GAAP filings. All of this data can be accessed by using XBRL APIs.

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.

How can you start using the XBRL APIs?

The easiest way to get data with the XBRL API is through a Google Sheet and an Add-on in your Google account. Read about how to get started using free resources we’ve posted to use in your Google account.

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 link at right 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.

Code sample – XBRL API from PHP to HTML


// 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 = '

    $args = array('fields' => "
     report.limit(" . $limit . "),",
           'concept.local-name' => $concepts,
           'fact.has-dimensions' => 'false',
           'period.fiscal-year' => '2018',
           'report.document-type' => '10-K',
           'report.entry-type' => 'inline',
           '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>You 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;
} ?>