Metadata-Version: 2.1
Name: secapi-tl
Version: 1.1.12
License: MIT License
        
        Copyright (c) 2022 tlie03
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/tlie03/secapi
Requires-Python: >=2.7.18
Description-Content-Type: text/markdown
License-File: LICENSE

# secapi
This module provides an API that can be used to query metadata from sec
filings. These metadata can then be used to create a link to the actual filings
which can then be parsed.

## Technical information
The module was developed with python 2.7.18 and only uses build-in python packages as well
as the packages typing, requests, ratelimiter and [OpenDateRange](https://github.com/tlie03/OpenDateRange).

## Installation
``$ pip install secapi-tl``

## What functionalities does the API provide?
### Query filing metadata
The most important function ist the `get_filings` function
which takes one required and four optional search parameters.
The required parameter is the ticker symbol of the company 
whose filings are requested. If none of the optional arguments is 
set all filings of the given company will be returned.
The following arguments are optional.
* date_from : only filings that have been filed on this date or a current date
will be returned
* date_to : only filings that have been filed on this date or a former date
will be returned
* form_types : filters all filings based on a list of form types, so only filings
with a form type from the list will be returned
* filings_information: returns only the metadata points for each filing that
are included in the given list. This can be used to reduce the amount of data
and to get rid of irrelevant data.
A list of all possible data points can be found below

The return value will be a list of Filing Objects. Each Filing holds multiple 
metadata points. Two of these metadata points are the ticker symbol 
and the cik which are always part of the metadata.
By default, all other metadata points are contained in the Filing, but
they can also be specifically selected via the filing_information parameter
of the get_filings function.
Below is a list of all possible metadata points:
* accessionNumber
* filingDate
* reportDate
* acceptanceDateTime
* act
* form
* fileNumber
* filmNumber
* items
* size
* isXBRL
* isInlineXBRL
* primaryDocument
* primaryDocDescription

These metadata can then be used to create the links to the actual filings.
The process of finding a way to build the links from the metadata can be quite difficult, 
and requires a lot of experimentation.

### How to make requests to the sec server
The sec has restricted the access to their servers .Thereby it is not allowed
to do more than 10 requests per second. To ensure that the amount of requests stays
within the boundaries set by the sec this package provides the `sec_request`
function which can be used to do requests to the sec servers. The
function has a ratelimiter which ensures that the function can only be executed
10 times per second. Due to the sleep and retry property of the function
the user does not have to worry about the number of function calls he makes.
Furthermore, all code segments in this package that make requests
to the sec servers use the same function as well. Thereby the request limit
can not be exceeded when alle requests are made with the `sec_request`
function. Because of that it is necessary that a user of this API uses
this function for all requests to the sec servers otherwise problems can occur.


### Utility functions
* `get_cik` can be used to get the cik that belongs to a ticker symbol
* `is_registered` can be used to proof if a company is registered at the sec

Both functions take the ticker symbol of the company as an argument
