Package/Dataset Endpoints

API Documentation

Package/Dataset Endpoints

  1. Accessing/List Of All IATI Registry Datasets
  2. Searching IATI Datasets And Accessing Datasets Metadata
  3. Accessing Metadata of the Dataset and its Resource
  4. Creating a Dataset
  5. Updating a Dataset
  6. Patch a Dataset
  7. Delete a Dataset


1. Accessing/List Of All IATI Registry Datasets

Returns a list of the names of the IATI Registry datasets (packages). The default number of items returned is 1200. When the authorisation header is provided, the call also returns all the private datasets that the user has access to.

Endpoint: /package_list

Method: GET

Authorisation: optional.

Parameters:

  • limit (int) (optional) – if given, the list of datasets will be broken into pages of at most limit datasets per page and only one page will be returned at a time
  • offset (int) (optional) – when the limit is given, the offset to start returning packages from

Examples:


2. Searching IATI Datasets And Accessing Datasets Metadata

Searches for packages satisfying a given search criteria. This action accepts Solr search query parameters (details below), and returns a dictionary of results, including dictized datasets that match the search criteria, a search count and also facet information.

Endpoint: /package_search

Method: GET

Authorisation: not required.

Solr Parameters: please read the Solr Documentation.

Parameters:

  • q (string) (optional) – the Solr query. Default: "*:*"
  • fq (string) (optional) – any filter queries to apply. Please see below examples
  • fq_list (list of strings) (optional) – additional filter queries to apply
  • sort (string) (optional) – sorting of the search results. Default: 'score desc, metadata_modified desc'. As per the Solr documentation, this is a comma-separated string of field names and sort-orderings
  • rows (int) (optional) – the maximum number of matching rows (datasets) to return. Default: 10, upper limit: 1000
  • start (int) (optional) – the offset in the complete result for where the set of returned datasets should begin
  • facet (string) (optional) – whether to enable faceted results. Default: True
  • facet.mincount (int) (optional) – the minimum counts for facet fields should be included in the results
  • facet.limit (int) (optional) – the maximum number of values the facet fields return. A negative value means unlimited. This can be set instance-wide with the search.facets.limit config option. Default is 50
  • facet.field (list of strings) (optional) – the fields to facet upon. Default empty. If empty, then the returned facet information is empty
  • include_drafts (bool) (optional) – if True, draft datasets will be included in the results. A user will only be returned their own draft datasets. Note: authorisation with API token required for this to be true
  • include_private (bool) (optional) – if True, private datasets will be included in the results. Only private datasets from the user’s organisations will be returned. Note: authorisation with API token required for this to be true

Examples:


3. Accessing Metadata of the Dataset and its Resource

Return the metadata of a dataset (package) and its resources.

Endpoint: /package_show

Method: GET

Authorisation: not required.

Parameters:

  • id (string)(required) – the id or name of the dataset
  • use_default_schema (bool)(optional) – use default package schema instead of a custom schema defined with an IDatasetForm plugin. Default: False
  • include_tracking (bool)(optional) – add tracking information to dataset and resources. Default: False

Examples:


4. Creating a Dataset

Create a new dataset (package). You must be authorised to create new datasets. If you specify any publisher for the new dataset, you must also be authorised to edit these publishers.

Endpoint: /package_create

Method: POST

Authorisation: required.

Additional request headers: ('Content-Type', 'application/json; charset=utf-8')

Parameters:

  • name (string) (required) – the name of the new dataset, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, - and _, e.g. 'warandpeace'
  • title (string) (required) – the title of the dataset. Default: same as name
  • private (bool) (required) – If True creates a private dataset
  • filetype (string) (required) - File type should be either “activity” or “organization”
  • owner_org (string) (required) – the id of the dataset’s owning organisation, see organization_list() for available values. This parameter can be made optional if the config option ckan.auth.create_unowned_dataset is set to True
  • author (string) (optional) – the name of the dataset’s author
  • author_email (string) (optional) – the email address of the dataset’s author
  • maintainer (string) (optional) – the name of the dataset’s maintainer
  • maintainer_email (string) (optional)– the email address of the dataset’s maintainer
  • notes (string) (optional) – a description of the dataset
  • url (string) (optional) – a URL for the dataset’s source
  • resources (list of resource dictionaries) – the dataset’s resources, see resource_create() for the format of resource dictionaries (optional). One IATI dataset can have only one resource
  • extras (list of dataset extra dictionaries)(optional) – the dataset’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to datasets, each extra dictionary should have keys 'key' (a string), 'value' (a string)
  • secondar_publisher (string) (optional) - The publisher this dataset is published on behalf of
  • country (string) (optional) - Recipient country code
  • tags (list of tag dictionaries) (optional)– the dataset’s tags, see tag_create() for the format of tag dictionaries
  • iati_version (string) (optional) - IATI Standard Version
  • activity_count (string) (optional) - Count of the number of activities reported
  • language (string) (optional) - The ISO 639-1 code for the default language of the file (e.g. 'en')

Examples:

  • Case 1: Create an activity dataset with publisher “my-test-publisher-3”.

