US Stocks Fundamentals API

2016-08-13

This API provides a convenient and free access to fundamental stock data based on XBRL from SEC.

About this data
API Features

Demo

An API has multiple endpoints for getting companies, indicator data and information about indicators.

Here is an example showing the format of the data when you request one indicator for all companies.

To see the actual CSV file generated by this request, you need to replace "your_access_token" with the access token you will see on your account page after registration.

The list of available options for the indicators endpoint is available below.

https://api.usfundamentals.com/v1/indicators/xbrl?indicators=NetIncomeLoss&token=your_access_token
company_id,indicator_id,2010,2011,2012,2013,2014,2015,2016
1000045,NetIncomeLoss,,,19940946,16703352,16855892,12379000,
1000180,NetIncomeLoss,1300142000,,,,,,
1000228,NetIncomeLoss,,367661000,388076000,431554000,466077000,479058000,
1000229,NetIncomeLoss,,184684000,216071000,242811000,257485000,114847000,
1000230,NetIncomeLoss,,666316,2749317,-42837,684227,-4255665,
~ 9,000 more rows omitted in this example

Getting started with the API

All requests to the API require authentication token, which you can get on your account page.

To get the list of companies, use the companies endpoint.

More information about the indicators and their description is available in the "about the data" section

The list of indicators sorted by the number of available data points is provided in the indicators metadata endpoint.

And the data itself is provided though indicators endpoint.

You can also mirror the whole data archive to your local database or CSV files, following instructions in the indicator updates section. We can also provide you with a custom updater for your database (free for sqlite, mysql, flat files), contact us if interested.

About the data

The data is based on SEC XBRL filings. We do not do any error corrections at the moment. Only data in the standard GAAP namespace is extracted.

We generate the 4th quarter data based on the yearly reports and previous quarterly reports.

To see the description of available metrics, you can download the "2016 US GAAP Taxonomy (Excel Version)" document from fasb.org website.

It contains the definitions of all metrics defined under the GAAP namespace that we extract from XBRL documents. Also contains information about relationships between metrics, that can be used to calculate metric child values. For example getting Revenues from SalesRevenueNet adding other revenue sources.

Using the API

Requests and responses

All requests to the API must include an auth token in the query string. Use HTTPS when making requests.

If an error is encountered while processing request an appropriate HTTP status code is returned with additional details in the response body. Possible errors.

Companies

Request
/v1/companies/xbrl

An endpoint for getting the list of all available companies with their CIKs and names.

ParamValueDescription
companies optional Comma separated list of company CIKs to return, omit to return all companies.
format json or csv Response format
Response

The response contains the following information as JSON object fields or CSV columns.

FieldDescription
company_id Company SEC CIK.
name_latest The name of the company in the latest quarterly or yearly filing.
names_previous Array of previous company names used in previous filings.
CSV format

The columns containing multiple entries, such as names_previous, have the entries separated using non-printable ASCII Unit Separator (\x1f).

We may add additional columns in the future. Please do not rely on column ordering, use the column names to get the right column instead.

Example
https://api.usfundamentals.com/v1/companies/xbrl?companies=320193,1418091&format=json&token=your_access_token

Indicators

Request
/v1/indicators/xbrl

An endpoint for getting indicator data.

Param Value Description
indicators optional Comma separated list of indicator IDs to return. Either indicators or companies must be specified.
companies optional Comma separated list of company CIK's to return. Either indicators or companies must be specified.
periods optional Comma separated list of periods to return. Omit to return all periods.
frequency y (default) or q Return yearly (y) or quarterly (q) indicators.
period_type yq (default) or end_date

If set to "yq" returns periods instead of dates for indicators, for example, years (2016) or quarters (2016Q2).

If set to "end_date" return end dates of indicators.

Response
Column name Description
company_id The CIK of the company.
indicator_id The indicator ID based on XBRL.
period value

If period_type was "yq", returns one column for each unique report period. The period will be returned as the column name (2017 or 2017Q1). The indicator values are returned in columns.

If period_type was "end_date", returns one column for each unique report date. The actual report date is returned as column name.

Indicator values are decimal numbers, with varied number of digits after the decimal point. For example: 173020, 0.431, 0.001. To parse the values 64-bit float is sufficient.

Example

https://api.usfundamentals.com/v1/indicators/xbrl?indicators=Goodwill,NetIncomeLoss&companies=320193,1418091&token=your_access_token
Indicators available for most companies

Indicator metadata

/v1/indicators/xbrl/meta

