API Documentation

Integrate Calcbench Data with your system

Access Calcbench data programitically via our JSON API.

Accessing Calcbench data programatically is not included in the standard Calcbench subscription. Talk to us before you start programming.

Adding Calcbench data to your website
Python client for the API @ https://github.com/calcbench/python_api_client.
Demos of the API with Python @ https://github.com/calcbench/notebooks.

Authentication

Calcbench uses token based authentication. Clients need to submit the authentication token with each request. To get the authentication cookie POST to https://www.calcbench.com/account/LogOnAjax with form-data:

email: The email address you use to log in on Calcbench
password: Your Calcbench password.

Standardized Data

Standardized metrics for comparisons between companies, the data behind the benchmarking page. To get normalized data POST to https://www.calcbench.com/api/mappedData with form-data:

companiesParameters

JSON object that specifies the companies to include,

companyIdentifiers: A array of tickers of tickers or CIKs (Central Index Key), for example ['msft', 'goog', 'appl']
entireUniverse: Search for all companies, either true or false

periodParameters

JSON object that specifies the periods to include

year: First year of data to get
period: First period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
endYear: Last year of data to get
endPeriod: last period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
allHistory: true or false, get all history
updateDate: Get data that Calcbench recieved on date, YYYY-mm-dd

pageParameters

JSON object that specifies the metrics to search for

metrics: Array of metrics to get. Available Metrics

Returns: An array of objects. One object for each data point. Each object has the properties ticker, calendar_year, calendar_period, metric, and value. For example:


                            [{
                        "ticker": "MSFT",
                        "calendar_year": 2010,
                        "calendar_period": 1,
                        "metric": "revenue",
                        "value": 14503000000
                    },
                    {
                        "ticker": "MSFT",
                        "calendar_year": 2010,
                        "calendar_period": 2,
                        "metric": "revenue",
                        "value": 16039000000
                    }]

Point-In-Time Data

Calcbench's standardized data associated with date on which the data was published. Useful for backtesting algorithms.

Getting Point-in-time data in bulk will take a long time. Talk to us before you start downloading PIT data.

companiesParameters

JSON object that specifies the companies to include,

companyIdentifiers: A array of tickers of tickers or CIKs (Central Index Key), for example ['msft', 'goog', 'appl']
entireUniverse: Search for all companies, either true or false

periodParameters

JSON object that specifies the periods to include

year: First year of data to get
period: First period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
endYear: Last year of data to get
endPeriod: last period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
allHistory: true or false, get all history
updateDate: Get data that Calcbench recieved on date, YYYY-mm-dd

pageParameters

JSON object that specifies the metrics to search for

metrics: Array of metrics to get. Available Metrics
pointInTime: true

Example form-data:


                {
                    "pageParameters":{"metrics" : ["earningsbeforetaxes"], "pointInTime" : true},
                    "companiesParameters":{"companyIdentifiers":["F"]},
                    "periodParameters":{"year" : 2013, "period" : 0, "endYear" : 2014, "endPeriod" : 0}
                }

Returns: An arrary of objects. One object for each "revision". If a value was revised by the filer after it was first reported there will multiple objects for the data point. Revisions have a revision_number greater than 0.


                [
                {
                "metric": "EarningsBeforeTaxes",
                "ticker": "F",
                "CIK": "0000037996",
                "value": 4342000000,
                "calendar_year": 2014,
                "calendar_period": 0,
                "fiscal_year": 2014,
                "fiscal_period": 0,
                "revision_number": 0,
                "date_reported": "2015-02-13T00:00:00"
                },
                {
                "metric": "EarningsBeforeTaxes",
                "ticker": "F",
                "CIK": "0000037996",
                "value": 1234000000,
                "calendar_year": 2014,
                "calendar_period": 0,
                "fiscal_year": 2014,
                "fiscal_period": 0,
                "revision_number": 1,
                "date_reported": "2016-02-11T00:00:00"
                }
                ]

As-Reported Data

Download statements as they are reported by companies in their filings. Calcbench "folds" the statements so you can get all reported history with one function call. This is the data behind the Company in Detail page. To get statements submit a GET requests to https://www.calcbench.com/api/asReported with the following URL parameters:

companyIdentifier: a ticker or a CIK code, eg "msft"
statementType: The statement type, one of income, balance, cash, change-in-equity, comprehensive-income
periodType: Period type, either annual or quarterly
allPeriods: Get all history or only the last four, true or false
descendingDates: return columns in oldest -> newest order, true or false

