Taxonomy Resource

Taxonomy Resource

Overview

Which taxonomies are supported?

How to check if a new version of a Taxonomy resource is available to be retrieved from the server (ETags)

How do I know which taxonomy is the correct one to apply to the financial data I fetched?

GET taxonomy/

GET taxonomy/{Taxonomy ID}/calculation

GET taxonomy/{TaxonomyID}/fieldlabel

GET taxonomy/{TaxonomyID}/fieldproperty

GET taxonomy/{TaxonomyID}/presentation

Overview

You can call the Taxonomy resources to fetch information that provides important context to the full financials and core financials reported in filings. After you fetch the Taxonomy resources, you can then apply these resources to the core financials you fetch from DataFied's Core Financials API or to full financials you fetch from DataFied's Full Financials data API. You can fetch the following Taxonomy resources for each supported taxonomy and then apply the resources to financial data your application key is entitled to.

Resource Description
Calculation Returns parent/child calculation relationships between numeric fields in the data to validate the consistency of the data and accurately roll up the data. The calculation resource only applies to full financials reported in filings and does not apply to core financials reported in filings.
Fieldlabel Returns the standard label and definition for each field in the data.
Fieldproperty Returns the field properties of each field in the data including data type, period type, and natural balance type.
Presentation Returns parent/child presentation relationships between sections and fields in the data to apply a human-readable hierarchy and logical ordering of the data.
Taxonomy Returns the following summary information for each supported taxonomy: taxonomy name, taxonomy ID, and data set to which the taxonomy applies.

You can fetch the Taxonomy resources in .json or .xml format.

Note: The taxonomy resource is not applicable to data retrieved from the Insider Trades and Institutional Ownership data APIs. 

Which taxonomies are supported?

Seven taxonomies are supported. One taxonomy (Core Financials) applies to all core financials retrieved from the Core Financials data API. The correct taxonomy to apply to full financials retrieved from the Full Financials data API depends on the industry under which the reporting company is classified, as described in the table below. 

Data API Taxonomy ID Taxonomy Name Description
Core Financials 50 Core Financials Applies to core financials reported in filings.
Full Financials 18 Commercial and Industrial (CI) Applies to full financials reported in filings of companies classified under the Commercial and Industrial (CI) industry—for example, Microsoft.
Full Financials 19 Banks and Savings Institutions (BASI) Applies to full financials reported in filings of companies classified under the Banks and Savings Institutions (BASI) industry—for example, Bank of America.
Full Financials 20 Insurance Applies to full financials reported in filings of companies classified under the Insurance industry—for example, Marsh and McLennan Companies.
Full Financials 27 Real Estate Applies to full financials reported in filings of companies classified under the Real Estate industry—for example, The Howard Hughes Corporation.
Full Financials 28 Broker Dealer Applies to full financials reported in filings of companies classified under the Broker Dealer industry—for example, Charles Schwab.
Full Financials 30 Oil & Gas Applies to full financials reported in filings of companies classified under the Oil & Gas industry—for example, Exxon Mobil.

When you call the Taxonomy resource, you specify in the call the taxonomy ID of the respective taxonomy whose resources you want to fetch. For example, 18 is the taxonomy ID you would specify in the call to fetch the calculation, field label, field property, and presentation resources of the Commercial and Industrial (CI) taxonomy. You could then apply these CI taxonomy resources to full financials reported in filings by companies classified under the Commercial and Industrial (CI) industry--for example, Microsoft.

To see an example call to each Taxonomy resource, see the resources' documentation below. You can also use the Make Live API Calls page in the DataFied portal to test the Taxonomy resources. To do this, sign into the portal using the Sign In link above, select 'Taxonomy' from the drop-down list, and then expand a menu below for the Taxonomy resource you want to test and set up the call. Then click Try It to call the Taxonomy resource. The response is returned at the bottom of the Make Live API Calls page.

How do I know which taxonomy is the correct one to apply to the financial data I fetched?

Core Financials

Full Financials

Core Financials

When you call the Core Financials data API to fetch core financials data, you can set up the call such that the taxonomy ID of the correct taxonomy to apply to the core financials data is included in the response (50). This taxonomy ID is returned in the response as the value of the taxonomyID field.

To do this, you can either fetch all fields to which your app key is entitled which includes the taxonomy ID field (an app key is always entitled to the taxonomyID field) or specify in the call each entitled field you want to fetch, including the TaxonomyID field. Examples of each technique are shown below.

Example 1: Fetch all entitled fields including taxonomy ID when calling the Core Financials data API

In the following example, the call fetches all fields in the core financials data set. This call returns all core financials reported by Microsoft in the second quarter of 2015 and includes with the response the taxonomy ID of the correct taxonomy to apply to the data.

https://datafied.api.edgar-online.com/v2/corefinancials/qtr.json?primarysymbols=msft&fiscalperiod=2015q2&fields=all&appkey={APPKEY}

