FTS API user guide

Date

Modified by

Description

07/12/2012

Sean Foo

V1

11/01/2013

Sean Foo

V1.01, added pledges web service

27/03/2013

Sean Foo

V1.02, added nodes for funding and pledges to cluster, appeal and emergency web services

 

 

 

 

 

 

 

 

 


 

Table of contents

Table of contents  2

1     Overview     3

2     Web address and structure  3

3     Version 1 services  4

3.1     Data Lists  4

3.1.1     Sector, Country, Organization   4

3.1.2     Contribution   4

3.1.3     Project  5

3.1.4     Appeal  5

3.1.5     Emergency  5

3.1.6     Cluster   6

3.2     IATI outputs  6

3.3     Contributions to OCHA in IATI 7

3.4     Funding   8

3.4.1     Subtotals using the parameter “groupby”  9

3.5     Pledges  10

3.5.1     Subtotals using the parameter “groupby”  11

4     Appendix   12

4.1     Output examples  12

4.1.1     Contribution   12

4.1.2     Project  12

4.1.3     Appeal  13

4.1.4     Emergency  13

4.1.5     Cluster   13

4.1.6     IATI 14


 

1         Overview

FTS's aim is to categorise, publish and illustrate overall humanitarian funding trends based on data submitted by donors and agencies Data published on FTS is therefore different from that of common accounting reports and standards.  It serves as an approximate indication of humanitarian funding flows in real-time and does not reflect certified financial data.

FTS data, in addition to its website, is now also available in XML format.  This includes the standard provided by IATI, which aims to enable participating organisations to openly publish their available data on financial transactions in a common format to enable open data exchange.   The FTS’s web API is available for users to directly access selected data from the system, and obtain it in an XML or JSON format.

2         Web address and structure

The web address that these new web services are available are all under http://fts.unocha.org/api/v1/

The “v1” portion of the path is the version of the api.  In the future, should major changes be introduced, then this portion of the path will be used to separate new services from existing services.

The rest of the URL after the standard address, has a general form Object/Filter/Value.format. 

·         Object – this is the data element that is being requested e.g. Emergency, Appeal or Project.

·         Filter – this is the filter clause, how the data element should be filtered before being returned.  This is generally required, although for some simpler elements, there are no options. These are outlined in the service table below.  The filter will typically be an object name too.

·         Value – this is the value of the filter to be used.  It may be numeric or string text, depending on the filter method.

·         Format – there are currently 2 formats available, “xml” or “json”.  Specify this to get the output in the desired format.

One way to think when composing this URL structure is to say “show me the [object] where the [filter condition] is this [value]”.   So for example, to get a list of all appeals in the year 2012, the URL structure will look like this: Appeal/year/2012.xml

The next section lists all the current available services from the FTS api.


3         Version 1 services

The following are the list of options available in version 1.

3.1       Data Lists

These are sets of information which show the individual records of key elements within the FTS.  Some are reference type data such as countries and sectors, others are the main data elements within the system such as Emergencies and Contributions.  Each of these services offers the user a set choice of methods to get at individual records or groups of records.

3.1.1       Sector, Country, Organization

These are the standard lists of data.  There are no further filters to access these data types.

·         Sector.xml

·         Country.xml

·         Organization.xml

3.1.2       Contribution

Available Filter

Value data type

URL Example

Comments

Emergency

Numeric

Contribution/emergency/16062.xml

To get all contributions to an Emergency.  The value is the Emergency ID, which can be obtained from the “Emergency” webservice.

Appeal

Numeric

Contribution/appeal/941.xml

To get all contributions to a specific “Appeal”. The value is the Appeal ID.  This can be obtained from the “Appeal” webservice

Project

Numeric

Contribution/project/45608.xml

To get all contributions to a specific “Project”.  The project will be a record of a CAP project with a specific project ID.  An example of such a code is “SSD-12/CSS/45608”.  The last portion of this code, the number 45608 is the unique ID that can be used in the URL to get the list of contributions.

Project + query param

String

Contribution/
project.xml?code=SSD-12/CSS/45608

This is an alternative way to filter by project.  To get all contributions to a specific “Project”.  The project will be a record of a CAP project with a specific project code.  An example of such a code is “SSD-12/CSS/45608”.  The whole code can be provided in the URL, as shown in the example.

 

3.1.3       Project

Available Filter

Value data type

URL Example

Comments

ID

Numeric

project/id/45608.xml

To get information on a CAP project by its unique ID.  The unique ID can be found in the CAP project code. For example “SSD-12/CSS/45608”, the unique ID is the last portion of this code which in this case is 45608.

(query param)

string

project.xml?code=SSD-12/CSS/45608

