[api]: https://filings.xbrl.org
[pd]: https://pandas.pydata.org
[sqlite]: https://www.sqlite.org/
[docs]: https://lsalmela.github.io/xbrl-filings-api
[pypi]: https://pypi.org/project/xbrl-filings-api "xbrl-filings-api entry on PyPI"
[lic]: https://spdx.org/licenses/MIT.html "MIT License"
# XBRL Filings API
Python API for filings.xbrl.org XBRL report repository.
This library provides:
1. Python-friendly access to the public API in [filings.xbrl.org][api]
2. Parallel downloading of associated files (ZIP, XHTML and JSON)
3. Integration to [pandas][pd]
4. Integration to [SQLite][sqlite] database, incl. SQLite views
(accounting reliability)
5. A few useful derived attributes
6. Possibility to strip redundant language versions/corrected filings
As of March 2024, all the filings in the database are Inline XBRL
reports. They are prepared in accordance to the European Single
Electronic Format (ESEF), the United Kingdom Single Electronic Format
(UKSEF), or the Ukraine Financial Reporting System. The first reports
are from financial year 2020 for all reporting formats.
In the case of ESEF, the reporters have issued securities on European
regulated markets in European Union member states. In most of the cases
these securities are shares. Issuers on alternative stock exchanges in
the EU such as the Nordic exchange First North are exempted from the
ESEF mandate and are thus not available.
This library is independent of XBRL International.
See [documentation for XBRL Filings API][docs]. The library is available
on [PyPI][pypi].
**Table of Contents**
- [License](#license)
- [Installation](#installation)
- [Data objects](#data-objects)
* [Filing](#filing)
* [Entity](#entity)
* [ValidationMessage](#validationmessage)
## License
``xbrl-filings-api`` is distributed under the terms of the [MIT][lic]
license.
## Installation
Install the library using pip.
```console
python -m pip install xbrl-filings-api
```
## Data objects
### Filing
Access to `entity` requires flag `GET_ENTITY` and to
`validation_messages` flag `GET_VALIDATION_MESSAGES`.
Data attributes:
| Attribute name | Type | Description | Query | JSON:API field name |
| ----------------------- | -------- | ----------------------------------- | ------- | --------------------- |
| `api_id` | str | JSON:API identifier | **X** | Resource `id` |
| `country` | str | Country of entity | **X** | `country` |
| `filing_index` | str | Database identifier | **X** | `fxo_id` |
| `language` | str | Language from `package_url`, `xhtml_url` | | *derived* |
| `last_end_date` | date | Last reported data date | **X** | `period_end` |
| `reporting_date` | date | Financial period end from `package_url` | | *derived* |
| `error_count` | int | Count of validation errors | | `error_count` |
| `inconsistency_count` | int | Count of validation inconsistencies | | `inconsistency_count` |
| `warning_count` | int | Count of validation warnings | | `warning_count` |
| `added_time` | datetime | Time when added to the database | **X** | `date_added ` |
| `processed_time` | datetime | Time when processed for the database | **X** | `processed` |
| `entity_api_id` | str | Same as `entity.api_id` | | Entity resource `id` |
| `json_url` | str | xBRL-JSON download URL | | `json_url` |
| `package_url` | str | ESEF report package download URL | | `package_url` |
| `viewer_url` | str | Inline XBRL viewer URL | | `viewer_url` |
| `xhtml_url` | str | Inline XBRL report download URL | | `report_url` |
| `query_time` | datetime | Time when query function was called | | \- |
| `request_url` | str | URL of the API request | | \- |
| `json_download_path` | str | Path where `json_url` was downloaded | | \- |
| `package_download_path` | str | Path where `package_url` was downloaded | | \- |
| `xhtml_download_path` | str | Path where `xhtml_url` was downloaded | | \- |
| `package_sha256` | str | SHA-256 checksum of `package_url` file | **X** |`sha256` |
As of April 2024, attributes ending with `_count` and `_url` could not
be used for filtering or sorting queries. This might change in future.
Object references:
| Attribute name | Type | Required flag for access |
| --------------------- | ------------------------ | ------------------------- |
| `entity` | Entity | `GET_ENTITY` |
| `validation_messages` | set of ValidationMessage | `GET_VALIDATION_MESSAGES` |
### Entity
Data attributes:
| Attribute name | Type | Description | JSON:API field name |
| ------------------------ | -------- | ----------------------------------- | ------------------- |
| `api_id` | str | JSON:API identifier | Resource `id` |
| `identifier` | str | XBRL identifier (e.g. LEI code) | `identifier` |
| `name` | str | Name | `name` |
| `api_entity_filings_url` | str | JSON:API query for its `filings` | \- |
| `query_time` | datetime | Time when query function was called | \- |
| `request_url` | str | URL of the API request | \- |
Object references:
| Attribute name | Type |
| -------------- | --------------|
| `filings` | set of Filing |
### ValidationMessage
Data attributes:
| Attribute name | Type | Description | JSON:API field name |
| ----------------------- | -------- | ----------------------------------- | ------------------- |
| `api_id` | str | JSON:API identifier | Resource `id` |
| `severity` | str | Severity of the issue | `severity` |
| `text` | str | Text of the message | `text` |
| `code` | str | Code of the breached rule | `code` |
| `filing_api_id` | str | Same as `filing.api_id` | Filing resource `id` |
| `calc_computed_sum` | float | Computed sum of calcInconsistency | *derived* |
| `calc_reported_sum` | float | Reported sum of calcInconsistency | *derived* |
| `calc_context_id` | str | Context ID of calcInconsistency | *derived* |
| `calc_line_item` | str | Line item of calcInconsistency | *derived* |
| `calc_short_role` | str | Short role of calcInconsistency | *derived* |
| `calc_unreported_items` | str | Unreported contributing items of calcInconsistency | *derived* |
| `duplicate_greater` | float | Greater one of duplicated facts | *derived* |
| `duplicate_lesser` | float | Lesser one of duplicated facts | *derived* |
| `query_time` | datetime | Time when query function was called | \- |
| `request_url` | str | URL of the API request | \- |
Derived attributes beginning `"calc_"` are only available for validation
messages with `code` `"xbrl.5.2.5.2:calcInconsistency"`. The ones
beginning `"duplicate_"` are available for `code`
`'message:tech_duplicated_facts1'` if the values are numeric. They are
parsed out from the `text` of the message.
Object references:
| Attribute name | Type |
| -------------- | --------------|
| `filing` | Filing |
Raw data
{
"_id": null,
"home_page": null,
"name": "xbrl-filings-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "AFR, ESEF, ESMA, EU, European Single Electronic Format, European Union, Extensible Business Reporting Language, IFRS, Inline XBRL, JSON, JSON-API, XBRL, accounting, accounting quality, annual financial report, consolidated, consolidation, financial analysis, financial statement, financial statement analysis, iXBRL, listed company, regulated markets, stock exchange, structured data, transparency",
"author": null,
"author_email": "Lauri Salmela <lauri.m.salmela@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c0/79/ff1e4dd662c44a9aca564b4197927fc8df3fe3aff94c50fcdf4b1388a8fb/xbrl_filings_api-1.0.tar.gz",
"platform": null,
"description": "[api]: https://filings.xbrl.org\n[pd]: https://pandas.pydata.org\n[sqlite]: https://www.sqlite.org/\n[docs]: https://lsalmela.github.io/xbrl-filings-api\n[pypi]: https://pypi.org/project/xbrl-filings-api \"xbrl-filings-api entry on PyPI\"\n[lic]: https://spdx.org/licenses/MIT.html \"MIT License\"\n\n# XBRL Filings API\n\nPython API for filings.xbrl.org XBRL report repository.\n\nThis library provides:\n\n1. Python-friendly access to the public API in [filings.xbrl.org][api]\n2. Parallel downloading of associated files (ZIP, XHTML and JSON)\n3. Integration to [pandas][pd]\n4. Integration to [SQLite][sqlite] database, incl. SQLite views\n (accounting reliability)\n5. A few useful derived attributes\n6. Possibility to strip redundant language versions/corrected filings\n\nAs of March 2024, all the filings in the database are Inline XBRL\nreports. They are prepared in accordance to the European Single\nElectronic Format (ESEF), the United Kingdom Single Electronic Format\n(UKSEF), or the Ukraine Financial Reporting System. The first reports\nare from financial year 2020 for all reporting formats.\n\nIn the case of ESEF, the reporters have issued securities on European\nregulated markets in European Union member states. In most of the cases\nthese securities are shares. Issuers on alternative stock exchanges in\nthe EU such as the Nordic exchange First North are exempted from the\nESEF mandate and are thus not available.\n\nThis library is independent of XBRL International.\n\nSee [documentation for XBRL Filings API][docs]. The library is available\non [PyPI][pypi].\n\n**Table of Contents**\n\n- [License](#license)\n- [Installation](#installation)\n- [Data objects](#data-objects)\n * [Filing](#filing)\n * [Entity](#entity)\n * [ValidationMessage](#validationmessage)\n\n## License\n\n``xbrl-filings-api`` is distributed under the terms of the [MIT][lic]\nlicense.\n\n## Installation\n\nInstall the library using pip.\n\n```console\npython -m pip install xbrl-filings-api\n```\n\n## Data objects\n\n### Filing\n\nAccess to `entity` requires flag `GET_ENTITY` and to\n`validation_messages` flag `GET_VALIDATION_MESSAGES`.\n\nData attributes:\n\n| Attribute name | Type | Description | Query | JSON:API field name |\n| ----------------------- | -------- | ----------------------------------- | ------- | --------------------- |\n| `api_id` | str | JSON:API identifier | **X** | Resource `id` |\n| `country` | str | Country of entity | **X** | `country` |\n| `filing_index` | str | Database identifier | **X** | `fxo_id` |\n| `language` | str | Language from `package_url`, `xhtml_url` | | *derived* |\n| `last_end_date` | date | Last reported data date | **X** | `period_end` |\n| `reporting_date` | date | Financial period end from `package_url` | | *derived* |\n| `error_count` | int | Count of validation errors | | `error_count` |\n| `inconsistency_count` | int | Count of validation inconsistencies | | `inconsistency_count` |\n| `warning_count` | int | Count of validation warnings | | `warning_count` |\n| `added_time` | datetime | Time when added to the database | **X** | `date_added ` |\n| `processed_time` | datetime | Time when processed for the database | **X** | `processed` |\n| `entity_api_id` | str | Same as `entity.api_id` | | Entity resource `id` |\n| `json_url` | str | xBRL-JSON download URL | | `json_url` |\n| `package_url` | str | ESEF report package download URL | | `package_url` |\n| `viewer_url` | str | Inline XBRL viewer URL | | `viewer_url` |\n| `xhtml_url` | str | Inline XBRL report download URL | | `report_url` |\n| `query_time` | datetime | Time when query function was called | | \\- |\n| `request_url` | str | URL of the API request | | \\- |\n| `json_download_path` | str | Path where `json_url` was downloaded | | \\- |\n| `package_download_path` | str | Path where `package_url` was downloaded | | \\- |\n| `xhtml_download_path` | str | Path where `xhtml_url` was downloaded | | \\- |\n| `package_sha256` | str | SHA-256 checksum of `package_url` file | **X** |`sha256` |\n\nAs of April 2024, attributes ending with `_count` and `_url` could not\nbe used for filtering or sorting queries. This might change in future.\n\nObject references:\n\n| Attribute name | Type | Required flag for access |\n| --------------------- | ------------------------ | ------------------------- |\n| `entity` | Entity | `GET_ENTITY` |\n| `validation_messages` | set of ValidationMessage | `GET_VALIDATION_MESSAGES` |\n\n\n### Entity\n\nData attributes:\n\n| Attribute name | Type | Description | JSON:API field name |\n| ------------------------ | -------- | ----------------------------------- | ------------------- |\n| `api_id` | str | JSON:API identifier | Resource `id` |\n| `identifier` | str | XBRL identifier (e.g. LEI code) | `identifier` |\n| `name` | str | Name | `name` |\n| `api_entity_filings_url` | str | JSON:API query for its `filings` | \\- |\n| `query_time` | datetime | Time when query function was called | \\- |\n| `request_url` | str | URL of the API request | \\- |\n\nObject references:\n\n| Attribute name | Type |\n| -------------- | --------------|\n| `filings` | set of Filing |\n\n\n### ValidationMessage\n\nData attributes:\n\n| Attribute name | Type | Description | JSON:API field name |\n| ----------------------- | -------- | ----------------------------------- | ------------------- |\n| `api_id` | str | JSON:API identifier | Resource `id` |\n| `severity` | str | Severity of the issue | `severity` |\n| `text` | str | Text of the message | `text` |\n| `code` | str | Code of the breached rule | `code` |\n| `filing_api_id` | str | Same as `filing.api_id` | Filing resource `id` |\n| `calc_computed_sum` | float | Computed sum of calcInconsistency | *derived* |\n| `calc_reported_sum` | float | Reported sum of calcInconsistency | *derived* |\n| `calc_context_id` | str | Context ID of calcInconsistency | *derived* |\n| `calc_line_item` | str | Line item of calcInconsistency | *derived* |\n| `calc_short_role` | str | Short role of calcInconsistency | *derived* |\n| `calc_unreported_items` | str | Unreported contributing items of calcInconsistency | *derived* |\n| `duplicate_greater` | float | Greater one of duplicated facts | *derived* |\n| `duplicate_lesser` | float | Lesser one of duplicated facts | *derived* |\n| `query_time` | datetime | Time when query function was called | \\- |\n| `request_url` | str | URL of the API request | \\- |\n\nDerived attributes beginning `\"calc_\"` are only available for validation\nmessages with `code` `\"xbrl.5.2.5.2:calcInconsistency\"`. The ones\nbeginning `\"duplicate_\"` are available for `code`\n`'message:tech_duplicated_facts1'` if the values are numeric. They are\nparsed out from the `text` of the message.\n\nObject references:\n\n| Attribute name | Type |\n| -------------- | --------------|\n| `filing` | Filing |\n",
"bugtrack_url": null,
"license": null,
"summary": "Python API for filings.xbrl.org XBRL report repository.",
"version": "1.0",
"project_urls": {
"Documentation": "https://lsalmela.github.io/xbrl-filings-api",
"Homepage": "https://github.com/lsalmela/xbrl-filings-api",
"Issues": "https://github.com/lsalmela/xbrl-filings-api/issues",
"Source": "https://github.com/lsalmela/xbrl-filings-api"
},
"split_keywords": [
"afr",
" esef",
" esma",
" eu",
" european single electronic format",
" european union",
" extensible business reporting language",
" ifrs",
" inline xbrl",
" json",
" json-api",
" xbrl",
" accounting",
" accounting quality",
" annual financial report",
" consolidated",
" consolidation",
" financial analysis",
" financial statement",
" financial statement analysis",
" ixbrl",
" listed company",
" regulated markets",
" stock exchange",
" structured data",
" transparency"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d60b688c5a34b4bd390a9ddf5372a9db9d4a31167ea526f1adff2fb68fc07a4c",
"md5": "f88eb4cd3d5255fffd5730a142d62b0d",
"sha256": "40a9a19c27d0ca6ef40758f0db8c14544394ac3f024c79a3e5ba7b00482a7bba"
},
"downloads": -1,
"filename": "xbrl_filings_api-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f88eb4cd3d5255fffd5730a142d62b0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 78115,
"upload_time": "2024-04-27T11:38:53",
"upload_time_iso_8601": "2024-04-27T11:38:53.111175Z",
"url": "https://files.pythonhosted.org/packages/d6/0b/688c5a34b4bd390a9ddf5372a9db9d4a31167ea526f1adff2fb68fc07a4c/xbrl_filings_api-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c079ff1e4dd662c44a9aca564b4197927fc8df3fe3aff94c50fcdf4b1388a8fb",
"md5": "68448dee7783b0482c690d81c7efe265",
"sha256": "3fc55dd5d5d091c69b833e13767844feb3a48e3d874d696ec7733d21695424cd"
},
"downloads": -1,
"filename": "xbrl_filings_api-1.0.tar.gz",
"has_sig": false,
"md5_digest": "68448dee7783b0482c690d81c7efe265",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 122647,
"upload_time": "2024-04-27T11:38:57",
"upload_time_iso_8601": "2024-04-27T11:38:57.904706Z",
"url": "https://files.pythonhosted.org/packages/c0/79/ff1e4dd662c44a9aca564b4197927fc8df3fe3aff94c50fcdf4b1388a8fb/xbrl_filings_api-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 11:38:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lsalmela",
"github_project": "xbrl-filings-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xbrl-filings-api"
}
JSON