Note: If your app key is not entitled to all fields in the core financials data set, you must modify the example call above by listing all restricted fields to which your app key is not entitled as negated values. To do this, list in the 'fields' parameter each restricted field or concept group (separated by a comma) and include an exclamation point in front of each field or concept group you want to negate. If you do not do this, an error returns, listing each field to which your app key is not entitled.

In the following example demonstrating negation, the app key specified in the call is entitled to all fields except Price Revenue (Fiscal Year) and Price (Previous Close):

https://datafied.api.edgar-online.com/v2/corefinancials/qtr.json?primarysymbols=msft&fiscalperiod=2015q2&fields=all,!pricerevenuefy,!pricepreviousclose&appkey={APPKEY}

Example 2: Specify the taxonomy ID in the request when calling the Core Financials data API

In the following simple example, the call fetches the company name and period end date reported by Microsoft in core financials for the second quarter of 2015 and in addition, the taxonomy ID of the correct taxonomy to apply to the data.

https://datafied.api.edgar-online.com/v2/corefinancials/qtr.json?primarysymbols=msft&fiscalperiod=2015q2&fields=companyname,periodenddate,taxonomyid&appkey={APPKEY}

Response

{
   "result": {
      "totalrows": 1,
      "rows": [
         {
            "rownum": 1,
            "values": [
               {
                  "field": "companyname",
                  "value": "MICROSOFT CORP"
               },
               {
                  "field": "periodenddate",
                  "value": "12/31/2014 12:00 AM"
               },
               {
                  "field": "taxonomyid",
                  "value": "50"
               }
            ]
         }
      ]
   }
}

To fetch additional fields, you would specify each additional field in the value for the 'fields' parameter and separate each additional field with a comma.  

After you retrieve the taxonomy ID, you can then specify the taxonomy ID in calls to the Taxonomy resource to fetch the correct taxonomy resources to apply to the core financials data.

Full Financials

When you call the Full Financials data API to fetch full financials data, you can set up the call to also retrieve the taxonomy ID of the correct taxonomy to apply to the data (TaxonomyID field).

To do this, you can either fetch all fields to which your app key is entitled which includes the taxonomy ID field (an app key is always entitled to the taxonomyID field) or you can specify in the call each field you want to fetch, including the TaxonomyID field. Examples of each technique are shown below.

Example 1: Fetch all entitled full financials fields including taxonomy ID when calling the Full Financials data API

In the following example, the call fetches all fields in the full financials data set including the taxonomy ID. The response returns all full financials reported by Microsoft in the second quarter of 2015 and includes the taxonomy ID of the correct taxonomy to apply to the data.

https://datafied.api.edgar-online.com/v2/financials/qtr.json?primarysymbols=msft&fiscalperiod=2015q2&fields=defaultfieldgroup,!cusip&appkey={APPKEY}

Note: If your app key is also entitled to CUSIP, remove the negated CUSIP from the value specified for the 'fields' parameter to also fetch CUSIPs (fields=defaultfieldgroup). If you remove the negated CUSIP but your app key is not entitled to CUSIPs, an error will return.

Example 2: Specify the taxonomy ID in the request when calling the Full Financials data API

In the following simple example, the call fetches the company name and period end date reported by Microsoft in full financials for the second quarter of 2015 and in addition, the taxonomy ID of the correct taxonomy to apply to the data.

https://datafied.api.edgar-online.com/v2/financials/qtr.json?primarysymbols=msft&fiscalperiod=2015q2&fields=companyname,periodenddate,taxonomyid&appkey={APPKEY}

Response

{
   "result": {
      "totalrows": 1,
      "rows": [
         {
            "rownum": 1,
            "values": [
               {
                  "field": "companyname",
                  "value": "MICROSOFT CORP"
               },
               {
                  "field": "periodenddate",
                  "value": "12/31/2014 12:00 AM"
               },
               {
                  "field": "taxonomyid",
                  "value": "18"
               }
            ]
         }
      ]
   }
}

To return additional fields in the response, you would specify each additional field in the value for the 'fields' parameter and separate each additional field with a comma.  

After you retrieve the taxonomy ID, you can then specify this taxonomy ID in calls to the Taxonomy resource to fetch the correct taxonomy resources for the industry under which the reporting company is classified and then apply the resources to the full financials data.

How to check if a new version of a Taxonomy resource is available to be retrieved from the server (ETags)

An HTTP entity tag (ETag) is a unique identifier that is assigned to each new version of a Taxonomy's resources. The purpose of using the ETags mechanism is to avoid unnecessary taxonomy processing time by checking whether a new version of a resource is available to be retrieved from the server. If you've built a cache mechanism for your application, you can use ETags to always fetch the resource from cache instead of the server when you've cached the current version of the resource.

