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

2 Web address and structure 3

3 Version 1 services 4

3.1 Data Lists 4

3.1.1 Sector, Country, Organization 4

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

1 Overview

The FTS has a new web API 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:

<group>

<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

<grouping_type>sector</grouping_type>

<group>

<name>agriculture</name>

</group>

<group>

<name>education</name>

</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:

<group>

<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”

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

<grouping_type>sector</grouping_type>

<group>

<name>agriculture</name>

</group>

<group>

<name>education</name>

</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

<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>

<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>

</Contribution>

4.1.2 Project

<appeal_id>949</appeal_id>

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

<cluster>COORDINATION AND COMMON SERVICES</cluster>

<country>South Sudan</country>

<current_requirements>9551071</current_requirements>

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

<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

<current_requirements>571946997</current_requirements>

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

<emergency_id>16099</emergency_id>

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

<original_requirements>457367146</original_requirements>

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

</Appeal>

</ArrayOfAppeal>

4.1.4 Emergency

<type>Complex Emergency</type>

</Emergency>

</ArrayOfEmergency>

4.1.5 Cluster

<current_requirement>24932067</current_requirement>

<name>AGRICULTURE AND LIVELIHOODS</name>

<original_requirement>23805866</original_requirement>

</Cluster>

<current_requirement>0</current_requirement>

<name>CLUSTER NOT YET SPECIFIED</name>

<original_requirement>0</original_requirement>

</Cluster>

<current_requirement>22333097</current_requirement>

<name>COORDINATION AND SUPPORT SERVICES</name>

<original_requirement>22236086</original_requirement>

</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>

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

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

</budget>

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

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

</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-type code="D">Disbursement</transaction-type>

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

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

<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-type code="D">Disbursement</transaction-type>

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

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

<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>