Alpha version

Please note that the Datastore is currently in its first release. Therefore, data queries may sometimes result in unexpected outputs. In particualar, invalid publisher data has been known to cause problems when importing data into the Datastore.

If you receive any unexpected results, please let us know: support@iatistandard.org We appreciate your understanding, and invite contributions to the codebase.

API

Available data

IATI activity data is available in the following formats:

Technical formats

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

recipient-country

Returns activities where the country contained within a recipient-country element matches a specified ISO country code.

Parameters:
@recipient-country: 2-digit ISO country code which appears on the country codelist
Example API call:
/api/1/access/activity.xml?recipient-country=SS

recipient-region

Returns activities where the contained within with a recipient-region element matches a specified DAC region code.

Parameters:
@recipient-region: 3-digit DAC region code which appears on the region codelist
Example API call:
/api/1/access/activity.xml?recipient-region=298

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:
/api/1/access/activity.xml?reporting-org=NL-KVK-41177206

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<http://iatistandard.org/201/codelists/OrganisationType/>`__
Example API call:
/api/1/access/activity.xml?reporting-org.type=10

sector

Returns activities where the value contained within a sector element matches a specified DAC sector code.

Parameters:
@sector: 5-digit DAC sector code which appears on the sector codelist
Example API call:
/api/1/access/activity.xml?sector=11110

policy-marker

The IATI Tech team have uncovered issues with this filter (‘500 internal server error’). `This issue has been logged <https://github.com/IATI/iati-datastore/issues/237>`__ and we will endeavour to resolve this shortly.

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<http://iatistandard.org/201/codelists/PolicyMarker/>`__
Example API call:
/api/1/access/activity.xml?policy-marker=1

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:
/api/1/access/activity.xml?participating-org.role=1

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:
/api/1/access/activity.xml?transaction=15458

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 issuing who provided transaction funds
Example API call:
/api/1/access/activity.xml?transaction_provider-org=GB-1

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 issuing who received transaction funds
Example API call:
/api/1/access/activity.xml?transaction_receiver-org=GB-CHC-1108464

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:
/api/1/access/activity.xml?registry-dataset=dfid-af

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-1&recipient-country=CD This would respond with all the DFID (GB-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-1&recipient-country=CD|UG This would return activities for DFID (GB-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 on a ‘page’ can be set using the limit parameter.

Parameters:
@limit: Maximum number of activities to be returned
Example API call:
/api/1/access/activity.xml?limit=100

The default behaviour is 50. Trying to fetch more than about 1000 activities with this this call is likely to result in an error.

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-1&stream=True This will return all the DFID transactions data as CSV.

/api/1/access/activity.xml?reporting-org.ref=GB-1&stream=True This will return all the DFID transactions data as XML.

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.