When you call a Taxonomy resource, the unique ETag identifier returns in the resource's response as the value of the 'etag' response header field. When you call the Taxonomy resource again, you can specify in the call the ETag value included in the resource's previous response to compare it with the ETag value associated with the current version of the resource on the server.

If the ETags do not match, this means that a new version of the resource is available. As a result, the server returns a payload containing the new version of the resource. However, if the ETags match, this means that you've already retrieved the current version of the resource and the server returns a 304 Not Modified response (with an empty payload). When the 304 Not Modified response returns in the response because you've already fetched the current version of the resource, you can then fetch the resource from the cache using the cache mechanism you've built because the cache contains the latest version.

The following Taxonomy resources support HTTP ETags: Calculation, Fieldlabel, Fieldproperty, and Presentation resources. The high-level process for using ETags is as follows: 

  1. Call a Taxonomy resource for a respective taxonomy for the first time to retrieve the resource—for example, the CI taxonomy's Fieldlabel resource (taxonomyID=18):
    https://datafied.api.edgar-online.com/taxonomy/18/fieldlabel?appkey={APPKEY}
  2. The server returns in the payload the resource you called in step 1. This response includes the 'etag' response header field with a corresponding value that uniquely identifies the current version of the resource. 

  3. Cache this current version of the resource returned by the server in Step 2 using a cache mechanism you've built for your application and store the ETag value uniquely identifies the current version of the resource.
  4. The next time you call the resource from step 1, specify in the call the ETag value that you stored in Step 3. You can specify the ETag value in the call in the following ways:
    • As a value of the http_etag query parameter. Example:
      https://datafied.api.edgar-online.com/taxonomy/18/fieldlabel?http_etag=asdfasdfdab28c180a38a8b0618f25a598478afa075ba7a1_json_utf-8&appkey={APPKEY}
    • As a value of the If-None-Match HTTP request header. Example:
      GET https://datafied.api.edgar-online.com/taxonomy/18/fieldlabel?appkey={APPKEY}
      Accept: application/json
      If-None-Match: asdfasdfdab28c180a38a8b0618f25a598478afa075ba7a1_json_utf-8

      Note: If the http_etag query parameter and If-None-Match HTTP request header are both specified in a call, the ETag value specified for the http_etag query parameter overrides the ETag value specified for the If-None-Match HTTP request header (the value specified for the If-None-Match HTTP request header is ignored by the server).

  5. The response of the resource you called in step 4 is returned in one of the following ways, depending on whether a new version of the resource is available:
    • A new version is not available. When the ETag value you specified in the call matches the ETag value assigned to the current version of the resource, this means that the resource has not changed (you already fetched the current version of the resource) and the server returns a 304 Not Modified response with an empty payload. When a new version of the resource is not available, you can then use the cache mechanism you've built to fetch the current version of the resource that is stored in the cache.

      Note: Each API call that returns a 304 Not Modified response counts toward your plan's quota.

    • A new version is available. When the ETag value you specified in the call does not match the ETag value assigned to the current version of the resource, this means that a new version of the resource is available, the resource is fetched from the server, and the response includes a new ETag value as the value of the 'etag' response header field that uniquely identifies the latest version of the resource. You should then cache this new version of the resource using your cache mechanism and store this new ETag value that uniquely identifies the latest version of the resource.

GET /taxonomy

Retrieves the taxonomy name, taxonomy ID, and corresponding data set of each supported taxonomy.

URL

https://datafied.api.edgar-online.com/taxonomy/?appkey={APPKEY}

Headers

Header Description Required Notes
Accept

Returns the response in xml or json format. Valid values:

application/json

application/xml

optional

Default: application/json


Sample Request

https://datafied.api.edgar-online.com/taxonomy/?appkey={APPKEY}

Response (JSON and XML)

Represents summary information about the supported taxonomies.

 

Element     Description Type Notes
taxonomies     Top level array of taxonomy objects    
  taxonomy   Describes a taxonomy object  
    id Taxonomy ID integer XML response: Returns as an attribute of the taxonomy element
    name Taxonomy name string XML response: Returns as an attribute of the taxonomy element
    dataset Corresponding data set to which the taxonomy applies string XML response: Returns as an attribute of the taxonomy element
  taxonomy   Next taxonomy in the response    

 

GET taxonomy/{Taxonomy ID}/calculation

Returns parent/child calculation relationships between fields of the specified taxonomy. Documentation for this resource's response is provided in .json and .xml format.

URL

https://datafied.api.edgar-online.com/taxonomy/{TaxonomyID}/calculation?appkey={APPKEY}

Request Headers

Header Description Type Required Notes
Accept

Formats the response in XML or JSON.

string optional

Values:

application/json, application/xml

Default: application/json

If-None-Match

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

Query Parameters

Parameter Description Type Required Notes
http_etag

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

