Publisher Endpoints

Publisher Endpoints

  1. List of Publishers
  2. Accessing Metadata of the Publisher
  3. Creating a new Publisher
  4. Updating a Publisher
  5. Patch a Publisher
  6. Delete a Publisher


1. List of Publishers

Return a list of the names of the site’s publisher. When the authorisation header is provided and the user has sysadmin privileges, the call also returns organisations with Pending status.

Endpoint: /organization_list

Method: GET

Authorisation: optional.

Parameters:

  • sort (string) (optional) – sorting of the search results. Default: “title asc” string of field name and sort-order. The allowed fields are ‘name’, ‘package_count’ and ‘title’
  • limit (int) (optional) – the maximum number of organisations returned. Default: 1200 when all_fields=false and 25 when all_fields=true. It's not recommended to use all_fields=true (use organization_show instead)
  • offset (int) (optional) – when limit is given, the offset to start returning organisations from
  • organizations (list of strings) (optional) – a list of names of the groups to return, if given only groups whose names are in this list will be returned
  • all_fields (bool) (optional) – return publisher dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the packages property for each group is deprecated, but there is a count of the packages in the package_count property. Default: False
  • include_dataset_count (bool) (optional) – if all_fields, include the full package_count. Default: True
  • include_extras (bool) (optional) – if all_fields, include the organisation extra fields. Default: False
  • include_tags (bool) (optional) – if all_fields, include the organisation tags. Default: False
  • include_groups (bool) (optional) – if all_fields, include the organisations the organisations are in. Default: False
  • include_users (bool) (optional) – if all_fields, include the organisation users. Default: False

Examples:


2. Accessing Metadata of the Publisher

Return the details of a publisher. When the authorisation header and include_datasets parameter are provided, the call also returns private datasets.

Endpoint: /organization_show

Method: GET

Authorisation: optional.

Parameters:

  • id (string) (required)(optional) – the id or name of the publisher
  • include_datasets (bool) (optional) – include a truncated list of the org’s datasets. Default: False
  • include_dataset_count (bool)(optional) – include the full dataset_count. Default: True
  • include_extras (bool) (optional) – include the publisher’s extra fields. Default: True
  • include_users (bool) (optional) – include the publisher’s users. Default: True
  • include_groups (bool) (optional) – include the publisher’s sub groups. Default: True
  • include_tags (bool) (optional) – include the publisher’s tags. Default: True
  • include_followers (bool) (optional) – include the publisher’s number of followers. Default: True

Examples:


3. Creating a new Publisher

Create a new organisation. You must be authorised to create organisations. Note: All newly created publishers will be in pending state until sysadmin approves.

Endpoint: /organization_create

Method: POST

Authorisation: required.

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

Parameters:

  • name (string) (required) – the name of the organisation, a string between 2 and 100 characters long, containing only lowercase alphanumeric characters, - and _
  • publisher_iati_id (string)(required) - IATI publisher id
  • title (string) (required) – the title of the organisation
  • publisher_source_type (string) (required) - Either “primary_source” or “secondary_source”
  • state (string) (required) - State should be always “approval_needed”
  • publisher_contact (string) (required) - Email address of the publisher
  • publisher_description (string) (optional) – the description of the publisher
  • license_id (string) (optional) - license_id can be obtained from here: https://iatiregistry.org/api/action/license_list.
  • image_display_url b– the URL to an image to be displayed on the publisher’s page
  • publisher_organization_type (string) (required) – Type of publisher. The value can be any of the below. E.g. publisher_organization_type=”22”
    • ('80', 'Academic, Training and Research'),
    • ('60', 'Foundation'),
    • ('10', 'Government'),
    • ('21', 'International NGO'),
    • ('40', 'Multilateral'),
    • ('22', 'National NGO'),
    • ('15', 'Other Public Sector'),
    • ('70', 'Private Sector'),
    • ('30', 'Public Private Partnership'),
    • ('23', 'Regional NGO')
  • packages (list of dictionaries) – the datasets (packages) that belong to the organisation, a list of dictionaries each with keys 'name' (string, the id or name of the dataset) and optionally 'title' (string, the title of the dataset)
  • users (list of dictionaries) – the users that belong to the organisation, a list of dictionaries each with key 'name' (string, the id or name of the user) and optionally 'capacity' (string, the capacity in which the user is a member of the organisation) Capacity can be either of “admin”, “member” or “editor”
  • publisher_country (string) (optional) - Publisher country code
  • publisher_ur (string) (optional) - External url for your publisher website
  • publisher_contact_email (string) (optional) - Contact address for publisher
  • publisher_implementation_schedule (string) (optional) - URL address of the Implementation Schedule
  • publisher_agencies (string) (optional) - Which organisations/agencies does your IATI data cover? (What % of your total development flows does this cover? What is missing?)
  • publisher_timeliness (string) (optional) - How soon after data is captured and available internally will data be published?
  • publisher_frequency_select (string) (optional) - How often is IATI data refreshed?. Either of these values monthly or quarterly or six_monthly or annually or lt_annually
  • publisher_frequency (string) (optional) - Any extra information regarding publisher frequency
  • publisher_units (string) (optional) - How is an activity defined e.g. projects and programmes, or some other structure? Do you have multi-tiered project structures e.g. projects and sub-projects or components? At which level/s do you intend to publish details?)
  • publisher_segmentation (string) (optional) - IATI data published in separate files per country or region?
  • publisher_refs (string) (optional) - Links to guides, explanations, codelists on the publisher's own site that clarify their data.
  • publisher_field_exclusions (string) (optional) - What fields recommended in the standard do you never use - and for what reason
  • publisher_record_exclusions (string) (optional) - What are your policies for excluding particular activities, or parts of an activity's data?
  • publisher_thresholds (string) (optional) - What are the thresholds below which data or whole activities are not published?
  • publisher_constraints (string) (optional) - Other policies or circumstances that restrict your full compliance with the standard
  • publisher_data_quality (string) (optional) - Publisher's comment on the status and accuracy of the data - audited/verified, operational/sub to change, etc.
  • publisher_ui (string) (optional) - Will IATI data be accessible for end users through an existing or a new user interface on your website?
  • publisher_ui_url (string) (optional) - If available, please provide the full URL to the website where your IATI data is accessible

