API¶
Contents
Available data¶
IATI activity data is available in the following formats:
Technical formats¶
XML - using endpoint: /api/1/access/activity.xml
JSON - using endpoint: /api/1/access/activity.json
CSV formats¶
List of activities /api/1/access/activity.csv
Activities by sector /api/1/access/activity/by_sector.csv
Activities by country /api/1/access/activity/by_country.csv
List of transactions /api/1/access/transaction.csv
Transactions by sector /api/1/access/transaction/by_sector.csv
Transactions by country /api/1/access/transaction/by_country.csv
List of budgets /api/1/access/budget.csv
Budgets by sector /api/1/access/budget/by_sector.csv
Budgets by country /api/1/access/budget/by_country.csv
Filtering¶
The following filters are available, which enable you to construct a query for the data that you are looking for.
Available filters¶
iati-identifier¶
Returns activities matching the specified IATI Identifier element. In practice this should return one activity, as each activity should contain a IATI Identifier value.
- Parameters:
@iati-identifier: String denoting an individual IATI activity
- Example API call:
/api/1/access/activity.xml?iati-identifier=NL-KVK-41177206-C-002350
title¶
Returns activities with any Title element containing the specified text (case-insensitive). NB: the Datastore currently only captures one title per activity.
- Parameters:
@title: String containing part or all of the title of the target activity.
- Example API call:
description¶
Returns activities with any Description element containing the specified text (case-insensitive). NB: the Datastore currently only captures one description per activity.
- Parameters:
@description: String containing part or all of the description of the target activity.
- Example API call:
activity-status¶
Returns activities matching the specified activity-status element.
- Parameters:
@activity-status: String containing the requested status.
- Example API call:
recipient-country¶
Returns activities where the country contained within a recipient-country element or any transaction/recipient-country matches a specified ISO country code.
- Parameters:
@recipient-country: 2-digit ISO country code which appears on the country codelist
- Example API call:
recipient-region¶
Returns activities where the contained within with a recipient-region element or any transaction/recipient-region matches a specified DAC region code.
- Parameters:
@recipient-region: 3-digit DAC region code which appears on the region codelist
- Example API call:
reporting-org¶
Returns activities where the value contained within a reporting-org element matches your specified Organisation identifier string.
- Parameters:
@reporting-org: Organisation identifier string.
- Example API call:
reporting-org.type¶
Returns activities where the value contained within a reporting-org @type attribute matches your specified value.
- Parameters:
@recipient-org.type: 2-digit value which appears on the organisation type codelist
- Example API call:
sector¶
Returns activities where the value contained within a sector element or any transaction/sector matches a specified DAC sector code.
- Parameters:
@sector: 5-digit DAC sector code which appears on the sector codelist
- Example API call:
policy-marker¶
Returns activities containing a policy-marker element which matches a your specified policy-marker value.
- Parameters:
@policy-marker: 1-digit value which appears on the policy marker codelist
- Example API call:
policy-marker.significance¶
Returns activities containing a policy-marker element which matches a your specified policy-significance value.
- Parameters:
@policy-marker.significance: 1-digit value which appears on the policy significance codelist
- Example API call:
participating-org¶
Returns activities where the the value contained within the participating-org element matches your specified participating-org identification string.
- Parameters:
@participating-org: Identification string for the organisation who is participating
- Example API call:
/api/1/access/activity.xml?participating-org=NL-KVK-41177206
participating-org.role¶
Returns activities where the value contained within the participating-org @role attribute matches your specified value.
- Parameters:
@participating-org.role: 1-digit value which appears on the organisation role codelist
- Example API call:
transaction¶
Returns activities containing at least one transaction element where the @ref attribute matches your given string.
- Parameters:
@transaction: String denoting an transaction @ref attribute
- Example API call:
transaction_provider-org¶
Returns activities containing at least one transaction element where the provider-org element matches your specified organisation identifier string.
- Parameters:
@transaction_provider-org: Organisation identifier string for the organisation who provided transaction funds
- Example API call:
/api/1/access/activity.xml?transaction_provider-org=GB-GOV-1
transaction_provider-org.text¶
Returns activities containing at least one transaction element where the name of the provider-org matches your specified string.
- Parameters:
@transaction_provider-org.text: `Name of the organisation who provided transaction funds
- Example API call:
/api/1/access/activity.xml?transaction_provider-org.text=Oxfam
transaction_provider-org.type¶
Returns activities containing at least one transaction element where funds have been provided by an organisation with the specified Organisation Type codelist.
- Parameters:
@transaction_receiver-org.type: Organisation type string for the organisation who provided transaction funds
- Example API call:
transaction_provider-org.provider-activity-id¶
Returns activities containing at least one transaction element where the provider-activity-id element matches a specified IATI activity identifier string.
- Parameters:
@transaction_provider-org.provider-activity-id: String denoting an IATI activity identifier
- Example API call:
/api/1/access/activity.xml?transaction_provider-org.provider-activity-id=GB-1-202505
transaction_receiver-org¶
Returns activities containing at least one transaction element where funds have been transferred to an organisation with the specified Organisation identifier string.
- Parameters:
@transaction_receiver-org: Organisation identifier string for the organisation who received transaction funds
- Example API call:
/api/1/access/activity.xml?transaction_receiver-org=GB-CHC-1108464
transaction_receiver-org.text¶
Returns activities containing at least one transaction element where the name of the receiver-org matches your specified string.
- Parameters:
@transaction_receiver-org.text: `Name of the organisation who received transaction funds
- Example API call:
/api/1/access/activity.xml?transaction_receiver-org.text=Oxfam
transaction_receiver-org.type¶
Returns activities containing at least one transaction element where funds have been transferred to an organisation with the specified Organisation Type codelist.
- Parameters:
@transaction_receiver-org.type: Organisation type string for the organisation who received transaction funds
- Example API call:
transaction_receiver-org.receiver-activity-id¶
Returns activities containing at least one transaction element where the receiver-org element has an @receiver-activity-id attribute which matches the specified IATI activity identifier string.
- Parameters:
@transaction_receiver-org.receiver-activity-id: String denoting an IATI activity identifier
- Example API call:
/api/1/access/activity.xml?transaction_receiver-org.receiver-activity-id=GB-CHC-1099776-B8
start-date¶
Returns activities where the date with in @activity-date element (with type equivalent to start-planned or start-actual) of an activity is less or greater than your specified query.
This API element has two sub-elements: to return activities less than your specified date, use start-date__lt, or to return activities less than your specified date use start-date__gt
- Parameters:
@start-date: ISO format date (YYYY-MM-DD).
- Example API calls:
/api/1/access/activity.xml?start-date__lt=2015-01-01 /api/1/access/activity.xml?start-date__gt=2015-01-01
end-date¶
Returns activities where the @activity-date element (with type equivalent to end-planned or end-actual) of an activity is less or greater than your specified query.
This API element has two sub-elements: to return activities less than your specified date, use end-date__lt, or to return activities less than your specified date use end-date__gt
- Parameters:
@end-date: ISO format date (YYYY-MM-DD).
- Example API call:
/api/1/access/activity.xml?end-date__lt=2015-01-01 /api/1/access/activity.xml?end-date__gt=2015-01-01
last-change¶
Returns activities where the observed last change the of an activity is less or greater than your specified query.
This differs from the last-updated-datetime. filter, as the last-date filter is based on when the Datastore process observed a change in data. The last-updated-datetime. filter returns data based on the @last-updated-datetime attribute contained within the data itself.
This API element has two sub-elements: to return activities less than your specified date, use last-change__lt, or to return activities less than your specified date use last-change__gt
- Parameters:
@last-change: ISO format date (YYYY-MM-DD).
- Example API calls:
/api/1/access/activity.xml?last-change__lt=2009-01-01 /api/1/access/activity.xml?last-change__gt=2009-01-01
last-updated-datetime¶
Returns activities where the @last-updated-datetime attribute of an activity is less or greater than your specified query.
This differs from the last-change. filter, as the last-updated-datetime filter returns data based on the @last-updated-datetime attribute contained within the data itself. The last-change. filter is based on when the Datastore process observed a change in data.
This API element has two sub-elements: to return activities less than your specified date, use last-updated-datetime__lt, or to return activities less than your specified date use last-updated-datetime__gt
- Parameters:
@last-updated-datetime: ISO format date (YYYY-MM-DD).
- Example API calls:
/api/1/access/activity.xml?last-updated-datetime__lt=2015-01-01 /api/1/access/activity.xml?last-updated-datetime__gt=2010-01-01
registry-dataset¶
Returns activities contained within a specified registry dataset.
- Parameters:
@registry-dataset: string name of the specified registry dataset
- Example API call:
Combining filters¶
All of the above filters can be combined using the & character. The resulting query will return activities which match all of the specified criteria.
- Example API call:
/api/1/access/activity.xml?reporting-org=GB-GOV-1&recipient-country=CD This would respond with all the FCDO (GB-GOV-1) data for the Democratic Republic of Congo (CD).
Complex Filtering¶
Each individual filter can be filtered for alternate values using the | character.
- Example API call:
/api/1/access/activity.xml?reporting-org=GB-GOV-1&recipient-country=CD|UG This would return activities for FCDO (GB-GOV-1) where the recipient-country is either Democratic Republic of Congo (CD) OR Uganda (UG)
Results options¶
Paging through results¶
By default, data is returned from the first result matching your API query. Incrementing the offset parameter will return data beginning at the nth activity.
/api/1/access/activity.xml This will return all activities, beginning with the first result.
/api/1/access/activity.xml?offset=20 This will return all activities, beginning with the 20th result.
The datastore will respond with an HTTP 404 when you have asked for the page beyond the last page.
Setting a number of maximum results¶
The maximum number of results to be returned per ‘page’ can be set using the limit parameter.
- Parameters:
@limit: Maximum number of activities to be returned
- Example API call:
The default behaviour is 50; the maximum is 1000. Trying to fetch more than about 1000 activities with this call will result in an error. See the following section if you need to retrieve all results at once.
Getting all the results at once¶
The CSV and XML formats support returning all results at once in a ‘stream’. To request all available results, add stream=True to your parameters.
- Example API calls:
/api/1/access/transaction.csv?reporting-org.ref=GB-GOV-1&stream=True This will return all the FCDO transactions data as CSV.
/api/1/access/activity.xml?reporting-org.ref=GB-GOV-1&stream=True This will return all the FCDO activity data as XML.
“Unwrapping” the query information¶
By default, XML and JSON responses include status and query data. To exclude this information from the response add unwrap=True to your parameters. This will return something closer to valid IATI data.
- Example API calls:
/api/1/access/activity/?unwrap=True This will return all activites as JSON, unwrapped.
/api/1/access/activity.xml?unwrap=True This will return all activites as XML, unwrapped.
Checking the Data¶
General information is available on datasets contained within the datastore, as well as datasets where errors were encountered during the process of fetching and parsing. Full information on this is available on the General API and Error API documentation.
Source code¶
The IATI Datastore is still under development. You can browse the source code on GitHub and report bugs on Github using the ‘Issues’ features.