TaxonomyID Specifies a taxonomy ID to return the calculation relationships of the specified taxonomy. integer required

Valid taxonomy IDs: 18, 19, 20, 27, 28, 30

Note: There is no Calculation resource for the Core taxonomy.

For a description of the taxonomy IDs, see Which Taxonomies are Supported?

Sample Request

The following sample request returns the calculation relationships for the Commercial and Industrial taxonomy (TaxonomyID=18). 

https://datafied.api.edgar-online.com/taxonomy/18/calculation?appkey={APPKEY}

JSON Response

Represents calculation relationships between fields of a taxonomy in JSON format.

Element         Description Type Notes
result         Top level

calculation relationships data object

 
  section       Describes sections of the financial data

array of objects where each object describes a section in the financial data containing calculation relationships and the section's calculation relationships

Examples of section names: Statement of Financial Position, Income Statement, Period Information, Statement of Cash Flows - Indirect Method
    id     Section ID integer  
    title     Name of the section string  
    relativeorder     Specifies the order  of the section, relative to the other sections in the financial data. float The order increases by increments of 100
    fieldhierarchy     Specifies the parent/child calculation relationships between fields belonging to the section array of objects where each object describes the parent and a child addend of a calculation relationship  
      parentfield   Describes the parent field of the calculation relationship object

The parent field in a calculation relationship is not the same parent field in a presentation relationship. This is because in a visual presentation relationship, the parent field is an abstract field that corresponds to a report heading and does not contain a value.   In a mathematical calculation relationship, the parent field represents the total for a calculation relationship and contains a value (total line item).

        id Parent field ID integer  
        value Name of the parent field string  
      childfield   Describes a child field of the calculation relationship object  
        id Child field ID integer  
        value Name of the child field string  
      weight   Specifies a multiplication factor to apply to the relationship. The multiplication factor is determined by the balance type (Debit or Credit) of the parent and child fields float

Possible values:

1.0000

-1.0000

      relativeorder  

Specifies the order of the child field relative to the other child fields included in the calculation relationship.

float The order increases by increments of 100.
      childlevel  

Specifies the level of the calculation relationship in relation to the overall calculation relationship hierarchy.

integer
A higher child level number indicates a deeper nesting in the hierarchy of calculation relationships for the financial data. For example, when the child level increases by 1, a field that was the parent field in a calculation relationship of child level = n can potentially be included as a child field in another calculation relationship where child level = n + 1.
    ------------     ...the section's next parent/child calculation relationship in the response.    
    id     ...next section in the response.    

JSON Sample Response (TaxonomyID=18)

Represents the beginning of the response of the calculation resource when TaxonomyID=18.


{
   "result": {
      "section": {

        {
            "id": "297640",
            "title": "Statement of Financial Position",
            "relativeorder": "100",
            "fieldhierarchy": [
             {
                "parentfield": {
               "id": "288634",
               "value": "Assets"
               },
               "childfield": {
               "id": "294253"
               "value": "CashCashEquivalentsFederalFunds"
               },
               "weight": "1.0000",
               "relativeorder": 100.0000",
               "childlevel": "1"
               },
                 ...the rest of the parent/child calculation relationships for the section return here. 
             ]
               ...the rest of the sections return here. 
        }
     ]
  }
}

XML Response

Represents calculation relationships between fields of a taxonomy in XML format.

Element       Attribute Description Type
result         Calculation relationships data object (top level).

array of section elements where each element describes a section in the financial data with calculation relationships and the section's calculation relationships 

Examples of sections: Statement of Financial Position, Income Statement, Period Information, Statement of Cash Flows - Indirect Method

  section       Describes a section in the financial data. Includes an array of fieldhierarchy elements where each fieldhierarchy element describes the parent and a child addend of a calculation relationship
        id Section ID integer
    title     Name of the section. string
    relativeorder    

Specifies the order of the section, relative to the other sections in the financial data.

The order increases by increments of 100.

float
    fieldhierearchy     Specifies the parent/child calculation relationships between fields belonging to the section  
      parentfield  

Name of the parent field.

The parent field in a calculation relationship is not the same parent field in a presentation relationship. This is because in a visual presentation relationship, the parent field is an abstract field that corresponds to a report heading and does not contain a value.   In a mathematical calculation relationship, the parent field represents the total for a calculation relationship and visually in the financial data, this value appears at the bottom of a visual presentation relationship (line item total).

string
        id Parent field ID integer
      childfield   Name of the child field of the calculation relationship. string
        id Child field ID integer
      weight   Specifies a multiplication factor to apply to the relationship. The multiplication factor is determined by the balance type (Debit or Credit) of the parent and child fields.

Possible values:

1.0000

-1.0000

float
      relativeorder   Specifies the order of the child field relative to the other child fields included in the calculation relationship. The order increases by increments of 100. float
      childlevel  

