query¶

Define query functions for the API.

All the functions are accessible through the package root namespace.

The parameter filters in functions/methods accepts a mapping such as a dictionary. Key is the attribute being searched for and the value is the searched item or an iterable of searched items. Both attribute styles are supported: the ones used by this library and the actual attribute names in the API. Search is case-sensitive. The API only supports equivalence filtering of one value, but by giving the mapping a value which is an iterable of strings, you may execute multiple equivalence filtering queries in one function/method call.

You will find the list of valid filtering attributes in the keys of dict api_attribute_map. Bear in mind that derived attributes such as reporting_date or language may not be used for filtering.

To filter only the filings reported in Finland, you may use the following parameter:

filters={'country': 'FI'}

To filter reports of Finnish companies Apetit and Boreo, the most reliable way is to filter them using their LEI codes which are defined in the Entity.identifier attribute:

filters={'entity.identifier': [
            '743700RSFZUIQYABYT14',
            '743700OD4QRWKZ4ODC98']}

For validation messages, plural prefix "validation_messages." is required:

filters={
    'validation_messages.code': 'message:tech_duplicated_facts1'
    }

Date fields have a special functioning in filters. If you filter by a date that only has a year, 12 requests are made by default for the end dates of each month. The months will start by default from January of the specified year and continue until December of the same year. Option year_filter_months can be used to change this behaviour. So the following filter:

filters={'last_end_date': 2022}

Will yield requests with the following parameter values:

last_end_date='2022-01-31'
last_end_date='2022-02-28'
...
last_end_date='2022-11-30'
last_end_date='2022-12-31'

If you filter by a year and a month, the filter will assign the end date of that month to the filter automatically, so filters={'last_end_date': '2022-12'} becomes filters={'last_end_date': '2022-12-31'}.

The parameter sort in functions/methods accepts a single attribute string or a sequence (e.g. list) of attribute strings. Normal sort order is ascending, but descending order can be obtained by prefixing the attribute with a minus sign (-). As with filtering, attributes ending with _count and _url did not work in July 2023.

The keys of api_attribute_map dict are valid values for sort. To get the most recently added filings, specify the following parameter:

sort='-added_time'

Note

Apart from filing_page_iter, the query functions return custom set objects. Parameter sort can be used to filter either ends of the value spectrum but it does not mean that the returned sets would have any kind of order.

Functions

`get_filings`([filters, sort, limit, flags, ...])	Return a `FilingSet` of all the filings matching the query.
`to_sqlite`(path, *[, update, filters, sort, ...])	Insert all filings from the query to an SQLite database.
`filing_page_iter`([filters, sort, limit, ...])	Lazily iterate query results page by page.

xbrl_filings_api.query.get_filings(filters=None, *, sort=None, limit=0, flags=<ScopeFlag.GET_ONLY_FILINGS: 1>, add_api_params=None)¶

Return a FilingSet of all the filings matching the query.

See xbrl_filings_api.query module documentation for specifics of parameter usage.

Parameters:

filters (mapping of {str: any or iterable of any}, optional) – Mapping of filters. Iterable values may be used to make a logic OR-style query with multiple API requests.
sort (str or sequence of str, optional) – Used together with limit to return filings from either end of sorted attribute values. Order is lost in FilingSet object. Default order is ascending; prefix attribute name with minus (-) to get descending order.
limit (int, default NO_LIMIT) – Maximum number of filings to retrieve. Filings will be retrieved on pages (HTTP requests) of size options.max_page_size.
flags (ScopeFlag, default GET_ONLY_FILINGS) – Scope of retrieval. Flag GET_ENTITY will retrieve and create the object for Filing.entity and GET_VALIDATION_MESSAGES a set of objects for Filing.validation_messages.
add_api_params (mapping, optional) – Add additional, overriding request parameters to the query. All parts will be URL-encoded automatically. Cannot be used to override filters.

Returns:

Set of retrieved filings.

Return type:

FilingSet of Filing

Notes

Parameter add_api_params is handled by requests.Request parameter params.

xbrl_filings_api.query.to_sqlite(path, *, update=False, filters=None, sort=None, limit=0, flags=<ScopeFlag.GET_ONLY_FILINGS: 1>, add_api_params=None)¶

Insert all filings from the query to an SQLite database.

See xbrl_filings_api.query module documentation for specifics of parameter usage.

Tables Filing, Entity, and ValidationMessage will be created according to settings in parameter flags. Dependencies for SQL joins:

Filing.entity_api_id = Entity.api_id
Filing.api_id = ValidationMessage.filing_api_id

If parameter path value is a file and update is False (default), a FileExistsError exception will be raised. If update is True, retrieved records will update the existing ones based on primary key api_id in tables and the new objects will be added. A database to be updated may have additional tables and additional columns. Missing tables and columns will be created.

If the intermediary folders in parameter path do not exist, they will be created.

If update is True and the database does not have any expected tables defined or any of the expected tables contain no expected columns, a DatabaseSchemaUnmatchError exception will be raised.

Datetime values will be exported to the database as the same string that was received from the API. The format is, as of April 2024, strftime() format string %Y-%m-%d %H:%M:%S.%f or %Y-%m-%d %H:%M:%S.

Parameters:

path (str or Path) – Path to the SQLite database.
update (bool, default False) – If the database already exists, update it with retrieved records. Old records are updated and new ones are added.
filters (mapping of {str: any or iterable of any}, optional) – Mapping of filters. Iterable values may be used to make a logic OR-style query with multiple API requests.
sort (str or sequence of str, optional) – Used together with parameter limit to return filings from either end of sorted attribute values. Order is lost in FilingSet object. Default order is ascending; prefix attribute name with minus (-) to get descending order.
limit (int, default NO_LIMIT) – Maximum number of filings to retrieve. Filings will be retrieved on pages (HTTP requests) of size options.max_page_size.
flags (ScopeFlag, default GET_ONLY_FILINGS) – Scope of retrieval. Flag GET_ENTITY will retrieve entity records of filings and GET_VALIDATION_MESSAGES the validation messages.
add_api_params (mapping, optional) – Add additional, overriding request parameters to the query. All parts will be URL-encoded automatically. Cannot be used to override filters.

Raises:

APIError – First error returned by the filings API.
HTTPStatusError – If filings API does not return errors but HTTP status is not 200.
FileExistsError – When update is False and the intended save path for the database is an existing file.
DatabaseSchemaUnmatchError – When update is True and the file contains a database whose schema does not match the expected format.
requests.ConnectionError – If connection fails.
sqlite3.DatabaseError – For example when update is True and the file is not a database etc.

Return type:

None