To get information on a CAP project by its full project code.  For example “SSD-12/CSS/45608”.  In this case, the URL is modified to enable the entire code to be specified using a query parameter at the end.

Appeal

Numeric

Project/appeal/942.xml

To get all projects within a specified appeal.  The  value is the Appeal ID, which can be obtained from the “Appeal” webservice.

 

 

 

 

 

3.1.4       Appeal

Available Filter

Value data type

URL Example

Comments

ID

Numeric

Appeal/id/45608.xml

To get the information of an appeal, using its appeal ID.

Year

Numeric

Appeal/year/2012.xml

To get a list of appeals within a specified year.

Country

String

Appeal/country/Mali.xml

To get a list of all appeals for a specified country.  Note that the country can either be a full name, or the ISO code of the country.

 

3.1.5       Emergency

Available Filter

Value data type

URL Example

Comments

Year

Numeric

Emergency/year/2012.xml

To get a list of emergencies within a specified year.

Country

String

Emergency/country/pakistan.xml

To get a list of all emergencies for a specified country.  Note that the country can either be a full name, or the ISO code of the country.

 

3.1.6       Cluster

Available Filter

Value data type

URL Example

Comments

Appeal

Numeric

cluster/appeal/974.xml

To get a list of clusters within a specified appeal (by id), and the requirements of each cluster.  Note that if the requirements of a cluster are null, then it is currently not being used by the appeal.

 

 

 

 

 

 

3.2       IATI outputs

The API also offers an output of the data in IATI format.  The top level URL is /iati/

Available Filter

Value data type

URL Example

Comments

project

Numeric

iati/project/id/45608.xml

To get a single CAP project by its unique ID.  The unique ID can be found in the CAP project code. For example “SSD-12/CSS/45608”, the unique ID is the last portion of this code which in this case is 45608.

Project + query param

String

iati/
project.xml?code=SSD-12/CSS/45608

This is an alternative way to get a project, using the whole CAP project code.  An example of such a code is “SSD-12/CSS/45608”.  The whole code can be provided in the URL, as shown in the example.

emergency

numeric

Iati/Emergency/id/16104.xml

To get a list of all projects and contributions within a specified emergency.  The emergency ID is required in this case, a list of which can be obtained from the emergency web service.

 

 

 

 

 

3.3       Contributions to OCHA in IATI

Contributions to OCHA’s core activities can now also be viewed in the IATI format.  This is in conjunction with OCHA becoming a signatory to IATI in August 2012.  The information is segmented by year, and the top level URL is /iati/ocha/

Available Filter

Value data type

URL Example

Comments

year

Numeric

iati/ocha/year/2012.xml

To get all contributions to OCHA in the specified year.


 


3.4       Funding

The API provides a quick way to get summed totals of the funding recorded in FTS.  Note that the definition of funding in FTS is sum of contribution records marked as “commitments”, “paid contributions” and “carry over”.   This particular service allows the use of multiple query parameters, in addition to specifying how the total should be split and sub-totaled.   Because of the use of multiple parameters, these are appended to the end of the URL in the form:

funding.xml?param1=val1&param2=val2

e.g. funding.xml?country=Sudan&year=2012

The output in XML looks like this:

<funding>
   <total>1000000</total>

   <grouping>

<group>

<amount>1000000</amount>

<type/>

</group>

   </grouping>

   <grouping_type/>
</funding>

 

The following table shows the available parameters and information about them.

Parameter name

Value Data type

Comments

Emergency

String or Numeric

the FTS emergency ID number, or the exact emergency title.

Appeal

String or Numeric

the FTS appeal ID number, or the exact appeal title.

Country

String or Numeric

the official country name, or the FTS country ID, or the 3 letter ISO country code.  Note that if this parameter is specified, then the year parameter should also be specified.

Donor

String or Numeric

The FTS organization name or organization ID making the donation. Note that if this parameter is specified, then the year, appeal or emergency parameter should also be specified.

Recipient

String or Numeric

The FTS organization name or organization ID receiving the funds. Note that if this parameter is specified, then the year, appeal or emergency parameter should also be specified.

Year

Numeric

The year the contribution was made by the donor.

 


 

3.4.1       Subtotals using the parameter “groupby”

If required, an additional parameter “groupby” can be included in the URL to have the output include subtotals of the total.  For example groupby=sector, will include subtotals of funding grouped by sectors.

The following list of are valid group by values:

Donor

Recipient

Sector

Emergency

Appeal

Country

Cluster (only available if querying an appeal)

 

 

The output will look like this

<funding>

<total>1000000</total>

<grouping_type>sector</grouping_type>

<grouping>

