Discussion Group

Join the open finance hackers discussion group for updates and ideas here >>

(Freerisk is under active development, and not all the pieces are in place yet. This site is a work in progress and is here to inspire more people to get involved in the project)

We're trying to build the simplest API that we can to create risk metrics, and we may have to evolve the specification as a result. We'll do our best to keep you updated and give you plenty of warning about any changes in advance. We'll try to stick to open standards like SparQL and JSON as much as possible.

Protocol Specification / Risk Calculator

A credit risk calculator is composed of a set of web calls under a single url, refered to as the "source" of the credit risk calculator. The following calls must all be available under the given names, relative to the source url (i.e. if source is "http://example.com/mycreditcalculator" then the query call must be available at "http://example.com/mycreditcalculator/query").

query?company=COMPANY.CIK.CODE&period=TIME.PERIOD

The query call supplies the calculator with the CIK code for the company in question and the time period in question. The calculator returns a SparQL query for Freerisk to execute on it's behalf. The results of this query will be posted back to the calculator for default risk calculation. The query returns a Query json object wrapping the SparQL query.

defaultRisk?data=JSON_STRING

The defaultRisk call returns a credit risk score given the data supplied. Data is supplied in the Financial Data json data format. The result of the calculation is a Risk Metric json object. This object can optionally carry with it the sensitivities of the metric to changes in the input data.

getDescription

The getDescription call returns a Description json object wrapping a text description of the calculator.

Freerisk RDF Data

TO DO

Freerisk Data Formats

Freerisk returns data in flattened formats, using name-value pairs, that are first scoped by date. Data element key names are all valid XBRL keys.

Financial Data Format

All financial data is passed from Freerisk is a single json format. The object consists of a set of time periods, each of which keys its own collection of name-value pair financial data. The financial data format is defined as follows:
KeyFormatValue
PeriodUnknownFinancialDataRecord*

Financial Data Record Format

Any element of financial data is passed as a name value pair binding the text value of the data element with the name of the element mapped to the XBRL name space.
KeyFormatValue
XBLR nameXBRL name identifierThe textual representation of the data.

Risk Metric Format

The risk metric json object wraps results from the credit risk calculators and provides optional sensitivity data for the metrics.
KeyFormatValue
"score"literalAny numeric rendering of the risk metric
"sensitivity"literalFinancialDataRecord* of sensitivities relative to the given data type.

Query Format

The query object format provides a simple wrapper for passing SparQL queries between Freerisk and associated risk calculators.
KeyFormatValue
"query"literalAny SparQL query

Description Format

The description object format provides a simple wrapper for passing calculator descriptions between Freerisk and associated risk calculators.
KeyFormatValue
"description"literalA html description of the calculator

Creating a credit calculator

A credit risk calculator involves implementing

Download a template

Freerisk currently offers two templates for creating credit risk calculators. One using Python and CherryPy, and one using Ruby and Ruby on Rails. We plan to have more in the future.

Support

The best developer support is currently available via our Google developer's group