Endpoint: https://iatiregistry.org/api/action/package_create

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = { "name": "my-test-publisher-3-activity", "title": "My test package", "private": False, "filetype": "activity",

"owner_org": "71a7698a-b14f-43c2-b113-b8eb884da7af", "resources": [ { "url": "https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml", "format":"IATI-XML", } ] }

  • Case 2: Create an organisation dataset with publisher “my-test-publisher-3” with country_code “ie”.

Endpoint: https://iatiregistry.org/api/action/package_create

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = { "name": "my-test-publisher-3-org", "title": "My test package org", "private": False, "filetype": "organisation",

"owner_org": "71a7698a-b14f-43c2-b113-b8eb884da7af", "country": "ie", "resources": [ { "url": "https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml", "format":"IATI-XML", } ] }


5. Updating a Dataset

Update a dataset (package). You must be authorised to edit the dataset and the groups that it belongs to. It is recommended to call package_show(), make the desired changes to the result, and then call package_update() with it.

The difference between the update and patch methods is that the patch will perform an update of the provided parameters, while leaving all other parameters unchanged, whereas the update methods deletes all parameters not explicitly provided in the data_dict.

Endpoint: /package_update

Method: POST

Authorisation: required.

Additional request headers: ('Content-Type', 'application/json; charset=utf-8')

Parameters:

  • id (string)(required) – the id of the dataset
  • For further parameters see package_create()

Examples:

  • Case 1: Let's update the title of the dataset “my-test-publisher-3-org" from “My test package org” to “My test new title org”. Note: It’s recommended to use package_update along with package_show.

Endpoint: https://iatiregistry.org/api/action/package_update

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = {'license_title': 'Open Data Commons Attribution Licence', 'maintainer': None, 'relationships_as_object': [], 'private': False, 'maintainer_email': None, 'num_tags': 0, 'id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'metadata_created': '2021-01-19T23:25:07.399494', 'metadata_modified': '2021-01-19T23:25:09.999163', 'author': None, 'author_email': None, 'state': 'active', 'version': None, 'creator_user_id': 'a6f09bb2-88d2-4219-80a2-9b606bdf4ac3', 'type': 'dataset', 'resources': [{'mimetype': '', 'cache_url': None, 'hash': '9148c7e5645290213a13897583d1c5c40c9798e6', 'description': None, 'metadata_modified': '2021-01-19T23:25:10.010376', 'cache_last_updated': None, 'url': 'https://aidstream.s3.us-west-2.amazonaws.com/xml/acfspain-ge.xml', 'name': None, 'format': 'IATI-XML', 'package_id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'created': '2021-01-19T23:25:07.402246', 'state': 'active', 'mimetype_inner': None, 'last_modified': None, 'position': 0, 'url_type': None, 'id': 'c13afd1f-91d6-4ee6-921b-4ec405b0a774', 'resource_type': None, 'size': 4417}], 'num_resources': 1, 'tags': [], 'groups': [], 'license_id': 'odc-by', 'relationships_as_subject': [], 'organization': {'description': '', 'created': '2021-01-19T22:50:46.969280', 'title': 'My Test Publisher 3', 'name': 'my-test-publisher-3', 'is_organization': True, 'state': 'active', 'image_url': '', 'type': 'organization', 'id': '71a7698a-b14f-43c2-b113-b8eb884da7af', 'approval_status': 'approved'}, 'name': 'my-test-publisher-3-org', 'isopen': True, 'url': None, 'notes': None, 'owner_org': '71a7698a-b14f-43c2-b113-b8eb884da7af', 'license_url': 'http://www.opendefinition.org/licenses/odc-by', 'title': 'My test new title org'}


6. Patch a Dataset

You are able to partially update and/or create resources with package_patch. If you are updating existing resources be sure to provide the resource id. Existing resources excluded from the package_patch data_dict will be removed. Resources in the package data_dict without an id will be treated as new resources and will be added. New resources added with the patch method do not create the default views. You must be authorised to edit the dataset and the groups that it belongs to.

The difference between the update and patch methods is that the patch will perform an update of the provided parameters, while leaving all other parameters unchanged, whereas the update methods deletes all parameters not explicitly provided in the data_dict.

Endpoint: /package_patch

Method: POST

Authorisation: required.

Additional request headers: ('Content-Type', 'application/json; charset=utf-8')

Parameters:

  • id (string)(required) – the id of the dataset
  • For further parameters see package_create()

Examples:

  • Case 1: Let's patch the dataset title to “My test new title org“ to “My test patch title” fo the dataset “my-test-publisher-3-org”

Endpoint: https://iatiregistry.org/api/action/package_patch

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload ={'id': '4008f48f-b9e1-4c2e-8e47-3928bf66a056', 'title': 'My test patch title'}


7. Delete a Dataset

Delete datasets. This makes the dataset disappear from all web & API views, apart from the trash. You must be authorised to delete the dataset.

Endpoint: /package_delete

Method: POST

Authorisation: required.

Additional request headers: ('Content-Type', 'application/json; charset=utf-8')

Parameters:

  • id (string)(required) – the id of the dataset

Examples:

  • Case 1: Let's delete the dataset “my-test-publisher-3-activity”.

Endpoint: https://iatiregistry.org/api/action/package_delete

headers = {"Content-Type": "application/json; charset=utf-8", "Authorization":”XXX”}

payload = {'id': 'e6471512-d3e9-4999-a692-82ae1893e346'}