Examples:

  • Case 1: Create a publisher called “my-test-publisher” (My Test Publisher) whose status is Pending for approval.

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

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

payload = { "name": "my-test-publisher", "publisher_iati_id": "XD-DAC-6-5", "title": "My Test Publisher", "publisher_contact_email": "[email protected]", "license_id": "odc-pddl", "publisher_organization_type": "80", "state": "approval_needed" }

  • Case 2: Create a publisher called “my-test-publisher-2” (My Test Publisher 2) and add users with respective capacity to the publisher.

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

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

payload = { "name": "my-test-publisher-2", "publisher_iati_id": "XDM-DAC-6-5", "title": "My Test Publisher 2", "publisher_contact_email": "[email protected]", "license_id": "odc-pddl", "publisher_organization_type": "80", "state": "approval_needed", "users": [ { "name": "swaroop", "capacity": "member" } ] }


4. Updating a Publisher

Update an organisation. You must be authorised to edit the organisation.

The difference between the organization_update and organization_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: /organization_update

Method: POST

Authorisation: required.

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

Parameters:

  • id (string) (required) – the name or id of the organisation to update
  • For further parameters see organization_create()

Examples:

  • Case 1: Lets update “publisher_organization_type” from 80 to 22 for the publisher “my-test-publisher-3”. Note: It's recommended to use organization_update along with organization_show.

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

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

payload = {'publisher_iati_id': 'XDMD-DAC-6-5', 'description': '', 'publisher_organization_type': '22', 'image_display_url': '', 'package_count': 0, 'title': 'My Test Publisher 3', 'is_organization': True, 'state': 'approval_needed', 'publisher_contact_email': '[email protected]', 'image_url': '', 'groups': [], 'type': 'organization', 'license_id': 'odc-pddl', 'users': [{'capacity': 'admin', 'name': 'admin'}, {'capacity': 'member', 'name': 'swaroop'}], 'num_followers': 0, 'id': '71a7698a-b14f-43c2-b113-b8eb884da7af', 'tags': [], 'name': 'my-test-publisher-3'}


5. Patch a Publisher

Patch an organisation.

The difference between the organization_update and organization_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: /organization_patch

Method: POST

Authorisation: required.

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

Parameters:

  • id (string) (required) – the name or id of the organisation to update
  • For further parameters see organization_create()

Examples:

  • Case 1: Lets patch “license_id” from odc-pddl to odc-by for the publisher “my-test-publisher-3”

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

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

payload = {id: '71a7698a-b14f-43c2-b113-b8eb884da7af', ‘license_id’: ‘odc-by’ }

  • Case 2: Let's add “publisher_country” to the publisher “my-test-publisher-3”

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

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

payload = {id: '71a7698a-b14f-43c2-b113-b8eb884da7af',”publisher_country”: “ie” }


6. Delete a Publisher

Patch an organisation. You must be authorised to delete the organization and no datasets should belong to the organisation.

The difference between the organization_update and organization_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: /organization_delete

Method: POST

Authorisation: required.

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

Parameters:

  • id (string) (required) – the name or id of the organisation to delete

Examples:

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

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

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

payload = {id: '71a7698a-b14f-43c2-b113-b8eb884da7af' }