2016-08-13
This API provides a convenient and free access to fundamental stock data based on XBRL from SEC.
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
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.
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.
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.
/v1/companies/xbrl
An endpoint for getting the list of all available companies with their CIKs and names.
| Param | Value | Description |
|---|---|---|
| companies | optional | Comma separated list of company CIKs to return, omit to return all companies. |
| format | json or csv | Response format |
The response contains the following information as JSON object fields or CSV columns.
| Field | Description |
|---|---|
| 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. |
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.
https://api.usfundamentals.com/v1/companies/xbrl?companies=320193,1418091&format=json&token=your_access_token
/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. |
| 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
/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. |
| 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
/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.
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.
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.
/v1/indicators/xbrl/updates?updated_on_from={{time_when_initial_download_started}}&frequency=y&period_type=yq&token={{your_token}}
/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. |
| 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
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. |
{"error_code":"invalid_auth_token","error_message":"auth token is missing from the url"}
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.
The XBRL dataset may be used, resold, or re-disseminated by any person who has lawfully obtained such information without restriction.
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
For any questions or support requests use our email address below.
The US fundamentals is a product of Linelane GmbH, a small company based in Switzerland.
Linelane GmbH