<group>

<name>agriculture</name>

<amount>100000</amount> 

</group>

<group>

<name>education</name>

<amount>2000</amount>

</group>

</grouping>

</funding>


 

3.5       Pledges

Similar to funding, the API provides a quick way to get summed totals of the contribution pledges recorded in FTS.  This particular service follows the same web service pattern as that of “funding”.

pledges.xml?param1=val1&param2=val2

e.g. pledges.xml?country=sudan&year=2012

The output in XML looks like this:

<pledges>
   <total>1000000</total>

   <grouping>

<group>

<amount>1000000</amount>

<type/>

</group>

   </grouping>

   <grouping_type/>
</pledges>

 

The following table shows the available parameters and information about them.

Parameter name

Value Data type

Comments

Emergency

String or Numeric

the FTS emergency ID number, or the exact emergency title.

Appeal

String or Numeric

the FTS appeal ID number, or the exact appeal title.

Country

String or Numeric

the official country name, or the FTS country ID, or the 3 letter ISO country code.  Note that if this parameter is specified, then the year parameter should also be specified.

Donor

String or Numeric

The FTS organization name or organization ID making the donation. Note that if this parameter is specified, then the year, appeal or emergency parameter should also be specified.

Recipient

String or Numeric

The FTS organization name or organization ID receiving the funds. Note that if this parameter is specified, then the year, appeal or emergency parameter should also be specified.

Year

Numeric

The year the contribution was made by the donor.

 


 

3.5.1       Subtotals using the parameter “groupby”

If required, an additional parameter “groupby” can be included in the URL to have the output include subtotals of the total.  For example groupby=sector, will include subtotals of pledges grouped by sectors.

The following list of are valid group by values:

Donor

Recipient

Sector

Emergency

Appeal

Country

Cluster (only available if querying an appeal)

 

 

The output will look like this

<pledges>

<total>1000000</total>

<grouping_type>sector</grouping_type>

<grouping>

<group>

<name>agriculture</name>

<amount>100000</amount> 

</group>

<group>

<name>education</name>

<amount>2000</amount>

</group>

</grouping>

</pledges>

 

 


4         Appendix

4.1       Output examples

The following are the outputs of key FTS objects in XML format.  (Note that the equivalent in json is also available)

4.1.1       Contribution

<ArrayOfContribution>

<Contribution>

<amount>2000000</amount>

<appeal_id>949</appeal_id>

<appeal_title>Republic of South Sudan 2012</appeal_title>

<decision_date>2012-05-10T00:00:00</decision_date>

<donor>United States of America</donor>

<emergency_id>16104</emergency_id>

<emergency_title>Republic of South Sudan 2012</emergency_title>

<id>181987</id>

<is_allocation>0</is_allocation>

<project_code>SSD-12/CSS/45608/119</project_code>

<recipient>Office for the Coordination of Humanitarian Affairs</recipient>

<status>Commitment</status>

<year>2012</year>

</Contribution>

<ArrayOfContribution>

 

4.1.2       Project

<ArrayOfProject>

<Project>

<appeal_id>949</appeal_id>

<appeal_title>Republic of South Sudan 2012</appeal_title>

<cluster>COORDINATION AND COMMON SERVICES</cluster>

<code>SSD-12/CSS/45608/119</code>

<country>South Sudan</country>

<current_requirements>9551071</current_requirements>

<end_date>2012-12-31T00:00:00</end_date>

<gendermarker>2a</gendermarker>

<id>63234</id>

<last_updated_datetime>2012-10-17T15:03:00</last_updated_datetime>

<objective>To ensure coordinated, effective and principled humanitarian action to vulnerable people through providing coordination and support services, including emergency preparedness.</objective>

<organisation>Office for the Coordination of Humanitarian Affairs</organisation>

<organisation_abbreviation>OCHA</organisation_abbreviation>

<original_requirements>9405393</original_requirements>

<priority>HIGH PRIORITY</priority>

<sector>COORDINATION AND SUPPORT SERVICES</sector>

<title>Strengthening Humanitarian Coordination and Advocacy in South Sudan</title>

</Project>

</ArrayOfProject>

 

 

4.1.3       Appeal

<ArrayOfAppeal>

<Appeal>

<country>Chad</country>

<current_requirements>571946997</current_requirements>

<end_date>2012-12-31T00:00:00</end_date>

<emergency_id>16099</emergency_id>

<funding>100000</funding>

<id>942</id>

<launch_date>2011-12-14T00:00:00</launch_date>

<pledges>0</pledges>

<original_requirements>457367146</original_requirements>

<start_date>2012-01-01T00:00:00</start_date>

<title>Chad 2012</title>