Breakout Data

Get breakouts/segments, this is the data behind the breakout page. To get breakouts POST to https://www.calcbench.com/api/breakouts with form-data:

companiesParameters

JSON object that specifies the companies to include,

entireUniverse: Search for all companies, either true or false
companyIdentifiers: A array of tickers of tickers or CIKs (Central Index Key), for example ['msft', 'goog', 'appl']

periodParameters

JSON object that specifies the periods to include

year: First year of data to get
period: First period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
end_year: Last year of data to get
end_period: last period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)

pageParameters

JSON object that specifies the metrics to search for

metrics: Array of breakouts, get the list @ https://www.calcbench.com/api/availableBreakouts pass in the "databaseName".

Example form-data:


            {
            "pageParameters": {"metrics": ["operatingSegmentRevenue"]}, 
            "periodParameters": {"periodType": "annual", "period": null, "endPeriod": null, "endYear": null, "year": null}, 
            "companiesParameters": {"entireUniverse": false, "companyIdentifiers": ["msft"]}
            }

Returns an array of breakout points. Each has a formatted value and the unformatted value denoted by a _effvalue suffix. The label is the dimension label associated with the values. Example return value:


            [
            {'CIK': '0000789019', 'calendar_period': 0, 'sic_code': 7372, 'ticker': 'MSFT', 'accession_id': 136461, 'Company': 'Microsoft Corp', 'fast_index_dim': 5716150, 'is_subtotal': False, 'operatingSegmentRevenue': '$5,090,000,000', 'calendar_year': 2014, 'end_date': '2015-06-30T00:00:00', 'entity_id': 5716, 'operatingSegmentRevenue_effvalue': '5090000000.00000000', 'sec_html_url': 'http://www.sec.gov/Archives/edgar/data/789019/000119312515272806/0001193125-15-272806-index.htm', 'disclosure_type': '66', 'label': 'Consulting and product support services'}, 
            {'CIK': '0000789019', 'calendar_period': 0, 'sic_code': 7372, 'ticker': 'MSFT', 'accession_id': 136461, 'Company': 'Microsoft Corp', 'fast_index_dim': 5716150, 'is_subtotal': False, 'operatingSegmentRevenue': '$14,826,000,000', 'calendar_year': 2014, 'end_date': '2015-06-30T00:00:00', 'entity_id': 5716, 'operatingSegmentRevenue_effvalue': '14826000000.00000000', 'sec_html_url': 'http://www.sec.gov/Archives/edgar/data/789019/000119312515272806/0001193125-15-272806-index.htm', 'disclosure_type': '66', 'label': 'Windows PC operating system'}
            ]

Footnotes

Search for and download footnotes. The data behind the footnote page.

Get footnotes for a Company

POST to https://www.calcbench.com/api/footnoteSearch with the following URL parameters:

companiesParameters

JSON object that specifies the companies to include,

entireUniverse: Search for all companies, either true or false
companyIdentifiers: A array of tickers of tickers or CIKs (Central Index Key), for example ['msft', 'goog', 'appl']

periodParameters

JSON object that specifies the periods to include

year: First year of data to get
period: First period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)
end_year: Last year of data to get
end_period: last period to get, for annual data pass 0, for quarters pass one of (1, 2, 3, 4)

pageParameters

JSON object with search parameters, to get all footnote for on company pass

allFootnotes: true

To search for text in footnotes

fullTextQuery: Text to search for, use Lucene syntax.

Other methods of searching are supported, contact us to discuss.

Returns: An object, which has a list of footnotes, a nextGroupStartEntityID and a moreResults flag indicating whether there are more results to get. Example:


                {
                "footnotes": [
                {
                "fact_id": 27072908,
                "network_id": 24686868,
                "accession_id": 136461,
                "description": "ACCOUNTING POLICIES",
                "footnote_type": 165,
                "ticker": "MSFT",
                "SEC_URL": "http://www.sec.gov/Archives/edgar/data/789019/000119312515272806/0001193125-15-272806-index.htm",
                "SEC_ID": 0,
                "blob_id": null,
                "footnote_type_title": "Accounting Policies",
                "fiscal_period": "Y",
                "fiscal_year": 2015,
                "filing_date": "2015-07-31",
                "document_type": "10-K",
                "guide_link": null,
                "entity_name": "Microsoft Corp",
                "page_url": null
                }
                ],
                "nextGroupStartEntityID": 100,
                "moreResults": false
                }