Use this endpoint to get the list of all possible indicator IDs and to get the number of available data points for each.

Param Value Description
indicators optional Comma separated list of indicator IDs to return.
frequency y (default) or q Return yearly (y) or quarterly (q) indicators.
period_type yq (default) or end_date

When set to "yq"

Returns data for indicators which are mapped to periods

The totals may be lower compared to "end_date", because some reports may map to the same period, in this case one value is ignored.

The year of the period is used for calculating subtotals by year. The year of the period does not always match the year of the report.

When set to "end_date"

Returns data for all reports.

Response
Column name Description
indicator_id The indicator ID based on XBRL.
total Total number of data points for the indicator.
year Subtotals by year.

Example

https://api.usfundamentals.com/v1/indicators/xbrl/meta?indicators=Revenues,NetIncomeLoss&token=your_access_token

Indicator updates

/v1/indicators/xbrl/updates

If you want to have a full copy of the dataset that is kept up-to-date, you can use this endpoint to get updates.

Here are the steps necessary to get all the data and setup updates. You can also check an example implementation in go.

Initial download

Download the list of all companies.

Download all indicators making a separate query for each company. If you want both yearly and quarterly data you would need to make two queries per company. Store this data.

Keep track of the time when you started the initial download. You will use it to get updates.

Updates

You will have to create a program that updates the data and keeps the ID of the last applied update. Here are the steps that the program should make.

Make a call to updates endpoint to get the list of companies and periods that need to be updated.

It should use the update_id_from parameter to get updates that were not yet processed. For the first run only, when this value is not yet known, updated_on_from should be used with the time when you started the initial download.

First update
/v1/indicators/xbrl/updates?updated_on_from={{time_when_initial_download_started}}&frequency=y&period_type=yq&token={{your_token}}
Subsequent updates
/v1/indicators/xbrl/updates?update_id_from={{last_processed_id}}&frequency=y&period_type=yq&token={{your_token}}

If you want both yearly and quarterly data you will have to repeat the process for both. Match the period_type param to one you are using when downloading indicator values.

After getting the list of companies and periods that have been updated, get the actual data.

For each item in this list make a query to the indicators endpoint using the company ID and period from the update list.

/v1/indicators/xbrl?companies={{company_id}}&periods={{period}}&frequency=y&period_type=yq&token={{your_token}}

Update the corresponding record in your database. If the response is empty delete the record if exists. This may happen if the period date was updated.

Update the last_processed_id with the value of update_id field.

Run this script as often as necessary. We update the data two times a day at the moment, but may do it realtime in the future.

Param Value Description
update_id_from string Returns updates starting from (not including) this value. Provide either update_id_from or updated_on_from.
updated_on_from unix timestamp in nanoseconds Returns updates starting from this time. Provide either update_id_from or updated_on_from.
frequency y (default) or q Return updates for yearly (y) or quarterly (q) indicators.
period_type yq (default) or end_date

When "yq" returns updates for indicators which are mapped to quarterly or yearly periods. When "end_date" returns updates for indicators using dates. Set this to match the value you are using when requesting indicators.

Response
Field Description
update_id Use update ID to keep track of updates that were processed.
company_id Company that was updated.
period The period that was updated.

Example

https://api.usfundamentals.com/v1/indicators/xbrl/updates?update_id_from=1469266768f5fa0b82f4bf7da2c91cb3a94f7ca5bd93bc1e&token=your_access_token

API errors

If an error is encountered while processing request, a JSON object describing an error will be returned. See below for the list of possible error types.

HTTP status code Error code Description
403 invalid_auth_token The auth token provided in the URL is not valid, or is missing.
400 invalid_param One or more params provided with the request are not valid.
500 server_error Internal server issue encountered.
Example error response
{"error_code":"invalid_auth_token","error_message":"auth token is missing from the url"}

Download data ZIP

If you prefer to download the archive containing all the data once, instead of using the API, you can download it here:

Download ZIP (100MB)

To get more info about the data in archive.

Preliminary terms of service

XBRL dataset

The XBRL dataset may be used, resold, or re-disseminated by any person who has lawfully obtained such information without restriction.

API for retrieving XBRL dataset

You are free to use the XBRL dataset API for any purpose, even commercially, under the following terms:

The API is operated by Linelane GmbH

Contact us

For any questions or support requests use our email address below.

Email
info |at| usfundamentals.com
Mailing address

The US fundamentals is a product of Linelane GmbH, a small company based in Switzerland.

Linelane GmbH
Kirchplatz 6
8853 Lachen
Switzerland