<type>CAP</type>

<year>2012</year>

</Appeal>

</ArrayOfAppeal>

 

4.1.4       Emergency

<ArrayOfEmergency>

<Emergency>

<country>Chad</country>

<funding>100000</funding>

<glideid/>

<id>16099</id>

<pledges>0</pledges>

<title>Chad 2012</title>

<type>Complex Emergency</type>

<year>2012</year>

</Emergency>

</ArrayOfEmergency>

 

4.1.5       Cluster

<ArrayOfCluster>

<Cluster>

<current_requirement>24932067</current_requirement>

<funding>100000</funding>

<name>AGRICULTURE AND LIVELIHOODS</name>

<original_requirement>23805866</original_requirement>

<pledges>0</pledges>

</Cluster>

<Cluster>

<current_requirement>0</current_requirement>

<funding>0</funding>

<name>CLUSTER NOT YET SPECIFIED</name>

<original_requirement>0</original_requirement>

<pledges>0</pledges>

</Cluster>

<Cluster>

<current_requirement>22333097</current_requirement>

<funding>100000</funding>

<name>COORDINATION AND SUPPORT SERVICES</name>

<original_requirement>22236086</original_requirement>

<pledges>0</pledges>

</Cluster>

</ArrayOfCluster>


 

4.1.6       IATI

<iati-activities version="1.00" generated-datetime="2012-11-12T14:51:45" xmlns:fts="fts.unocha.org">

  <iati-activity xml:lang="en" default-currency="USD" hierarchy="1" last-updated-datetime="2012-02-01T16:25:00">

  <iati-identifier>41127-FTS:SDN-11/S-NF/37463/5926</iati-identifier>

  <reporting-org ref="41127-FTS" type="40">UNOCHA-FTS</reporting-org>

  <participating-org role="Implementing">World Relief</participating-org>

  <participating-org role="Funding" type="10">United States of America</participating-org>

  <participating-org role="Funding" type="40">Common Humanitarian Fund</participating-org>

  <recipient-country code="SD">SUDAN</recipient-country>

  <title>World Relief NFI program</title>

  <description type="2">To provide needs-based and timely non food items and emergency shelter to people affected by conflict and disaster, including IDPs, returnees, pastoralists and other vulnerable poplation of Azirni and Sanidadi.</description>

  <activity-date type="start-planned">2011-01-01</activity-date>

  <activity-date type="end-planned">2011-12-31</activity-date>

  <other-identifier>SDN-11/S-NF/37463/5926</other-identifier>

  <sector vocabulary="DAC" code="72010">Material relief assistance and services</sector>

  <sector vocabulary="RO">SHELTER AND NON-FOOD ITEMS</sector>

    <budget type="Original">

  <period-start iso-date="2011-01-01" />

  <period-end iso-date="2011-12-31" />

  <value value-date="2011-01-01">22224</value>

  </budget>

  <budget type="Revised">

  <period-start iso-date="2011-01-01" />

  <period-end iso-date="2011-12-31" />

  <value value-date="2011-01-01">22224</value>

  </budget>

  <fts:emergency-title xmlns:fts="nothing">Sudan 2011</fts:emergency-title>

  <fts:appeal-title xmlns:fts="nothing">Sudan 2011</fts:appeal-title>

  <fts:appeal-type code="10" xmlns:fts="nothing">CAP</fts:appeal-type>

  <fts:cluster xmlns:fts="nothing">NFI AND EMERGENCY SHELTER</fts:cluster>

  <fts:priority xmlns:fts="nothing">MEDIUM PRIORITY</fts:priority>

  <fts:gender-marker xmlns:fts="nothing">2a</fts:gender-marker>

  <transaction ref="177455">

  <transaction-type code="D">Disbursement</transaction-type>

  <provider-org>United States of America</provider-org>

  <receiver-org>World Relief</receiver-org>

  <value value-date="2011-11-04">33333</value>

  <transaction-date iso-date="2011-11-04" />

  <finance-type code="110">Grant</finance-type>

  <fts:contribution-category code="0" xmlns:fts="nothing">Contribution</fts:contribution-category>

  </transaction>

  <transaction ref="168388">

  <transaction-type code="D">Disbursement</transaction-type>

  <provider-org>Common Humanitarian Fund</provider-org>

  <receiver-org>World Relief</receiver-org>

  <value value-date="2011-05-08">22000</value>

  <transaction-date iso-date="2011-05-08" />

  <finance-type code="110">Grant</finance-type>

  <fts:contribution-category code="1" xmlns:fts="nothing">Allocation</fts:contribution-category>

  </transaction>

  </iati-activity>

  </iati-activities>