Specifies the level of the calculation relationship in relation to the overall calculation relationship hierarchy. .

A higher child level number indicates a deeper nesting in the hierarchy of calculation relationships for the financial data. For example, when the child level increases by 1, a field that was the parent field in a calculation relationship of child level = n can potentially be included as a child field in another calculation relationship where child level = n + 1.

integer
    fieldhierarchy     The section's next fieldhierarchy element in the response..  
  section       The next section in the response.  

XML Sample Response (TaxonomyID=18)

Represents the beginning of the response of the calculation resource when TaxonomyID=18. 

<result>
   <section id="297640">
      <title>Statement of Financial Position</title>
      <relativeorder>100</relativeorder>
      <fieldhierarchy>
         <parentfield id="288634">Assets</parentfield>
         <childfield id="294253" />CashCashEquivalentsFederalFunds</childfield>
         <weight>1.0000</weight>            
         <relativeorder>100.0000</relativeorder>            
         <childlevel>1</childlevel>        
      </fieldhierarchy>
       …the rest of the parent/child calculation relationships for the section return here. 
   </section>
    …the rest of the sections return here.
 </result>

GET taxonomy/{TaxonomyID}/fieldlabel

Returns human-readable labels that describe the fields in the data (Full, Primary, and Terse labels). When a definition is available for a field, the 'fieldlabel' resource returns this definition as the Full label. This definition can provide context for the field.

Documentation for this resource's response is provided in .json and .xml format.

URL

https://datafied.api.edgar-online.com/taxonomy/{TaxonomyID}/fieldlabel?appkey={APPKEY}&fieldID=field IDs&fieldname=field names

Headers

Header Description Type Required Notes
Accept

Formats the response in XML or JSON.

string optional

Values:

application/json, application/xml

Default: application/json

If-None-Match

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

Query Parameters

Parameter Description Type Required Notes
http_etag

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

TaxonomyID Specifies a taxonomy ID to return the corresponding field labels of the specified taxonomy. integer required

Valid IDs: 18, 19, 20, 27, 28, 30, 50

For a description of the taxonomy IDs, see Which Taxonomies are Supported?

fieldid

Specifies field IDs to only fetch field labels of the fields corresponding to the specified field IDs (see the field ID element in the response).

Separate each specified field ID with a comma (no space)

integer optional

If you specify the 'fieldid' query parameter in a call, do not also specify the 'fieldname' parameter in the call. If you specify both the 'fieldid' and 'fieldname' query parameters in a call, the call returns an error.

Default: Null (if the fieldid or fieldname parameters are not specified, all available field labels return in the response)

fieldname

Specifies field names to only fetch field labels of the fields corresponding to the specified field names (see the tag element in the response).

Separate each field name with a comma (no space)

 
string optional

If you specify the 'fieldname' query parameter in a call, do not also specify the 'fieldid' parameter in the call. If you specify both the 'fieldname' and 'fieldid' query parameters in a call, the call returns an error.

You must specify the name of the field (value of the tag element). If you specify the name of a label, an error will return.

Default: Null (if the fieldid or fieldname parameters are not specified, all available field labels return in the response)

Sample Request

Returns the field labels of the Commercial and Industrial taxonomy (TaxonomyID=18). 

https://datafied.api.edgar-online.com/taxonomy/18/fieldlabel?appkey={APPKEY}

JSON Response

Represents the human-readable labels for fields in JSON format.

Element       Description Type Notes
result       Top level Field labels data object
  total     Number of fields for which field labels are returned integer  
  field     Describes the field labels. array of objects where each object describes a field and its labels  


id   Field ID integer
    tag   Name of the field string  


rownum   Row number for the field integer


label   Specifies the description and label type ID for the field's labels. array of up to three labels



value The label's description. string



labeltypeid Indicates whether the label is the primary, terse, or full label. The primary label is the full name of the field, the terse label is a shortened name of the field with inferred descriptions omitted, and the full label is the definition of the field. integer

1 = Primary

2 = Terse

3= Full


field
  Next field in the array  

JSON Sample Response (TaxonomyID=18)

Represents the beginning of the label file response when TaxonomyID=18. 