Get Footnote Text

Get the contents of the footnote. GET to https://www.calcbench.com/api/footnote?networkID={networkID}, the networkID is the network id as returned by the footnotes end-point.

Returns: An object, the text of the footnote is a list of strings in the blobs value.


                {"blobs":["\n NOTE\n 1 — ACCOUNTING POLICIES
\n Accounting\n Principles
\n

\n We prepare our unaudited\n interim consolidated financial statements in conformity with\n accounting principles generally accepted..."], "entity_id":5716, "entity_name":"Microsoft Corp", "document_type":"10-Q", "end_date":"2015-09-30T00:00:00", "filing_date":"2015-10-22T00:00:00", "sec_html_url":"http://www.sec.gov/Archives/edgar/data/789019/000119312515350718/0001193125-15-350718-index.htm", "accession_id":142982, "label":"ACCOUNTING POLICIES", "fact_id":0, "disclosure_type":-1, "is_detail":false, "fiscal_period":null, "fiscal_year":0, "last_in_group":false}

Companies

Get companies from Calcbench. GET to https://www.calcbench.com/api/companies The following parameters are supported

universe: trueGet all companies
SICCodes: a list of SICCodes for which to get the companies for.
index: SP500 or DJIA for the Standard and Poores 500 or the Dow Jones Industrial Average components

Example : https://www.calcbench.com/api/companies?SICCodes=1200&SICCodes=1300

Returns a list of company objects, example


                [
                {
                "entity_id": 10797,
                "entity_name": "1PM Industries",
                "ticker": "OPMZ",
                "first_filing": "2015-08-13T00:00:00",
                "most_recent_filing": "2016-01-12T00:00:00",
                "most_recent_full_year_end": "2005-11-30T00:00:00",
                "sic_code": 1311,
                "naics_code": 211111,
                "cik_code": "0000859747",
                "most_recent_complete_calendar_year": 2005
                },
                {
                "entity_id": 8223,
                "entity_name": "Abby Inc.",
                "ticker": "ABBY",
                "first_filing": "2012-03-06T00:00:00",
                "most_recent_filing": "2013-04-22T00:00:00",
                "most_recent_full_year_end": "2011-11-30T00:00:00",
                "sic_code": 1311,
                "naics_code": 211111,
                "cik_code": "0001478535",
                "most_recent_complete_calendar_year": 2011
                }
                ]

Filings

XBRL and Non-XBRL Filings. POST to https://www.calcbench.com/api/filingsV2

companiesParameters

JSON object that specifies the companies to include,

companyIdentifiers: A array of tickers of tickers or CIKs (Central Index Key), for example ['msft', 'goog', 'appl']
entireUniverse: Include filings for all companies, either true or false

periodParameters

JSON object that specifies the periods to include

updateDate: Restrict results to filings from date, YYYY-mm-dd

pageParameters

JSON object

includeNonXBRL: Include non-XBRL filings in the results, earnings press-releases, proxy filings, etc.

Returns a list of filing objects, example


                [{'calcbench_accepted': '2009-10-23T08:34:21',
                'calcbench_id': 11493,
                'entity_id': 5716,
                'filing_date': '2009-10-23T00:00:00',
                'filing_sub_type': '10-Q',
                'filing_type': '10-Q',
                'fiscal_period': 1,
                'fiscal_year': 2010,
                'is_xbrl': True,
                'sec_accession_id': '0001193125-09-212454',
                'sec_html_url': 'http://www.sec.gov/Archives/edgar/data/789019/000119312509212454/0001193125-09-212454-index.htm',
                'ticker': 'MSFT'},
                {'calcbench_accepted': '2010-01-28T16:11:45',
                'calcbench_id': 11494,
                'entity_id': 5716,
                'filing_date': '2010-01-28T00:00:00',
                'filing_sub_type': '10-Q',
                'filing_type': '10-Q',
                'fiscal_period': 2,
                'fiscal_year': 2010,
                'is_xbrl': True,
                'sec_accession_id': '0001193125-10-015598',
                'sec_html_url': 'http://www.sec.gov/Archives/edgar/data/789019/000119312510015598/0001193125-10-015598-index.htm',
                'ticker': 'MSFT'}]