Overview

Introduction

Welcome to the TagniFi API (v.2015-04-16).

Our API’s sole purpose is to deliver highly-accessible, accurate and timely financial data; enabling you to build the next-generation of financial applications.  To achieve this our API adheres to the following set of core tenets:

  • Usability –  We revere the idea of making our API as accessible and discoverable as possible. We value explicitness over implicitness. We want to provide the best API documentation, tools, and developer experience this side of the Internet.
  • Adaptability – The world changes and so will our API. It’s our intent to provide incremental updates and evolve without breaking your application.
  • Responsiveness – Our API should respect the temporal sensitivity of financial data. This means a couple of things, we will enable your application to have access to the latest financial data as it becomes available and we treat our performance as a critical success factor.

We take these tenets seriously. With that said, if you think we are missing the mark on any of these, please let us know.

A couple of other quick technical bullet points about our API, we do the following:

  • We currently only support JSON. Please let us know if you would like to see other formats.
  • Authenticate via Basic Auth over SSL.
  • Heavily leverage HTTP status codes for all responses.
  • Versioning is handled via a custom HTTP header. The header is named TagniFi-Version and contains an ISO8601 (YYYY-MM-DD) formatted date. Note: we will be publishing a changelog when we release our next version.

What’s Next?  Well, you can get started, provide feedback, or if anything is unclear, ask questions.

Back To Top

Getting Started

Follow these steps to get started with the TagniFi API:

  1. Obtain an API key.
  2. Visit the Authentication page to understand  how to send your API key to any Tagnifi API action.
  3. Read the Search Fundamentals or Search Markets documentation.
  4. Send your first request. To test it out before you write any code you can use a number of tool(s). If you like the command line give cURL a try. If a web interface whets your appetite then give Postman a spin. If neither of these work for you there are plethora of other choices.
  5. That’s it! Request away.

If you have any questions/comments or any other feedback, please let us know.

Don’t forget to subscribe to our system status updates!

Back To Top

Authentication

You authenticate to the Tagnifi API via HTTP Basic Auth over HTTPS. Please send your API key via the basic auth username; the basic auth password is not required.

Note: all requests must be made via HTTPS and must be authenticated. 

Back To Top

Actions

Search Fundamentals

Description

Searches for fundamental value(s) for specific fiscal periods (annual, quarter, or year to date). It also supports the ability to find all fundamentals for multiple periods and statements.

Request Parameters

AttributeDescriptionTypeRequired?DefaultNotes
companyThe company's ID or ticker symbol.StringYesPlease use our Coverage List to search for companies with data available.
tagReturns a specific tag from the TagniFi Fundamentals dataset.StringNoPlease see TagniFi Fundamentals Definitions for a list of available tags.
statementReturns all tags in the selected financial statement from the TagniFi Fundamentals dataset. StringNoPossible values: balance_sheet_statement, income_statement, or cash_flow_statement.
period_typeThe type of period to search. Valid periods include annual, quarter, or year_to_date.StringNoannual
fiscal_yearThe fiscal year of the period you are requesting.NumberNoCurrent year
fiscal_quarterThe fiscal quarter of the period you are requesting.NumberNo4This attribute is ignored if annual is specified for the period_type.
relative_periodReturns data relative to the most recent data available. For example, 0 returns the most recent data available.NumberNo0 (Most recent period)All periods returned are relative to the specified fiscal_year and fiscal_quarter and their associated defaults.
vintage_datePoint-in-time date used for back-testing, the Vintage Date will restrict the data for the selected period to use only data filed on or before the selected date.Date (ISO8601)NoCurrent dateThis date must be given in ISO-8601 date only format. Ex. 2013-03-01
industry_templateThe industry template for the data you are requesting.StringNoCommercialPossible values: commercial or banking
offsetThe number of rows to skip for a page of fundamentals.NumberNo0
limitThe number of values to return for a page of fundamentals.NumberNo1The maximum limit amount is 25.

Response

Returns a fundamental resource if there are no errors. It will return an error if the request fails.

Example Request/Response

Search Fundamentals Tag Example

Search Fundamentals Statement Example

