Introduction To Development With The True North Data Platform

by | Oct 15, 2018 | Solutions

Over the course of this four-part series, David North (Head of Engineering) and Sam Stancombe (Sales Engineer) explain the basics of developing against the True North Data Platform (TNDP) APIs, and give examples of what can be achieved. All the code samples can be found on CoreFiling’s Github account.

Introducing the TNDP

The TNDP is a set of applications and APIs which bring together many of the XBRL capabilities CoreFiling has built into our software over the years. This includes validation, rendering, conversion to/from different formats, and various types of analysis. Some of these capabilities are made available for limited free use via CoreFiling Labs. Because APIs are provided for every capability, users can build their own applications to complement and extend CoreFiling’s own.

Exploring using the developer centre

The easiest way to explore the TNDP APIs is to use the developer centre. This provides interactive documentation for all API endpoints available, and allows the simpler ones to be tried out interactively.

Please contact us for access to the developer centre and API key.

Choosing a programming language

At CoreFiling, our favourite programming languages are Java, Python and Typescript. For the examples in this series, we’ll use Python (version 3) as it’s concise. Since the TNDP APIs are built using REST and called over HTTPS, any language with an HTTP client can be used.

Getting an API key

In order to interact with the TNDP APIs from code, you will need an API key (if you’re familiar with OAuth 2 and OpenID Connect, this is actually a service account).

Your first API call

In order to test that your newly acquired service account works, you can use the following Python program:

#!/usr/bin/env python3

SERVICE_CLIENT_NAME = "my-service-client"
SERVICE_CLIENT_SECRET = "insert-your-secret-here-it-is-a-string-of-hexadecimal"

import re
import json
import requests
from os.path import expanduser
from requests.auth import HTTPBasicAuth

def main():
    at_response = json.loads(requests.post('https://login.corefiling.com/auth/realms/platform/protocol/openid-connect/token',
                                        data={'grant_type':'client_credentials'},
                                        auth=HTTPBasicAuth(SERVICE_CLIENT_NAME, SERVICE_CLIENT_SECRET)).text)
    access_token = at_response['access_token']

    headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}

    def get_filings(page=1):
        req = requests.get('https://api.apps.corefiling.com/document-service/v1/filings/?pageSize=1000&pageNumber=%s' % page, headers=headers)
        req.raise_for_status()
        return json.loads(req.text)

    print("Here is a list of filings in your account:")
    for f in get_filings():
        print("\t" + (f)["name"])

if __name__=='__main__':
    main()

This should produce output similar to the following:

Here is a list of filings in your account:
PEPSI BOTTLING GROUP INC (0001076405) 10-K, Dec 26, 2009
Alphabet Holding Company, Inc. (0001566978) 10-Q/A, 31 Dec 2015

Coming Up

In the next post, we will show you how to validate an individual XBRL filing, and work with the data once it is loaded into the platform.