{
   "result": {
      "total": 6121,
      "field": [
         {
            "id": 299404,
            "tag": "AcceleratedFiler",
            "rownum": "1",
            "label": [
               {
                  "value": "Accelerated Filer",
                  "labeltypeid": "1"
               },
              {
                  "value": "Accelerated Filer",
                  "labeltypeid": "2"
               },                      {
                  "value": "Accelerated Filer",
                  "labeltypeid": "3"
               },
                
                ...rest of the fields of the response return here.
               ]
         
             }
}

XML Response

Represents human-readable labels in XML format.

Element
  Attribute Description Type
result       Top level. field labels data object

    total Number of fields for which field labels are returned integer
  field  
Describes a field and its labels. array of up to three label elements (Primary, Terse, Full label)
 

 

  id

Field ID

integer
      tag Name of the field.  
      rownum Row number for the field. integer
 

 

label  

The label's description.

string
 

 

  labeltypeid

Indicates whether the label is the primary, terse, or full label. The primary label is the full name of the field, the terse label is a shortened name of the field with inferred descriptions omitted, and the full label is the definition of the field.

1=Primary label

2=Terse label

3=Full label

integer
  field     Next field in the array  

XML Sample Response (TaxonomyID=18)

Represents the beginning of the label file response when TaxonomyID=18. 

<result total="6121">
    <field id="299404 tag="AcceleratedFiler" rownum="1">
        <label labeltypeid="1">Accelerated Filer</label>      
        <label labeltypeid="2">Accelerated Filer</label>        
        <label labeltypeid="3">Accelerated Filer</label>
    </field>
   ...the rest of the human-readable labels return here.
</result>

GET taxonomy/{TaxonomyID}/fieldproperty

Returns the properties of each field included in the taxonomy. These field properties include data type, period type, balance type, and so forth. Documentation for this resource's response is provided in .json and .xml format.

URL

https://datafied.api.edgar-online.com/taxonomy/{TaxonomyID}/fieldproperty?appkey={APPKEY}

Headers

Header Description Type Required Notes
Accept

Formats the response in XML or JSON.

string optional

Values:

application/json,

application/xml

Default: application/json

If-None-Match

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

Query Parameters

Parameter Description Type Required Notes
http_etag

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

TaxonomyID Specifies a taxonomy ID to return the field properties for the fields of the specified taxonomy integer required

Valid IDs: 18, 19, 20, 27, 28, 30, 50

For a description of the taxonomy IDs, see Which Taxonomies are Supported?

Sample Request

The following sample request returns the field properties for the fields of the Commercial and Industrial (CI) taxonomy (TaxonomyID=18). 

https://datafied.api.edgar-online.com/taxonomy/18/fieldproperty?appkey={APPKEY} 

JSON Response

Represents field properties in JSON format.

Element         Description Type Notes
result         Top level  Field properties data object  
  total       Number of fields returned. integer  
  field      

Describes fields and their properties

array of objects where each object describes a field and the field's properties  
    id     Field ID integer  
    name     Name of the field string  
    rownum     The field's row number integer  
    datatype     Describes the field's data type object  
      id  

Data type ID

integer

1 = Abstract

2 = Tuple

3 = DateTime

4 = Decimal

5 = Monetary

6 = Shares

7 = String

8 = Ratio

12 = Boolean

13 = Date

15 = Integer

34 = percentItemType

      description   Name of the field's data type string  
      extendedproperty   Describes the field's extended properties object  
        isnumeric Indicates whether the field is numeric (=1) or not numeric (=0) integer (0 or 1)
 
        ismoney Indicates whether the field is contains a monetary value (=1) or does not contain a monetary value (=0) integer (0 or 1)  
        canholdvalue Indicates whether the field can hold a value (=1) or cannot hold a value (=0)    integer (0 or 1) A field that cannot hold a value is typically an abstract field. Abstract fields correspond to the headings in a financial report.
        issection Indicates whether the field is a section (=1) or is not a section (=0)
integer (0 or 1) Examples of sections: Income Statement, Miscellaneous Items, Statement of Cash Flows Direct, Statement of Cash Flows Indirect, Statement of Financial Position, Summary Income Statement, Summary Statement of Cash Flows Indirect, Summary Statement of Financial Position
    periodtype     The field's period type object If the field does not have a period type, the periodtype object is excluded from the response. For example, the DepositsByType is an abstract field that does not hold a value (report heading) so the periodtype object is not returned for this field.
      id   Period type ID

 

integer

1 = Duration

2 = Instant

      description   Period type description (Instant or Duration) string  
    balancetype     The field's balance type object If the field does not have a balance type, the balancetype object is excluded from the response. For example, the AcceleratedFiler field indicates whether the company is an accelerated filer so the field does not have a balance type and the balancetype object is excluded from the response for this field.

    id   Balance type ID   integer 1 = Credit   2 = Debit

    description   Balance type description (Credit or Debit) string  
    id     Next field in the response.    

JSON Sample Response (TaxonomyID=18)

Represents the field properties of fields when TaxonomyID=18.  

Note: The AcceleratedFiler field does not have a balance type as it is neither Debit or Credit so the balancetype object is excluded from the response.  

{
   "result": {
      "total": 6121,
      "field": [
         {
            "id": 299404,
            "name": "AcceleratedFiler",
            "rownum": "1",
            "datatype": {
              "id": "7",               
             "description": "String",               
             "extendedproperty": {                  
                 "isnumeric": "0",                  
                 "ismoney": "0",                  
                 "canholdavalue": "1",                  
                 "issection": "0"
             }
          },            
            "periodtype": {               
            "id": "2",               
                 "description": "Instant"
             },            
          },    
          …the rest of the field properties return here.
         ]
       }
   }

XML Response

Represents the field properties in XML format.

Element         Attribute Description Type
result           Top level array of field elements where each element describes a field and the field's properties
          total Number of fields returned. integer
  field         Describes a field and its properties.  
   
    id Field ID integer
   
    rownum Row number for the field integer
    name       Field name string
    datatype       Describes the field's data type  
          id

Date type ID

1 = Abstract

2 = Tuple

3 = DateTime

4 = Decimal

5 = Monetary

6 = Shares

7 = String

8 = Ratio

12 = Boolean

13 = Date

15 = Integer

34 = percentItemType

integer
      description     Name of the field's data type string
      extendedproperty     Describes the field's extended properties  
        isnumeric   Indicates whether the field is numeric (=1) or not numeric (=0) integer (0 or 1)
        ismoney   Indicates whether the field contains a monetary value (=1) or does not contain a monetary value (=0) integer (0 or 1)
        canholdvalue  

Indicates whether the field can hold a value (=1) or cannot hold a value (=0)

A field that cannot hold a value is typically an abstract field. Abstract fields correspond to the headings in a financial report.

integer (0 or 1)
        issection  

Indicates whether the field is a section (=1) or is not a section (=0)

Examples of sections: Income Statement, Miscellaneous Items, Statement of Cash Flows Direct, Statement of Cash Flows Indirect, Statement of Financial Position, Summary Income Statement, Summary Statement of Cash Flows Indirect, Summary Statement of Financial Position

integer (0 or 1)
    periodtype      

Describes the field's period type

If the field does not have a period type, the periodtype object is excluded from the response. For example, the DepositsByType is an abstract field that does not hold a value (report heading) so the periodtype object is not returned for this field.

 
       
id

Period type ID

1 = Duration

2 = Instant

integer
     
description  

Name of the period type

string
    balancetype  
 

Describes the field's balance type.

If the field does not have a balance type, the balancetype object is excluded from the response. For example, the AcceleratedFiler field indicates whether the company is an accelerated filer so the field does not have a balance type and the balancetype object is excluded from the response for this field.

description element
       
id

Balance type ID

1 = Credit

2 = Debit

integer
        description   Name of the balance type. string
  field         Next field element in the response.  

XML Sample Response (TaxonomyID=18)

Represents the field properties of fields when TaxonomyID=18.  

Note: The AcceleratedFiler field does not have a balance type as it is neither Debit or Credit so the balancetype object is excluded from the response.  

<result total="6121">   
   <field id="299404" rownum="1">        
      <name>AcceleratedFiler</name>        
      <datatype id="7">            
           <description>String</description>            
           <extendedproperty>                
                <isnumeric>0</isnumeric>                
                <ismoney>0</ismoney>                
                <canholdavalue>1</canholdavalue>                
                <issection>0</issection>            
           </extendedproperty>        
     </datatype>        
     <periodtype id="2">            
           <description>Instant</description>        
    </periodtype>           
  </field> 
…the rest of the field properties return here.
</result>

GET taxonomy/{TaxonomyID}/presentation

Returns the presentation relationships between fields of the specified taxonomy to apply a human-readable hierarchy and logical organization of rows to the retrieved financial data. The presentation is expressed through parent and child relationships between fields.

These presentation relationships are expressed as a parent abstract field (report heading) and child fields holding values or child report subheadings. The nesting of these presentation relationships are defined by the assigned child level to form the presentation hierarchy.

Documentation for this resource's response is provided in .json and .xml format.

URL

https://datafied.api.edgar-online.com/taxonomy/{TaxonomyID}/presentation?appkey={APPKEY}

Headers

Header Description Type Required Notes
Accept

Formats the response in XML or JSON.

string optional

Values:

application/json, application/xml

Default: application/json

If-None-Match

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

Query Parameters

Parameter Description Type Required Notes
http_etag

Specifies the ETag value that was returned in the "ETag" response header field in the resource's previous response to check if a new version of the resource is available to be retrieved from the server.

For more information, see ETags.

string optional

Default: None

TaxonomyID Specifies a taxonomy ID to return the presentation relationships for the fields of the specified taxonomy integer required

Valid IDs: 18, 19, 20, 27, 28, 30, 50

For a description of the taxonomy IDs, see Which Taxonomies are Supported?


Sample Request

The following sample request returns the presentation file of the Commercial and Industrial taxonomy (TaxonomyID=18). 

https://datafied.api.edgar-online.com/taxonomy/18/presentation.json?appkey={APPKEY}

JSON Response

Represents presentation relationships between fields.

Element         Description Type Notes
result         Top level object  
  section       Describes the sections appearing in the financial data array of objects where each object describes a section and the section's presentation relationships Each section object corresponds to the major, top-level sections of the data set such as Statement of Financial Position and Income Statement. 
    id     Section ID integer  
    title    

Name of the section

string  
    relativeorder     Specifies the order of the section in relation to the other sections appearing in the report. This order organizes the data in a logical, intuitive fashion  float The order increases by increments of 100
    fieldhierarchy     Specifies all parent/child presentation relationships between the fields appearing in the section array of objects where each object describes a single parent/child presentation relationship  
      parentfield   Describes the parent field of the presentation relationship object  
        id Parent field ID integer  
        value Name of the parent field string This name typically ends in 'Abstract' and corresponds to a report heading (an abstract field that does not hold a value).

      childfield   Describes the child field of the presentation relationship object  
        id Child field ID integer  
        value Name of the child field string  
      labeltypeid    Label type ID integer Specifies the label type ID for the field's field label (see fieldlabel resource)   Returns 1 in the response for all fields (Primary field label)
      relativeorder   Specifies the order beneath the parent abstract field at which the child field is located in the presentation. This order organizes the data in a logical, intuitive fashion  float The order increases by increments of 100  
      childlevel   Specifies the level of indentation into the presentation hierarchy at which this parent/child presentation relationship is located within the section integer A higher number indicates a further nesting to the right in the section's presentation hierarchy
    fieldhierarchy     Rest of parent/child presentation relationship for the section.    
    id     Next section in the presentation.    

JSON Sample Response (TaxonomyID=18)

Represents the beginning of the presentation file response when TaxonomyID=18. 

Note: The parent ‘IMetrix_StatementFinancialPosition’ abstract line refers to the balance sheet.

{

  "result": {

      "section": [

        "id": "299537",

        "title": "Company Statistics",

        "relativeorder": "100",

        "fieldhierarchy": [

          {

            "parentfield": {

              "id": "299537",

              "value": "IMetrix_CompanyStatistics"

            },

            "childfield": {

              "id": "299534",

              "value": "CompanyStatisticsAbstract"

            },

            "labeltypeid": "1",

            "relativeorder": "100.0000",

            "childlevel": "0"

          },
         ...the rest of parent/child presentation relationships for the section return here. 
]

...rest of the sections of the presentation file return here.

}]}
}

XML Response

Represents presentation relationships between fields.

Element    
Attribute Description Type
result         Top level

array of section elements

 

section

 

 

 

Describes a section appearing in the financial data and the section's presentation relationships.

Example of sections: Income Statement, Miscellaneous Items, Statement of Cash Flows Direct, Statement of Cash Flows Indirect, Statement of Financial Position, Summary Income Statement, Summary Statement of Cash Flows Indirect, Summary Statement of Financial Position

title and relativeorder elements and array of fieldhierarchy elements
        id Section ID integer
    title     Name of the section string
    relativeorder    

Specifies the order of the section in relation to the other sections appearing in the report. This order organizes the data in a logical, intuitive fashion.

The order increases by increments of 100.

float
    fieldhierarchy     Describes a parent/child presentation relationship for a section.  
      parentfield  

Name of the parent field of the presentation relationship

This name typically ends in 'Abstract' and corresponds to a report heading (an abstract field that does not hold a value).

string
        id Parent field ID integer
      childfield   Name of the child field of the presentation relationship N/A
        id Child field ID integer
      labeltypeid  

  Specifies the label type ID for the field's field label (see fieldlabel resource).

Returns 1 in the response for all fields (Primary field label)

integer
      relativeorder  

Specifies the order beneath the parent abstract field at which the child field is located in the presentation order. This order organizes the data in a logical, intuitive fashion.

The order increases by increments of 100.

float
      childlevel  

Specifies the level of indentation into the presentation hierarchy at which this parent/child presentation relationship is located within the section.

A higher number indicates a further nesting to the right in the section's presentation hierarchy.

integer
    fieldhierarchy     Rest of parent/child presentation relationship for the section.  
  section       Next section in the presentation  

XML Sample Response (TaxonomyID=18)

Represents the beginning of the presentation file response when TaxonomyID=18.

Note: The parent ‘IMetrix_StatementFinancialPosition’ abstract line refers to the balance sheet.

<result>
    <section id="299537">

         <title>Company Statistics</title>

         <relativeorder>100</relativeorder

         <fieldhierarchy>

              <parentfield id="299537">IMetrix_CompanyStatistics</parentfield>

              <childfield id="299534"/>CompanyStatisticsAbstract</childfield>

              <labeltypeid>1</labeltypeid>

              <relativeorder>100.0000</relativeorder>

              <childlevel>0</childlevel>

              ...rest of the presentation relationships for the section return here.

         </fieldhierarchy>

     ...rest of the sections return here....

     </section>
</result>