Search Fundamentals Multiple Periods Example

Back To Top

Search Markets

Description

Searches for end-of-day market prices for specific or relative periods.

Request Properties

AttributeDescriptionTypeRequired?DefaultNotes
companyThe company's ID or ticker symbol.StringYesPlease use our Coverage List to search for companies with data available.
dateThe en-of-day date to retrieve market prices.Date (ISO8601)NoCurrent Date
relative_periodReturns data relative to the most recent data available. For example, 0 returns the most recent data available.NumberNo0 (Most recent period)All periods returned are relative to the specified date and their associated defaults.
splitReturns prices that are either adjusted or unadjusted based of splits.StringNounadjustedPossible values: adjusted or unadjusted.
offsetThe number of rows to skip for a page of fundamentals.IntegerNo0
limitThe number of values to return for a page of fundamentals.IntegerNo1The maximum limit amount is 25.

Response

Returns a market resource if there are no errors. It will return an error if the request fails.

Example Request/Response

Search Markets Example

Back To Top

Resources

Fundamental

Definition

Fundamental resources represent a list of fundamental values. When a fundamental is returned from an action, regardless if it’s a single fundamental tag or multiple fundamentals being returned,  it will always be wrapped within a fundamentals collection.

Attributes

AttributeTypeDescription
filing_typeStringThe type of the filing.
filing_linkStringA link to the filing on the SEC site.
statementStringThe tag's financial statement. Possible values: 'income_statement', 'balance_sheet_statement', 'cash_flow_statement'
reported_dateDate (ISO8601)The date the filing was submitted to the SEC.
start_periodDate (ISO8601)The start date of the period. Applies only to tags with duration types.
end_periodDate (ISO8601)The end date of the period.
fiscal_yearNumberThe fiscal year of the data.
fiscal_quarterNumberThe fiscal quarter of the data.
companyObjectCompany information. Please see the Company Resource.
tagsArrayArray of fundamental values which belong to this period. Please see the Fundamental Tag Resource.

Back To Top

Fundamental Tag

Definition

Fundamental tag resources represent a  fundamental value. When a fundamental is returned from an action, regardless if it’s a single fundamental value or multiple fundamentals being returned,  it will always be wrapped within a tags collection.

Attributes

AttributeTypeDescription
idStringTag's ID.
tagStringThe Fundamental tag. Please see Fundamental Tag Definitions for more information.
valueIntegerThe standardized value of the tag.
transparenciesListList of source transparency values. Please see the Fundamental Tag Transparency Definition.

Back To Top

Fundamental Transparency

Definition

Fundamental tag transparency resources represent a fundamental tag’s source transparency information.

Attributes

AttributeTypeDescription
nameStringThe name of the transparency item.
valueIntegerSource transparency item's value.
operatorStringOperator which is used with the other source transparency items to compute the value of the parent tag.
Operator values can be either a '-', '+', '*', or '/'.
sourceStringThe source of the transparency item. Source values can be xbrl_usgaap, xbrl_extension or tagnifi_fundamentals (for calculated tags).

Back To Top

Market

Definition

Market represent a list of market prices. When a price is returned from an action, regardless if it’s a single market price or multiple market prices being returned,  it will always be wrapped within a markets collection.

Attributes

AttributeTypeDescription
companyObjectCompany information. Please see the Company Resource.
pricesArrayArray of market prices which belong to this period. Please see the Market Price Resource.

Back To Top

Market Price

Definition

Market price resource represent a market price. When a market price is returned from an action, regardless if it’s a single market price or multiple market prices being returned,  it will always be wrapped within a markets collection.

Attributes

AttributeTypeDescription
dateDate (ISO8601)The date of the price.
closeNumberClose price for date.
openNumberOpen price for date.
highNumberHigh price for date.
lowNumberLow Price for date.
volumeNumberAmount traded for date.
adjustedBooleanSpecifies whether the data is adjusted for splits.

Back To Top

Company

Definition

Company resources represents a company within the TagniFi API. 

Attributes

AttributeTypeDescription
nameStringCompany's name.
idStringCompany's ID.
tickerStringCompany's ticker symbol.

Back To Top