Global Filings API

  • SECTIONS
  • Overview
  • API Definition
  • SDK Libraries
  • Notebooks
  • Code Snippet
  • Changelog
Overview

The Global Filings API provides a comprehensive set of functionalities for searching and retrieving filing documents from various sources.

This API is designed to expose document search and document retrieval functionality. A document search will allow a request to query FactSet document databases based on certain search criteria specified in the request. The results are typically one or more filing document links. Given a particular document’s filing link, a document story request will retrieve and return the document requested. The two reports work together to provide the access to document information

This API uses query parameters to retrieve data from its sources. Each source has it's own history.

Below are the list of sources currently available.

  • EDGAR
  • EDINET
  • FactSet Blackline Report
  • FactSet Annuals & Interims
  • HNX News
  • SEDAR (filings sourced from the Canadian Corporate Disclosure Document Service through 9/30/2024)
  • SEDAR+ (filings sourced from the Canadian Corporate Disclosure Document Service beginning on 9/30/2024)
  • Johannesburg Stock Exchange (SENS)
  • Taiwan Stock Exchange Company Announcements
  • ASX Company Announcements - Delayed
  • GlobeNewswire Europe (OMX)

In addition, a document count request will provide information on the number of stories available for a particular security.

The reference endpoints, such as sources, formTypes, timeZones, and categories, provide comprehensive lists of available sources, form types, time zones, and categories, respectively.

How to Programmatically Download API Specification File

You can download the Global Filings API Specification File in .yaml. using the "Download Spec" button to the right of the version number. This specification can then be used for Codegen to create your own SDKs.

API Definition
SDK Libraries
Notebooks
Global Filings API V1 - Getting Started - SDK
Code Snippet
Global Filings Snippet - SDK
from fds.sdk.utils.authentication import ConfidentialClient # To install, please use pip install fds.sdk.utils

import fds.sdk.GlobalFilings # To install, please use pip install fds.sdk.GlobalFilings==0.20.0
from fds.sdk.GlobalFilings.api import filings_api_api
from fds.sdk.GlobalFilings.models import *
from dateutil.parser import parse as dateutil_parser
from pprint import pprint
import pandas as pd
import requests
import os
from urllib.parse import urlparse

# Basic authentication: FactSetApiKey
configuration = fds.sdk.GlobalFilings.Configuration(
     username='USERNAME',
     password='API-KEY'
 )

output_dir = 'C:/Users/USERNAME/XXXX' # make sure to replace 'USERNAME' with your actual username

print("Search endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)
    
    api_response = api_instance.get_filings(
            sources = ["EDG"], 
            ids = ["MODN-US"],
            start_date = "20231222",
            end_date = "20231223", 
            pagination_limit = 20, 
            pagination_offset = 0,
            time_zone = "America/New_York",
            sort = "desc", 
            categories = ["CN:US","LN:EN"],
            search_text = "Updates"
            
    )
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)
    
print("\n File download: ")

# Authorization for viewing the downloaded HTML files (Same credentials used for basic authentication)
authorization = ('USERNAME','API-KEY') 

# Download
item = api_response['data']
#print(item)
for item in api_response['data']:
    url = item['filings_link']
    #print(url)
    # Perform a GET request to download the HTML content
        
    try:
        response = requests.get(url, auth=authorization)
        response.raise_for_status()  # Raises an HTTPError if the HTTP request returned an unsuccessful status code
    except requests.RequestException as e:
        print(f"Request failed: {e}")
        continue

    # Generate a file name using document_id or another unique identifier in 'item'
    # Here, I'm stripping any parameters and queries from the URL, but you might want to use a different method
    parsed_url = urlparse(url)
    filename = f"{item['document_id']}_{os.path.basename(parsed_url.path)}.html"
    path = os.path.join(output_dir, filename)

    # Write the HTML content to a file
    try:
        with open(path, 'wb') as f:
            f.write(response.content)
        print(f"Downloaded: {filename}")
    except IOError as e:
        print(f"Failed to write to file: {e}")
    
print("\nSources endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)

    api_response = api_instance.get_sources()
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)

print("\nForm-types endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)

    api_response = api_instance.get_formtype()
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)

print("\nTime-zones endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)

    api_response = api_instance.get_timezone()
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)

print("\nCategories endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)

    api_response = api_instance.getcategories()
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)

print("\nCount endpoint response: ")
# Enter a context with an instance of the API client
with fds.sdk.GlobalFilings.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = filings_api_api.FilingsAPIApi(api_client)

    sources = ["EDG"] 
    ids = ["MODN-US"] 
    start_date = "20231222"
    end_date = "20231223"
    
    api_response = api_instance.get_count(sources, ids=ids, start_date=start_date, end_date=end_date)
    results = pd.DataFrame(api_response.to_dict()['data'])
    display(results)
Changelog

V1.0.0

Summary

  • Version 1.0.0 released on March 21st 2024

Functionality Additions

  • Ability to retrive the filing documents from various sources[1.0.0]