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:
- 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}
- 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.
- 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.
- 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).
- 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:
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>