Refinitiv Data Platform APIs

Introduction To Filings - Python
    Zoya Farberov
    Developer Advocate

Introducing Filings API Service on Refinitiv Data Platform

A new Filings API service is available on Refinitiv Data Platform (RDP) providing access to Global and EDGAR filing data for over 40 million documents from 135,000 companies worldwide, spanning over 50 years of history from 1968. Automated document feeds and newswires delivers timely and comprehensive collections for USA, Canada, Japan, Norway, Italy, Australia, Singapore, India, China and Korea.

Filings service consists of search and retrieval of public corporate disclosures. In this article, we will review on how to search for specific filings documents and to download the documents from the API.

Filings Search Using GraphQL

Filings documents can be searched through our GraphQL endpoint. GraphQL is a query language for APIs used on the front end to request and receive specific data in the response. Some capabilities used to search for filings documents include:

  • Filtering
  • Sorting
  • Limit
  • Pagination
  • Keyword Search

To learn more about GraphQL, please visit https://graphql.org/.

Python Environment

For the purpose of demonstration, we are going to use Jupyter Lab with Python 3..8.   We are going to discuss the code that is available for download from https://github.com

Valid Credentials - Replace in Code or Read From File

Valid RDP credentials are required to interact with an RDP service:

  • USERNAME
  • PASSWORD
  • CLIENTID

We include two ways to supply the valid credentials. 

  • One is, to replace the placeholders in code, "VALIDUSER" ... with the valid personal credential values.    To enact, comment out the call  to read cred from file: 

        #readCredsFromFile("..\creds\credFileHuman.txt")

  • The other way is to store a set of valid RDP credentials in a file that is stored in path "../creds" in file "credsFileHuman.txt" and have the code retrieve the credentials from the file.  

        The file is expected to be in simple format one entity per line:

 

Define Token Handling and Obtain a Valid Token

Having a valid token is a pre-requisite to requesting of any RDP content, and will be passed into the next steps.  For additional information on Authorization and Tokens, refer to RDP Tutorial: Authorization - All about tokens.

The implementation steps that come next may look familiar, as with some variation they come up repeatedly, with any RDP service interaction.

Define Filings Helper Function requestSearch

Search Filings by File Type

The following example searches for all 10-Qs on February 12, 2021. 

Once we have identified the required DocId or DocIds, and cusrsor, this info is used by the next steps to request the required Filings documents

Pagination

The maximum number response is 200 if a limit is not specified in the query. Since we use a cursor-based pagination, returns a pointer to a specific item in the dataset. Each cursors is unique to a specific record. Last record is used to paginate.

To view the next 25 responses in the previous example, set the cursor from the last data point in the response to retrieve 26-50.

Search by OrganizationId

Search for all filings documents for Tesla in 2021

Keyword Search by Document Text

One of the other features available in keyword word against document or section text.

Download Filings Documents

There are four identifers or retrieval methods you can use to download a document.

  • FilingId (FilingId, or Financial Filing Id, is an internal permanent identifier assigned to each filings document. This is our strategic filings identifier.)
  • Dcn (Dcn, also known as Document Control Number, is an external identifier and an enclosed film-number specific to Edgar documents.)
  • DocId (DocId, or Document Identifier, is an internal identifier assigned to financial filings documents.)
  • Filename (Filename provides a faster and direct route to download documents without going through a resolver.)

Define Helper Function retrieveURL

 Retrieve URL by DocID

Retrieve URL by FilingId

Download the Document

Now we are ready to download the Filings document and save it under downloads folder

At this point a filings pdf file is stores under downloads folder:

 

For more common use case examples that can be implemented in Python analogously, see Filings Developer Guide -> Section Use Cases 

References