Summary

This documentation is for users of the FTS public API, which provides data in JSON or XML formats. The FTS data model has been redesigned completely, and is now structured around a flow model, where each record is conceptualised as a flow of funds from source to destination.  Resultsets of flows are retrieved by defining a boundary, into which funds flow into the boundary, internally within the boundary, or out of the boundary.  Based on these 3 categories, various groupings of the flows can then be set, giving multiple useful perspectives of the data.  More information about the flow model is presented in this short video.

The API is RESTful, and is accessed with GET requests only via https only.

Full details of how to use the FTS API can be found here: https://api.hpc.tools/docs/v1/

Accessing the API

Having reviewed usage logs of our API in 2017, we decided to make the public API openly accessible as of December 2017. This means that users will be able to request and view data in general without any special credentials. However, in order to manage our server loads, open access has limits on the number of requests allowed per hour. This limit is relatively generous to handle most general public users' needs, but we may adjust the limit as and when needed. If you need to request data on an ad hoc basis or just to play around with our data, then open access will probably be most suitable for your needs.

However, if you need regular continued access over an extended or indefinite period of time (for example you are connecting your website to our API to pull data), then it would be advisable to request a specific client id and password from us. Requests to the API with authentication will ensure that your usage limits are separate and at a higher level than open access. With your client id and password, you can access the API using HTTP Basic Authentication.  This means that for each request, you will need to set the ‘Authorization’ request header with ‘Basic ’  + base64 encoded version of "clientId:password".  For example, if your client id is “clientABC” and you password is “passwordXYZ”, you would set the header as such using base64 encoding:

GET /v1/public/fts/flow?year=2016 HTTP/1.1

Host: api.hpc.tools

Content-Type: application/json

Authorization: Basic base64(clientABC:passwordXYZ)

Most API client frameworks have native support for creating HTTP Basic Authentication headers.  To request a client ID and password, please email fts@un.org with the following information:

  • Your name and email

  • The name of your organization and country your office is located in

  • The URL of the website or application name which will be using the FTS API