API guide

This section documents CKAN APIs, for developers who want to write code thatinteracts with CKAN sites and their data.

CKAN’sAction API is a powerful, RPC-style API that exposes all of CKAN’score features to API clients. All of a CKAN website’s core functionality(everything you can do with the web interface and more) can be used by externalcode that calls the CKAN API. For example, using the CKAN API your app can:

Note

CKAN’s FileStore and DataStore have their own APIs, see:

Note

For documentation of CKAN’s legacy API’s, seeLegacy APIs.

Note

On early CKAN versions, datasets were called “packages” and this namehas stuck in some places, specially internally and on API calls. Package hasexactly the same meaning as “dataset”.

Making an API request

To call the CKAN API, post a JSON dictionary in an HTTP POST request to one ofCKAN APIs URLs. The parameters for the API function should be given in theJSON dictionary. CKAN will also return its response in a JSON dictionary.

One way to post a JSON dictionary to a URL is using the command-lineclientCurl. For example, to get a list of the namesof all the datasets in thedata-explorer group on demo.ckan.org, installcurl and then call thegroup_list API function by running this commandin a terminal:

curlhttps://demo.ckan.org/api/3/action/group_list

The response from CKAN will look like this:

{"help":"...","result":["data-explorer","department-of-ricky","geo-examples","geothermal-data","reykjavik","skeenawild-conservation-trust"],"success":true}

The response is a JSON dictionary with three keys:

  1. "success":true orfalse.

    The API aims to always return200OK as the status code of its HTTPresponse, whether there were errors with the request or not, so it’simportant to always check the value of the"success" key in the responsedictionary and (if success isfalse) check the value of the"error"key.

Note

If there are major formatting problems with a request to the API, CKANmay still return an HTTP response with a409,400 or500status code (in increasing order of severity). In future CKAN versionswe intend to remove these responses, and instead send a200OKresponse and use the"success" and"error" items.

  1. "result": the returned result from the function you called. The typeand value of the result depend on which function you called. In the case ofthegroup_list function it’s a list of strings, the names of all thedatasets that belong to the group.

    If there was an error responding to your request, the dictionary willcontain an"error" key with details of the error instead of the"result" key. A response dictionary containing an error will look likethis:

    {"help":"Creates a package","success":false,"error":{"message":"Access denied","__type":"Authorization Error"}}

  2. "help": the documentation string for the function you called.

The same HTTP request can be made using Python’s standardurllib2 module,with this Python code:

#!/usr/bin/env pythonimporturllib2importurllibimportjsonimportpprint# Make the HTTP request.response=urllib2.urlopen('http://demo.ckan.org/api/3/action/group_list',data_string)assertresponse.code==200# Use the json module to load CKAN's response into a dictionary.response_dict=json.loads(response.read())# Check the contents of the response.assertresponse_dict['success']isTrueresult=response_dict['result']pprint.pprint(result)

Example: Importing datasets with the CKAN API

You can add datasets using CKAN’s web interface, but when importing manydatasets it’s usually more efficient to automate the process in some way. Inthis example, we’ll show you how to use the CKAN API to write a Python scriptto import datasets into CKAN.

Todo

Make this script more interesting (eg. read data from a CSV file), and allput the script in a .py file somewhere with tests and import it here.

#!/usr/bin/env pythonimporturllib2importurllibimportjsonimportpprint# Put the details of the dataset we're going to create into a dict.dataset_dict={'name':'my_dataset_name','notes':'A long description of my dataset','owner_org':'org_id_or_name'}# Use the json module to dump the dictionary to a string for posting.data_string=urllib.quote(json.dumps(dataset_dict))# We'll use the package_create function to create a new dataset.request=urllib2.Request('http://www.my_ckan_site.com/api/action/package_create')# Creating a dataset requires an authorization header.# Replace *** with your API key, from your user account on the CKAN site# that you're creating the dataset on.request.add_header('Authorization','***')# Make the HTTP request.response=urllib2.urlopen(request,data_string)assertresponse.code==200# Use the json module to load CKAN's response into a dictionary.response_dict=json.loads(response.read())assertresponse_dict['success']isTrue# package_create returns the created package as its result.created_package=response_dict['result']pprint.pprint(created_package)

For more examples, seeAPI Examples.

API versions

The CKAN APIs are versioned. If you make a request to an API URL without aversion number, CKAN will choose the latest version of the API:

http://demo.ckan.org/api/action/package_list

Alternatively, you can specify the desired API version number in the URL thatyou request:

http://demo.ckan.org/api/3/action/package_list

Version 3 is currently the only version of the Action API.

We recommend that you specify the API version number in your requests, because thisensures that your API client will work across different sites running differentversion of CKAN (and will keep working on the same sites, when those sitesupgrade to new versions of CKAN). Because the latest version of the API maychange when a site is upgraded to a new version of CKAN, or may differ ondifferent sites running different versions of CKAN, the result of an APIrequest that doesn’t specify the API version number cannot be relied on.

Authentication and API tokens

Some API functions require authorization. The API uses the same authorizationfunctions and configuration as the web interface, so if a user is authorized todo something in the web interface they’ll be authorized to do it via the API aswell.

When calling an API function that requires authorization, you mustauthenticate yourself by providing an API token. Tokens areencrypted keys that can be generated manually from the UI (User Profile > Manage > API tokens)or via theapi_token_create() function. A user can create as many tokens as neededfor different uses, and revoke one or multiple tokens at any time. In addition, enablingtheexpire_api_token core plugin allows to define the expiration timestamp for a token.

Site maintainers can useAPI Token Settings to configure the token generation.

To provide your API token in an HTTP request, include it in anAuthorization header. (The name of the HTTP headercan be configured with the :ref:apitoken_header_name option in your CKANconfiguration file.)

For example, to ask whether or not you’re currently following the usermarkw on demo.ckan.org using curl, run this command:

curl -H "Authorization: XXX"  https://demo.ckan.org/api/3/action/am_following_user?id=markw

(ReplacingXXX with your API token.)

Or, to get the list of activities from your user dashboard on demo.ckan.org,run this Python code:

request=urllib2.Request('https://demo.ckan.org/api/3/action/dashboard_activity_list')request.add_header('Authorization','XXX')response_dict=json.loads(urllib2.urlopen(request,'{}').read())

GET-able API functions

Functions defined inckan.logic.action.get can also be called with an HTTPGET request. For example, to get the list of datasets (packages) fromdemo.ckan.org, open this URL in your browser:

http://demo.ckan.org/api/3/action/package_list

Or, to search for datasets (packages) matching the search queryspending,on demo.ckan.org, open this URL in your browser:

http://demo.ckan.org/api/3/action/package_search?q=spending

Tip

Browser plugins likeJSONView for FirefoxorChromewill format and color CKAN’s JSON response nicely in your browser.

The search query is given as a URL parameter?q=spending. MultipleURL parameters can be appended, separated by& characters, for exampleto get only the first 10 matching datasets open this URL:

http://demo.ckan.org/api/3/action/package_search?q=spending&rows=10

When an action requires a list of strings as the value of a parameter, thevalue can be sent by giving the parameter multiple times in the URL:

http://demo.ckan.org/api/3/action/term_translation_show?terms=russian&terms=romantic%20novel

JSONP support

To cater for scripts from other sites that wish to access the API, the data canbe returned in JSONP format, where the JSON data is ‘padded’ with a functioncall. The function is named in the ‘callback’ parameter. For example:

http://demo.ckan.org/api/3/action/package_show?id=adur_district_spending&callback=myfunction

Note

This only works for GET requests

API Examples

Tags (not in a vocabulary)

A list of all tags:

Top 10 tags used by datasets:

All datasets that have tag ‘economy’:

Tag Vocabularies

Top 10 tags and vocabulary tags used by datasets:

e.g. Facet:vocab_Topics means there is a vocabulary called Topics, and its top tags are listed under it.

A list of datasets using tag ‘education’ from vocabulary ‘Topics’:

Uploading a new version of a resource file

You can use theupload parameter of theresource_patch() function to upload anew version of a resource file. This requires amultipart/form-datarequest, with curl you can do this using the@file.csv:

curl-XPOST-H"Content-Type: multipart/form-data"-H"Authorization: XXXX"-F"id=<resource_id>"-F"upload=@updated_file.csv"https://demo.ckan.org/api/3/action/resource_patch

Action API reference

Note

If you call one of the action functions listed below and the functionraises an exception, the API will return a JSON dictionary with keys"success":false and an"error" key indicating the exceptionthat was raised.

For examplemember_list() (which returns alist of the members of a group) raisesNotFound ifthe group doesn’t exist. If you called it over the API, you’d get back aJSON dict like this:

{"success":false"error":{"__type":"Not Found Error","message":"Not found"},"help":"...",}

ckan.logic.action.get

API functions for searching for and getting data from CKAN.

ckan.logic.action.get.package_list(context:Context,data_dict:dict[str,Any])→Sequence[str]

Return a list of the names of the site’s datasets (packages).

Parameters:

  • limit (int) – if given, the list of datasets will be broken into pages ofat mostlimit datasets per page and only one page will be returnedat a time (optional)

  • offset (int) – whenlimit is given, the offset to startreturning packages from

Return type:

list of strings

ckan.logic.action.get.current_package_list_with_resources(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of the site’s datasets (packages) and their resources.

The list is sorted most-recently-modified first.

Parameters:

  • limit (int) – if given, the list of datasets will be broken into pages ofat mostlimit datasets per page and only one page will be returnedat a time (optional)

  • offset (int) – whenlimit is given, the offset to startreturning packages from

  • page (int) – whenlimit is given, which page to return,Deprecated: useoffset

Return type:

list of dictionaries

ckan.logic.action.get.member_list(context:Context,data_dict:dict[str,Any])→List[Tuple[Any,...]]

Return the members of a group.

The user must have permission to ‘get’ the group.

Parameters:

  • id (string) – the id or name of the group

  • object_type (string) – restrict the members returned to those of a given type,e.g.'user' or'package' (optional, default:None)

  • capacity (string) – restrict the members returned to those with a givencapacity, e.g.'member','editor','admin','public','private' (optional, default:None)

Return type:

list of (id, type, capacity) tuples

Raises:

ckan.logic.NotFound: if the group doesn’t exist

ckan.logic.action.get.package_collaborator_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of all collaborators for a given package.

Currently you must be an Admin on the package owner organization tomanage collaborators.

Note: This action requires the collaborators feature to be enabled withtheckan.auth.allow_dataset_collaborators configuration option.

Parameters:

  • id (string) – the id or name of the package

  • capacity (string) – (optional) If provided, only users with this capacity arereturned

Returns:

a list of collaborators, each a dict including the package anduser id, the capacity and the last modified date

Return type:

list of dictionaries

ckan.logic.action.get.package_collaborator_list_for_user(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of all package the user is a collaborator in

Note: This action requires the collaborators feature to be enabled withtheckan.auth.allow_dataset_collaborators configuration option.

Parameters:

  • id (string) – the id or name of the user

  • capacity (string) – (optional) If provided, only packages where the userhas this capacity are returned

Returns:

a list of packages, each a dict including the package id, thecapacity and the last modified date

Return type:

list of dictionaries

ckan.logic.action.get.group_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of the names of the site’s groups.

Parameters:

  • type (string) – the type of group to list (optional, default:'group'),See docs forIGroupForm

  • order_by (string) – the field to sort the list by, must be'name' or'packages' (optional, default:'name') Deprecated use sort.

  • sort (string) – sorting of the search results. Optional. Default:“title asc” string of field name and sort-order. The allowed fields are‘name’, ‘package_count’ and ‘title’

  • limit (int) – the maximum number of groups returned (optional)Default:1000 when all_fields=false unless set in site’sconfigurationckan.group_and_organization_list_maxDefault:25 when all_fields=true unless set in site’sconfigurationckan.group_and_organization_list_all_fields_max

  • offset (int) – whenlimit is given, the offset to startreturning groups from

  • groups (list ofstrings) – a list of names of the groups to return, if given onlygroups whose names are in this list will be returned (optional)

  • all_fields (bool) – return group dictionaries instead of just names. Onlycore fields are returned - get some more using the include_* options.Returning a list of packages is too expensive, so thepackagesproperty for each group is deprecated, but there is a count of thepackages in thepackage_count property.(optional, default:False)

  • include_dataset_count (bool) – if all_fields, include the full package_count(optional, default:True)

  • include_extras (bool) – if all_fields, include the group extra fields(optional, default:False)

  • include_groups (bool) – if all_fields, include the groups the groups are in(optional, default:False).

  • include_users (bool) – if all_fields, include the group users(optional, default:False).

Return type:

list of strings

ckan.logic.action.get.organization_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of the names of the site’s organizations.

Parameters:

  • type (string) – the type of organization to list (optional,default:'organization'),See docs forIGroupForm

  • order_by (string) – the field to sort the list by, must be'name' or'packages' (optional, default:'name') Deprecated use sort.

  • sort (string) – sorting of the search results. Optional. Default:“title asc” string of field name and sort-order. The allowed fields are‘name’, ‘package_count’ and ‘title’

  • limit (int) – the maximum number of organizations returned (optional)Default:1000 when all_fields=false unless set in site’sconfigurationckan.group_and_organization_list_maxDefault:25 when all_fields=true unless set in site’sconfigurationckan.group_and_organization_list_all_fields_max

  • offset (int) – whenlimit is given, the offset to startreturning organizations from

  • organizations (list ofstrings) – a list of names of the groups to return,if given only groups whose names are in this list will bereturned (optional)

  • all_fields (bool) – return group dictionaries instead of just names. Onlycore fields are returned - get some more using the include_* options.Returning a list of packages is too expensive, so thepackagesproperty for each group is deprecated, but there is a count of thepackages in thepackage_count property.(optional, default:False)

  • include_dataset_count (bool) – if all_fields, include the full package_count(optional, default:True)

  • include_extras (bool) – if all_fields, include the organization extra fields(optional, default:False)

  • include_groups (bool) – if all_fields, include the organizations theorganizations are in(optional, default:False)

  • include_users (bool) – if all_fields, include the organization users(optional, default:False).

Return type:

list of strings

ckan.logic.action.get.group_list_authz(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of groups that the user is authorized to edit.

Parameters:

  • available_only (bool) – remove the existing groups in the package(optional, default:False)

  • am_member (bool) – ifTrue return only the groups the logged-in user isa member of, otherwise return all groups that the user is authorized toedit (for example, sysadmin users are authorized to edit all groups)(optional, default:False)

Returns:

list of dictized groups that the user is authorized to edit

Return type:

list of dicts

ckan.logic.action.get.organization_list_for_user(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the organizations that the user has a given permission for.

Specifically it returns the list of organizations that the currentlyauthorized user has a given permission (for example: “manage_group”)against.

By default this returns the list of organizations that the currentlyauthorized user is member of, in any capacity.

When a user becomes a member of an organization in CKAN they’re given a“capacity” (sometimes called a “role”), for example “member”, “editor” or“admin”.

Each of these roles has certain permissions associated with it. For examplethe admin role has the “admin” permission (which means they have permissionto do anything). The editor role has permissions like “create_dataset”,“update_dataset” and “delete_dataset”. The member role has the “read”permission.

This function returns the list of organizations that the authorized userhas a given permission for. For example the list of organizations that theuser is an admin of, or the list of organizations that the user can createdatasets in. This takes account of when permissions cascade down anorganization hierarchy.

Parameters:

  • id (string) – the name or id of the user to get the organization list for(optional, defaults to the currently authorized user (logged in or viaAPI key))

  • permission (string) – the permission the user has against thereturned organizations, for example"read" or"create_dataset"(optional, default:"manage_group")

  • include_dataset_count (bool) – include the package_count in each org(optional, default:False)

Returns:

list of organizations that the user has the given permission for

Return type:

list of dicts

ckan.logic.action.get.license_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of licenses available for datasets on the site.

Return type:

list of dictionaries

ckan.logic.action.get.tag_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]|List[str]

Return a list of the site’s tags.

By default only free tags (tags that don’t belong to a vocabulary) arereturned. If thevocabulary_id argument is given then only tagsbelonging to that vocabulary will be returned instead.

Parameters:

  • query (string) – a tag name query to search for, if given only tags whosenames contain this string will be returned (optional)

  • vocabulary_id (string) – the id or name of a vocabulary, if give only tagsthat belong to this vocabulary will be returned (optional)

  • all_fields (bool) – return full tag dictionaries instead of just names(optional, default:False)

Return type:

list of dictionaries

ckan.logic.action.get.user_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]|List[str]|Query

Return a list of the site’s user accounts.

Parameters:

  • q (string) – filter the users returned to those whose names contain a string(optional)

  • email (string) – filter the users returned to those whose email match astring (optional) (you must be a sysadmin to use this filter)

  • order_by (string) – which field to sort the list by (optional, default:'display_name'). Users can be sorted by'id','name','fullname','display_name','created','about','sysadmin' or'number_created_packages'.

  • all_fields (bool) – return full user dictionaries instead of just names.(optional, default:True)

  • include_site_user (bool) – add site_user to the result(optional, default:False)

Return type:

list of user dictionaries. User properties include:number_created_packages which excludes datasets which are privateor draft state.

ckan.logic.action.get.package_relationships_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a dataset (package)’s relationships.

Parameters:

  • id (string) – the id or name of the first package

  • id2 (string) – the id or name of the second package

  • rel – relationship as string seepackage_relationship_create() forthe relationship types (optional)

Return type:

list of dictionaries

ckan.logic.action.get.package_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

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

Parameters:

  • id (string) – the id or name of the dataset

  • use_default_schema – use default package schema instead ofa custom schema defined with an IDatasetForm plugin (default:False)

  • include_plugin_data – Include the internal plugin data object(sysadmin only, optional, default:False)

Type:

include_plugin_data: bool

Return type:

dictionary

ckan.logic.action.get.resource_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the metadata of a resource.

Parameters:

id (string) – the id of the resource

Return type:

dictionary

ckan.logic.action.get.resource_view_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the metadata of a resource_view.

Parameters:

id (string) – the id of the resource_view

Return type:

dictionary

ckan.logic.action.get.resource_view_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of resource views for a particular resource.

Parameters:

id (string) – the id of the resource

Return type:

list of dictionaries.

ckan.logic.action.get.group_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the details of a group.

Parameters:

  • id (string) – the id or name of the group

  • include_datasets (bool) – include a truncated list of the group’s datasets(optional, default:False)

  • include_dataset_count (bool) – include the full package_count(optional, default:True)

  • include_extras (bool) – include the group’s extra fields(optional, default:True)

  • include_users (bool) – include the group’s users(optional, default:True ifckan.auth.public_user_detailsisTrue otherwiseFalse)

  • include_groups (bool) – include the group’s sub groups(optional, default:True)

  • include_followers (bool) – include the group’s number of followers(optional, default:True)

Return type:

dictionary

Note

Only its first 1000 datasets are returned

ckan.logic.action.get.organization_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the details of a organization.

Parameters:

  • id (string) – the id or name of the organization

  • include_datasets (bool) – include a truncated list of the org’s datasets(optional, default:False)

  • include_dataset_count (bool) – include the full package_count(optional, default:True)

  • include_extras (bool) – include the organization’s extra fields(optional, default:True)

  • include_users (bool) – include the organization’s users(optional, default:True ifckan.auth.public_user_detailsisTrue otherwiseFalse)

  • include_groups (bool) – include the organization’s sub groups(optional, default:True)

  • include_followers (bool) – include the organization’s number of followers(optional, default:True)

Return type:

dictionary

Note

Only its first 10 datasets are returned

ckan.logic.action.get.group_package_show(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the datasets (packages) of a group.

Parameters:

  • id (string) – the id or name of the group

  • limit (int) – the maximum number of datasets to return (optional)

Return type:

list of dictionaries

ckan.logic.action.get.tag_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the details of a tag and all its datasets.

Parameters:

  • id (string) – the name or id of the tag

  • vocabulary_id (string) – the id or name of the tag vocabulary that the tag isin - if it is not specified it will assume it is a free tag.(optional)

  • include_datasets (bool) – include a list of the tag’s datasets. (Up to alimit of 1000 - for more flexibility, use package_search - seepackage_search() for an example.)(optional, default:False)

Returns:

the details of the tag, including a list of all of the tag’sdatasets and their details

Return type:

dictionary

ckan.logic.action.get.user_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return a user account.

Either theid should be passed or the user should be logged in.

Parameters:

  • id (string) – the id or name of the user (optional)

  • include_datasets (bool) – Include a list of datasets the user has created.If it is the same user or a sysadmin requesting, it includes datasetsthat are draft or private.(optional, default:False, limit:50)

  • include_num_followers (bool) – Include the number of followers the user has(optional, default:False)

  • include_password_hash (bool) – Include the stored password hash(sysadmin only, optional, default:False)

  • include_plugin_extras (bool) – Include the internal plugin extras object(sysadmin only, optional, default:False)

Returns:

the details of the user. Includes email_hash andnumber_created_packages (which excludes draft or private datasetsunless it is the same user or sysadmin making the request). Excludesthe password (hash) and reset_key. If it is the same user or asysadmin requesting, the email and apikey are included.

Return type:

dictionary

ckan.logic.action.get.package_autocomplete(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of datasets (packages) that match a string.

Datasets with names or titles that contain the query string will bereturned.

Parameters:

  • q (string) – the string to search for

  • limit (int) – the maximum number of resource formats to return (optional,default:10)

Return type:

list of dictionaries

ckan.logic.action.get.format_autocomplete(context:Context,data_dict:dict[str,Any])→List[str]

Return a list of resource formats whose names contain a string.

Parameters:

  • q (string) – the string to search for

  • limit (int) – the maximum number of resource formats to return (optional,default:5)

Return type:

list of strings

ckan.logic.action.get.user_autocomplete(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of user names that contain a string.

Parameters:

  • q (string) – the string to search for

  • limit (int) – the maximum number of user names to return (optional,default:20)

Return type:

a list of user dictionaries each with keys'name','fullname', and'id'

ckan.logic.action.get.group_autocomplete(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of group names that contain a string.

Parameters:

  • q (string) – the string to search for

  • limit (int) – the maximum number of groups to return (optional,default: 20)

Return type:

a list of group dictionaries each with keys'name','title', and'id'

ckan.logic.action.get.organization_autocomplete(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of organization names that contain a string.

Parameters:

  • q (string) – the string to search for

  • limit (int) – the maximum number of organizations to return (optional,default:20)

Return type:

a list of organization dictionaries each with keys'name','title', and'id'

ckan.logic.action.get.package_search(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Searches for packages satisfying a given search criteria.

This action accepts solr search query parameters (details below), andreturns a dictionary of results, including dictized datasets that matchthe search criteria, a search count and also facet information.

Solr Parameters:

For more in depth treatment of each parameter, please read theSolr Documentation.

This action accepts asubset of solr’s search query parameters:

Parameters:

  • q (string) – the solr query. Optional. Default:"*:*"

  • fq (string) – any filter queries to apply. Note:+site_id:{ckan_site_id}is added to this string prior to the query being executed.

  • fq_list (list ofstrings) – additional filter queries to apply.

  • sort (string) – sorting of the search results. Optional. Default:'scoredesc,metadata_modifieddesc'. As per the solrdocumentation, this is a comma-separated string of field names andsort-orderings.

  • rows (int) – the maximum number of matching rows (datasets) to return.(optional, default:10, upper limit:1000 unless set insite’s configurationckan.search.rows_max)

  • start (int) – the offset in the complete result for where the set ofreturned datasets should begin.

  • facet (string) – whether to enable faceted results. Default:True.

  • facet.mincount (int) – the minimum counts for facet fields should beincluded in the results.

  • facet.limit (int) – the maximum number of values the facet fields return.A negative value means unlimited. This can be set instance-wide withthesearch.facets.limit config option. Default is 50.

  • facet.field (list ofstrings) – the fields to facet upon. Default empty. If empty,then the returned facet information is empty.

  • include_drafts (bool) – ifTrue, draft datasets will be included in theresults. A user will only be returned their own draft datasets, and asysadmin will be returned all draft datasets. Optional, the default isFalse.

  • include_deleted (bool) – ifTrue, deleted datasets will be included in theresults (site configuration “ckan.search.remove_deleted_packages” mustbe set to False). Optional, the default isFalse.

  • include_private (bool) – ifTrue, private datasets will be included inthe results. Only private datasets from the user’s organizations willbe returned and sysadmins will be returned all private datasets.Optional, the default isFalse.

  • use_default_schema (bool) – use default package schema instead ofa custom schema defined with an IDatasetForm plugin (default:False)

The following advanced Solr parameters are supported as well. Note thatsome of these are only available on particular Solr versions. See Solr’sdismax andedismax documentation for further details on them:

qf,wt,bf,boost,tie,defType,mm

Examples:

q=flood datasets containing the wordflood,floods orfloodingfq=tags:economy datasets with the tageconomyfacet.field=["tags"]facet.limit=10rows=0 top 10 tags

Results:

The result of this action is a dict with the following keys:

Return type:

A dictionary with the following keys

Parameters:

  • count (int) – the number of results found. Note, this is the total numberof results found, not the total number of results returned (which isaffected by limit and row parameters used in the input).

  • results (list ofdictized datasets.) – ordered list of datasets matching the query, where theordering defined by the sort parameter used in the query.

  • facets (DEPRECATED dict) – DEPRECATED. Aggregated information about facet counts.

  • search_facets (nested dict ofdicts.) – aggregated information about facet counts. The outerdict is keyed by the facet field name (as used in the search query).Each entry of the outer dict is itself a dict, with a “title” key, andan “items” key. The “items” key’s value is a list of dicts, each with“count”, “display_name” and “name” entries. The display_name is aform of the name that can be used in titles.

An example result:

{'count':2,'results':[{<snip>},{<snip>}],'search_facets':{u'tags':{'items':[{'count':1,'display_name':u'tolstoy','name':u'tolstoy'},{'count':2,'display_name':u'russian','name':u'russian'}]}}}

Limitations:

The full solr query language is not exposed, including.

fl

The parameter that controls which fields are returned in the solrquery.fl can be None or a list of result fields, such as[‘id’, ‘extras_custom_field’].if fl = None, datasets are returned as a list of full dictionary.

ckan.logic.action.get.resource_search(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Searches for resources in public Datasets satisfying the search criteria.

It returns a dictionary with 2 fields:count andresults. Thecount field contains the total number of Resources found without thelimit or query parameters having an effect. Theresults field is alist of dictized Resource objects.

The ‘query’ parameter is a required field. It is a string of the form{field}:{term} or a list of strings, each of the same form. Withineach string,{field} is a field or extra field on the Resource domainobject.

If{field} is"hash", then an attempt is made to match the{term} as aprefix of theResource.hash field.

If{field} is an extra field, then an attempt is made to match againstthe extra fields stored against the Resource.

Note: The search is limited to search against extra fields declared inthe config settingckan.extra_resource_fields.

Note: Due to a Resource’s extra fields being stored as a json blob, thematch is made against the json string representation. As such, falsepositives may occur:

If the search criteria is:

query="field1:term1"

Then a json blob with the string representation of:

{"field1":"foo","field2":"term1"}

will match the search criteria! This is a known short-coming of thisapproach.

All matches are made ignoring case; and apart from the"hash" field,a term matches if it is a substring of the field’s value.

Finally, when specifying more than one search criteria, the criteria areAND-ed together.

Theorder parameter is used to control the ordering of the results.Currently only ordering one field is available, and in ascending orderonly.

The context may contain a flag,search_query, which if True will makethis action behave as if being used by the internal search api. ie - theresults will not be dictized, and SearchErrors are thrown for bad searchqueries (rather than ValidationErrors).

Parameters:

  • query (string or list of strings of the form{field}:{term1}) – The search criteria. See above for description.

  • order_by (string) – A field on the Resource model that orders the results.

  • offset (int) – Apply an offset to the query.

  • limit (int) – Apply a limit to the query.

Returns:

A dictionary with acount field, and aresults field.

Return type:

dict

ckan.logic.action.get.tag_search(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return a list of tags whose names contain a given string.

By default only free tags (tags that don’t belong to any vocabulary) aresearched. If thevocabulary_id argument is given then only tagsbelonging to that vocabulary will be searched instead.

Parameters:

  • query (string orlist ofstrings) – the string(s) to search for

  • vocabulary_id (string) – the id or name of the tag vocabulary to search in(optional)

  • fields (dictionary) – deprecated

  • limit (int) – the maximum number of tags to return

  • offset (int) – whenlimit is given, the offset to start returning tagsfrom

Returns:

A dictionary with the following keys:

'count'

The number of tags in the result.

'results'

The list of tags whose names contain the given string, a list ofdictionaries.

Return type:

dictionary

ckan.logic.action.get.tag_autocomplete(context:Context,data_dict:dict[str,Any])→List[str]

Return a list of tag names that contain a given string.

By default only free tags (tags that don’t belong to any vocabulary) aresearched. If thevocabulary_id argument is given then only tagsbelonging to that vocabulary will be searched instead.

Parameters:

  • query (string) – the string to search for

  • vocabulary_id (string) – the id or name of the tag vocabulary to search in(optional)

  • fields (dictionary) – deprecated

  • limit (int) – the maximum number of tags to return

  • offset (int) – whenlimit is given, the offset to start returning tagsfrom

Return type:

list of strings

ckan.logic.action.get.task_status_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return a task status.

Either theid parameteror theentity_id,task_typeandkey parameters must be given.

Parameters:

  • id (string) – the id of the task status (optional)

  • entity_id (string) – the entity_id of the task status (optional)

  • task_type (string) – the task_type of the task status (optional)

  • key (string) – the key of the task status (optional)

Return type:

dictionary

ckan.logic.action.get.term_translation_show(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the translations for the given term(s) and language(s).

Parameters:

  • terms (list ofstrings) – the terms to search for translations of, e.g.'Russian','romanticnovel'

  • lang_codes (list oflanguage code strings) – the language codes of the languages to search fortranslations into, e.g.'en','de' (optional, default is tosearch for translations into any language)

Return type:

a list of term translation dictionaries each with keys'term'(the term searched for, in the source language),'term_translation'(the translation of the term into the target language) and'lang_code' (the language code of the target language)

ckan.logic.action.get.get_site_user(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return the ckan site user

Parameters:

defer_commit (bool) – by default (or if set to false) get_site_user willcommit and clean up the current transaction. If set to true, calleris responsible for committing transaction after get_site_user iscalled. Leaving open connections can cause cli commands to hang!(optional, default:False)

ckan.logic.action.get.status_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return a dictionary with information about the site’s configuration.

Return type:

dictionary

ckan.logic.action.get.vocabulary_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return a list of all the site’s tag vocabularies.

Return type:

list of dictionaries

ckan.logic.action.get.vocabulary_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Return a single tag vocabulary.

Parameters:

id (string) – the id or name of the vocabulary

Returns:

the vocabulary.

Return type:

dictionary

ckan.logic.action.get.user_follower_count(context:Context,data_dict:dict[str,Any])→int

Return the number of followers of a user.

Parameters:

id (string) – the id or name of the user

Return type:

int

ckan.logic.action.get.dataset_follower_count(context:Context,data_dict:dict[str,Any])→int

Return the number of followers of a dataset.

Parameters:

id (string) – the id or name of the dataset

Return type:

int

ckan.logic.action.get.group_follower_count(context:Context,data_dict:dict[str,Any])→int

Return the number of followers of a group.

Parameters:

id (string) – the id or name of the group

Return type:

int

ckan.logic.action.get.organization_follower_count(context:Context,data_dict:dict[str,Any])→int

Return the number of followers of an organization.

Parameters:

id (string) – the id or name of the organization

Return type:

int

ckan.logic.action.get.user_follower_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of users that are following the given user.

Parameters:

id (string) – the id or name of the user

Return type:

list of dictionaries

ckan.logic.action.get.dataset_follower_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of users that are following the given dataset.

Parameters:

id (string) – the id or name of the dataset

Return type:

list of dictionaries

ckan.logic.action.get.group_follower_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of users that are following the given group.

Parameters:

id (string) – the id or name of the group

Return type:

list of dictionaries

ckan.logic.action.get.organization_follower_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of users that are following the given organization.

Parameters:

id (string) – the id or name of the organization

Return type:

list of dictionaries

ckan.logic.action.get.am_following_user(context:Context,data_dict:dict[str,Any])→bool

ReturnTrue if you’re following the given user,False if not.

Parameters:

id (string) – the id or name of the user

Return type:

bool

ckan.logic.action.get.am_following_dataset(context:Context,data_dict:dict[str,Any])→bool

ReturnTrue if you’re following the given dataset,False if not.

Parameters:

id (string) – the id or name of the dataset

Return type:

bool

ckan.logic.action.get.am_following_group(context:Context,data_dict:dict[str,Any])→bool

ReturnTrue if you’re following the given group,False if not.

Parameters:

id (string) – the id or name of the group

Return type:

bool

ckan.logic.action.get.followee_count(context:Context,data_dict:dict[str,Any])→int

Return the number of objects that are followed by the given user.

Counts all objects, of any type, that the given user is following(e.g. followed users, followed datasets, followed groups).

Parameters:

id (string) – the id of the user

Return type:

int

ckan.logic.action.get.user_followee_count(context:Context,data_dict:dict[str,Any])→int

Return the number of users that are followed by the given user.

Parameters:

id (string) – the id of the user

Return type:

int

ckan.logic.action.get.dataset_followee_count(context:Context,data_dict:dict[str,Any])→int

Return the number of datasets that are followed by the given user.

Parameters:

id (string) – the id of the user

Return type:

int

ckan.logic.action.get.group_followee_count(context:Context,data_dict:dict[str,Any])→int

Return the number of groups that are followed by the given user.

Parameters:

id (string) – the id of the user

Return type:

int

ckan.logic.action.get.organization_followee_count(context:Context,data_dict:dict[str,Any])→int

Return the number of organizations that are followed by the given user.

Parameters:

id (string) – the id of the user

Return type:

int

ckan.logic.action.get.followee_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of objects that are followed by the given user.

Returns all objects, of any type, that the given user is following(e.g. followed users, followed datasets, followed groups.. ).

Parameters:

  • id (string) – the id of the user

  • q (string) – a query string to limit results by, only objects whose displayname begins with the given string (case-insensitive) will be returned(optional)

Return type:

list of dictionaries, each with keys'type' (e.g.'user','dataset' or'group'),'display_name' (e.g. a user’sdisplay name, or a package’s title) and'dict' (e.g. a dictrepresenting the followed user, package or group, the same as the dictthat would be returned byuser_show(),package_show() orgroup_show())

ckan.logic.action.get.user_followee_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of users that are followed by the given user.

Parameters:

id (string) – the id of the user

Return type:

list of dictionaries

ckan.logic.action.get.dataset_followee_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of datasets that are followed by the given user.

Parameters:

id (string) – the id or name of the user

Return type:

list of dictionaries

ckan.logic.action.get.group_followee_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of groups that are followed by the given user.

Parameters:

id (string) – the id or name of the user

Return type:

list of dictionaries

ckan.logic.action.get.organization_followee_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the list of organizations that are followed by the given user.

Parameters:

id (string) – the id or name of the user

Return type:

list of dictionaries

ckan.logic.action.get.member_roles_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return the possible roles for members of groups and organizations.

Parameters:

group_type (string) – the group type, either"group" or"organization"(optional, default"organization")

Returns:

a list of dictionaries each with two keys:"text" (thedisplay name of the role, e.g."Admin") and"value" (theinternal name of the role, e.g."admin")

Return type:

list of dictionaries

ckan.logic.action.get.help_show(context:Context,data_dict:dict[str,Any])→str|None

Return the help string for a particular API action.

Parameters:

name (string) – Action function name (eguser_create,package_search)

Returns:

The help string for the action function, or None if the functiondoes not have a docstring.

Return type:

string

Raises:

ckan.logic.NotFound: if the action function doesn’t exist

ckan.logic.action.get.config_option_show(context:Context,data_dict:dict[str,Any])→Any

Show the current value of a particular configuration option.

Only returns runtime-editable config options (the ones returned byconfig_option_list()), which can be updated with theconfig_option_update() action.

Parameters:

key (string) – The configuration option key

Returns:

The value of the config option from either the system_info table or ini file.

Return type:

string

Raises:

ckan.logic.ValidationError: if config option is not in the schema (whitelisted as editable).

ckan.logic.action.get.config_option_list(context:Context,data_dict:dict[str,Any])→List[str]
Return a list of runtime-editable config options keys that can be

updated withconfig_option_update().

Returns:

A list of config option keys.

Return type:

list

ckan.logic.action.get.job_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]|List[str]

List enqueued background jobs.

Parameters:

  • queues (list) – Queues to list jobs from. If not given then thejobs from all queues are listed.

  • limit (int) – Number to limit the list of jobs by.

  • ids_only (bool) – Whether to return only a list if job IDs or not.

Returns:

The currently enqueued background jobs.

Return type:

list

Will return the list in the way that RQ workers will execute the jobs.Thus the left most non-empty queue will be emptied firstbefore the next right non-empty one.

Added in version 2.7.

ckan.logic.action.get.job_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Show details for a background job.

Parameters:

id (string) – The ID of the background job.

Returns:

Details about the background job.

Return type:

dict

Added in version 2.7.

ckan.logic.action.get.api_token_list(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Return list of all available API Tokens for current user.

Parameters:

user_id (string) – The user ID or name

Returns:

collection of all API Tokens from oldest to newest

Return type:

list

Added in version 2.9.

ckan.logic.action.create

API functions for adding data to CKAN.

ckan.logic.action.create.package_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]|str

Create a new dataset (package).

You must be authorized to create new datasets. If you specify any groupsfor the new dataset, you must also be authorized to edit these groups.

Plugins may change the parameters of this function depending on the valueof thetype parameter, see theIDatasetForm plugin interface.

Parameters:

  • name (string) – the name of the new dataset, must be between 2 and 100characters long and contain only lowercase alphanumeric characters,- and_, e.g.'warandpeace'

  • title (string) – the title of the dataset (optional, default: same asname)

  • private (bool) – IfTrue creates a private dataset

  • author (string) – the name of the dataset’s author (optional)

  • author_email (string) – the email address of the dataset’s author (optional)

  • maintainer (string) – the name of the dataset’s maintainer (optional)

  • maintainer_email (string) – the email address of the dataset’s maintainer(optional)

  • license_id (license id string) – the id of the dataset’s license, seelicense_list() for available values(optional)

  • notes (string) – a description of the dataset (optional)

  • url (string) – a URL for the dataset’s source (optional)

  • version (string,no longer than 100 characters) – (optional)

  • state (string) – the current state of the dataset, e.g.'active' or'deleted', only active datasets show up in search results andother lists of datasets, this parameter will be ignored if you are notauthorized to change the state of the dataset (optional, default:'active')

  • type (string) – the type of the dataset (optional),IDatasetForm pluginsassociate themselves with different dataset types and provide customdataset handling behaviour for these types

  • resources (list ofresource dictionaries) – the dataset’s resources, seeresource_create() for the format of resource dictionaries(optional)

  • tags (list oftag dictionaries) – the dataset’s tags, seetag_create() for the formatof tag dictionaries (optional)

  • extras (list ofdataset extra dictionaries) – the dataset’s extras (optional), extras are arbitrary(key: value) metadata items that can be added to datasets, each extradictionary should have keys'key' (a string),'value' (astring)

  • plugin_data (dict) –

    private package data belonging to plugins.Only sysadmin users may set this value. It should be a dict that canbe dumped into JSON, and plugins should namespace their data with theplugin name to avoid collisions with other plugins, eg:

    {"name":"test-dataset","plugin_data":{"plugin1":{"key1":"value1"},"plugin2":{"key2":"value2"}}}

  • relationships_as_object (list ofrelationship dictionaries) – seepackage_relationship_create()for the format of relationship dictionaries (optional)

  • relationships_as_subject (list ofrelationship dictionaries) – seepackage_relationship_create()for the format of relationship dictionaries (optional)

  • groups (list ofdictionaries) – the groups to which the dataset belongs (optional), eachgroup dictionary should have one or more of the following keys whichidentify an existing group:'id' (the id of the group, string), or'name' (the name of thegroup, string), to see which groups existcallgroup_list()

  • owner_org (string) – the id of the dataset’s owning organization, seeorganization_list() ororganization_list_for_user() foravailable values. This parameter can be made optional if the configoptionckan.auth.create_unowned_dataset is set toTrue.

Returns:

the newly created dataset (unless ‘return_id_only’ is set to Truein the context, in which case just the dataset id willbe returned)

Return type:

dictionary

ckan.logic.action.create.resource_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Appends a new resource to a datasets list of resources.

Parameters:

  • package_id (string) – id of package that the resource should be added to.

  • url (string) – url of resource

  • description (string) – (optional)

  • format (string) – (optional)

  • hash (string) – (optional)

  • name (string) – (optional)

  • resource_type (string) – (optional)

  • mimetype (string) – (optional)

  • mimetype_inner (string) – (optional)

  • cache_url (string) – (optional)

  • size (int) – (optional)

  • created (iso date string) – (optional)

  • last_modified (iso date string) – (optional)

  • cache_last_updated (iso date string) – (optional)

  • upload (FieldStorage (optional)needs multipart/form-data) – (optional)

Returns:

the newly created resource

Return type:

dictionary

ckan.logic.action.create.resource_view_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Creates a new resource view.

Parameters:

  • resource_id (string) – id of the resource

  • title (string) – the title of the view

  • description (string) – a description of the view (optional)

  • view_type (string) – type of view

  • config (JSON string) – options necessary to recreate a view state (optional)

Returns:

the newly created resource view

Return type:

dictionary

ckan.logic.action.create.resource_create_default_resource_views(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Creates the default views (if necessary) on the provided resource

The function will get the plugins for the default views defined inthe configuration, and if some were found thecan_view method ofeach one of them will be called to determine if a resource view shouldbe created. Resource views extensions get the resource dict and theparent dataset dict.

If the latter is not provided,package_show is called to get it.

By default only view plugins that don’t require the resource data to be inthe DataStore are called. Seeckan.logic.action.create.package_create_default_resource_views.`()for details on thecreate_datastore_views parameter.

Parameters:

  • resource (dict) – full resource dict

  • package (dict) – full dataset dict (optional, if not providedpackage_show() will be called).

  • create_datastore_views (bool) – whether to create views that rely on databeing on the DataStore (optional, defaults to False)

Returns:

a list of resource views created (empty if none were created)

Return type:

list of dictionaries

ckan.logic.action.create.package_create_default_resource_views(context:Context,data_dict:dict[str,Any])→List[dict[str,Any]]

Creates the default views on all resources of the provided dataset

By default only view plugins that don’t require the resource data to be inthe DataStore are called. Passingcreate_datastore_views as True willonly create views that require data to be in the DataStore. The first casehappens when the function is called frompackage_create orpackage_update, the second when it’s called from the DataPusher whendata was uploaded to the DataStore.

Parameters:

  • package (dict) – full dataset dict (ie the one obtainedcallingpackage_show()).

  • create_datastore_views (bool) – whether to create views that rely on databeing on the DataStore (optional, defaults to False)

Returns:

a list of resource views created (empty if none were created)

Return type:

list of dictionaries

ckan.logic.action.create.package_relationship_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create a relationship between two datasets (packages).

You must be authorized to edit both the subject and the object datasets.

Parameters:

  • subject (string) – the id or name of the dataset that is the subject of therelationship

  • object – the id or name of the dataset that is the object of therelationship

  • type (string) – the type of the relationship, one of'depends_on','dependency_of','derives_from','has_derivation','links_to','linked_from','child_of' or'parent_of'

  • comment (string) – a comment about the relationship (optional)

Returns:

the newly created package relationship

Return type:

dictionary

ckan.logic.action.create.member_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Make an object (e.g. a user, dataset or group) a member of a group.

If the object is already a member of the group then the capacity of themembership will be updated.

You must be authorized to edit the group.

Parameters:

  • id (string) – the id or name of the group to add the object to

  • object (string) – the id or name of the object to add

  • object_type (string) – the type of the object being added, e.g.'package'or'user'

  • capacity (string) – the capacity of the membership

Returns:

the newly created (or updated) membership

Return type:

dictionary

ckan.logic.action.create.package_collaborator_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Make a user a collaborator in a dataset.

If the user is already a collaborator in the dataset then theircapacity will be updated.

Currently you must be an Admin on the dataset owner organization tomanage collaborators.

Note: This action requires the collaborators feature to be enabled withtheckan.auth.allow_dataset_collaborators configuration option.

Parameters:

  • id (string) – the id or name of the dataset

  • user_id (string) – the id or name of the user to add or edit

  • capacity (string) – the capacity or role of the membership. Must be one of“editor” or “member”. Additionallyifckan.auth.allow_admin_collaborators is set to True, “admin”is also allowed.

Returns:

the newly created (or updated) collaborator

Return type:

dictionary

ckan.logic.action.create.group_create(context:Context,data_dict:dict[str,Any])→str|dict[str,Any]

Create a new group.

You must be authorized to create groups.

Plugins may change the parameters of this function depending on the valueof thetype parameter, see theIGroupForm plugin interface.

Parameters:

  • name (string) – the name of the group, a string between 2 and 100 characterslong, containing only lowercase alphanumeric characters,- and_

  • id (string) – the id of the group (optional)

  • title (string) – the title of the group (optional)

  • description (string) – the description of the group (optional)

  • image_url (string) – the URL to an image to be displayed on the group’s page(optional)

  • type (string) – the type of the group (optional, default:'group'),IGroupForm pluginsassociate themselves with different group types and provide customgroup handling behaviour for these typesCannot be ‘organization’

  • state (string) – the current state of the group, e.g.'active' or'deleted', only active groups show up in search results andother lists of groups, this parameter will be ignored if you are notauthorized to change the state of the group (optional, default:'active')

  • approval_status (string) – (optional)

  • extras (list ofdataset extra dictionaries) – the group’s extras (optional), extras are arbitrary(key: value) metadata items that can be added to groups, each extradictionary should have keys'key' (a string),'value' (astring), and optionally'deleted'

  • packages (list ofdictionaries) – the datasets (packages) that belong to the group, a listof dictionaries each with keys'name' (string, the id or name ofthe dataset) and optionally'title' (string, the title of thedataset)

  • groups (list ofdictionaries) – the groups that belong to the group, a list of dictionarieseach with key'name' (string, the id or name of the group) andoptionally'capacity' (string, the capacity in which the group isa member of the group)

  • users (list ofdictionaries) – the users that belong to the group, a list of dictionarieseach with key'name' (string, the id or name of the user) andoptionally'capacity' (string, the capacity in which the user isa member of the group)

Returns:

the newly created group (unless ‘return_id_only’ is set to Truein the context, in which case just the group id willbe returned)

Return type:

dictionary

ckan.logic.action.create.organization_create(context:Context,data_dict:dict[str,Any])→str|dict[str,Any]

Create a new organization.

You must be authorized to create organizations.

Plugins may change the parameters of this function depending on the valueof thetype parameter, see theIGroupForm plugin interface.

Parameters:

  • name (string) – the name of the organization, a string between 2 and100 characters long, containing only lowercase alphanumericcharacters,- and_

  • id (string) – the id of the organization (optional)

  • title (string) – the title of the organization (optional)

  • description (string) – the description of the organization (optional)

  • image_url (string) – the URL to an image to be displayed on theorganization’s page (optional)

  • state (string) – the current state of the organization, e.g.'active' or'deleted', only active organizations show up in search results andother lists of organizations, this parameter will be ignored if youare not authorized to change the state of the organization(optional, default:'active')

  • approval_status (string) – (optional)

  • extras (list ofdataset extra dictionaries) – the organization’s extras (optional), extras are arbitrary(key: value) metadata items that can be added to organizations,each extradictionary should have keys'key' (a string),'value' (astring), and optionally'deleted'

  • packages (list ofdictionaries) – the datasets (packages) that belong to the organization,a list of dictionaries each with keys'name' (string, the idor name of the dataset) and optionally'title' (string, thetitle of the dataset)

  • users (list ofdictionaries) – the users that belong to the organization, a listof dictionaries each with key'name' (string, the id or nameof the user) and optionally'capacity' (string, the capacityin which the user is a member of the organization)

Returns:

the newly created organization (unless ‘return_id_only’ is setto True in the context, in which case just the organization idwill be returned)

Return type:

dictionary

ckan.logic.action.create.user_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create a new user.

You must be authorized to create users.

Parameters:

  • name (string) – the name of the new user, a string between 2 and 100characters in length, containing only lowercase alphanumericcharacters,- and_

  • email (string) – the email address for the new user

  • password (string) – the password of the new user, a string of at least 4characters

  • id (string) – the id of the new user (optional)

  • fullname (string) – the full name of the new user (optional)

  • about (string) – a description of the new user (optional)

  • image_url (string) – the URL to an image to be displayed on the group’s page(optional)

  • plugin_extras (dict) –

    private extra user data belonging to plugins.Only sysadmin users may set this value. It should be a dict that canbe dumped into JSON, and plugins should namespace their extras withthe plugin name to avoid collisions with other plugins, eg:

    {"name":"test_user","email":"test@example.com","plugin_extras":{"my_plugin":{"private_extra":1},"another_plugin":{"another_extra":True}}}

  • with_apitoken (bool) – whether to create an API token for the user.(Optional)

Returns:

the newly created user

Return type:

dictionary

ckan.logic.action.create.user_invite(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Invite a new user.

You must be authorized to create group members.

Parameters:

  • email (string) – the email of the user to be invited to the group

  • group_id (string) – the id or name of the group

  • role (string) – role of the user in the group. One ofmember,editor,oradmin

Returns:

the newly created user

Return type:

dictionary

ckan.logic.action.create.vocabulary_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create a new tag vocabulary.

You must be a sysadmin to create vocabularies.

Parameters:

  • name (string) – the name of the new vocabulary, e.g.'Genre'

  • tags (list oftag dictionaries) – the new tags to add to the new vocabulary, for the format oftag dictionaries seetag_create()

Returns:

the newly-created vocabulary

Return type:

dictionary

ckan.logic.action.create.tag_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create a new vocabulary tag.

You must be a sysadmin to create vocabulary tags.

You can only use this function to create tags that belong to a vocabulary,not to create free tags. (To create a new free tag simply add the tag toa package, e.g. using thepackage_update() function.)

Parameters:

  • name (string) – the name for the new tag, a string between 2 and 100characters long containing only alphanumeric characters,spaces and the characters-,_ and., e.g.'Jazz'

  • vocabulary_id (string) – the id of the vocabulary that the new tagshould be added to, e.g. the id of vocabulary'Genre'

Returns:

the newly-created tag

Return type:

dictionary

ckan.logic.action.create.follow_user(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Start following another user.

You must provide your API key in the Authorization header.

Parameters:

id (string) – the id or name of the user to follow, e.g.'joeuser'

Returns:

a representation of the ‘follower’ relationship between yourselfand the other user

Return type:

dictionary

ckan.logic.action.create.follow_dataset(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Start following a dataset.

You must provide your API key in the Authorization header.

Parameters:

id (string) – the id or name of the dataset to follow, e.g.'warandpeace'

Returns:

a representation of the ‘follower’ relationship between yourselfand the dataset

Return type:

dictionary

ckan.logic.action.create.group_member_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Make a user a member of a group.

You must be authorized to edit the group.

Parameters:

  • id (string) – the id or name of the group

  • username (string) – name or id of the user to be made member of the group

  • role (string) – role of the user in the group. One ofmember,editor,oradmin

Returns:

the newly created (or updated) membership

Return type:

dictionary

ckan.logic.action.create.organization_member_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Make a user a member of an organization.

You must be authorized to edit the organization.

Parameters:

  • id (string) – the id or name of the organization

  • username (string) – name or id of the user to be made member of theorganization

  • role (string) – role of the user in the organization. One ofmember,editor, oradmin

Returns:

the newly created (or updated) membership

Return type:

dictionary

ckan.logic.action.create.follow_group(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Start following a group.

You must provide your API key in the Authorization header.

Parameters:

id (string) – the id or name of the group to follow, e.g.'roger'

Returns:

a representation of the ‘follower’ relationship between yourselfand the group

Return type:

dictionary

ckan.logic.action.create.api_token_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create new API Token for current user.

Apart from theuser andname field that are required bydefault implementation, there may be additional fields registeredby extensions.

Parameters:

  • user (string) – name or id of the user who owns new API Token

  • name (string) – distinctive name for API Token

Returns:

Returns a dict with the key “token” containing theencoded token value. Extensions can provide additionalfields viaadd_extra method ofIApiToken

Return type:

dictionary

ckan.logic.action.update

API functions for updating existing data in CKAN.

ckan.logic.action.update.resource_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a resource.

To update a resource you must be authorized to update the dataset that theresource belongs to.

Note

Update methods may delete parameters not explicitly provided in thedata_dict. If you want to edit only a specific attribute useresource_patchinstead.

For further parameters seeresource_create().

Parameters:

id (string) – the id of the resource to update

Returns:

the updated resource

Return type:

string

ckan.logic.action.update.resource_view_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a resource view.

To update a resource_view you must be authorized to update the resourcethat the resource_view belongs to.

For further parameters seeresource_view_create().

Parameters:

id (string) – the id of the resource_view to update

Returns:

the updated resource_view

Return type:

string

ckan.logic.action.update.resource_view_reorder(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Reorder resource views.

Parameters:

  • id (string) – the id of the resource

  • order (list ofstrings) – the list of id of the resource to update the order of the views

Returns:

the updated order of the view

Return type:

dictionary

ckan.logic.action.update.package_update(context:Context,data_dict:dict[str,Any])→str|dict[str,Any]

Update a dataset (package).

You must be authorized to edit the dataset and the groups that it belongsto.

Note

Update methods may delete parameters not explicitly provided.If you want to edit only a specific attribute useckan.logic.action.get.package_patch() instead.

If theresources list is omitted the current resources will be leftunchanged.

Plugins may change the parameters of this function depending on the valueof the dataset’stype attribute, see theIDatasetForm plugin interface.

For further parameters seepackage_create().

Parameters:

id (string) – the name or id of the dataset to update

Returns:

the updated dataset (if'return_id_only' isFalse inthe context, which is the default. Otherwise returns just thedataset id)

Return type:

dictionary

ckan.logic.action.update.package_revise(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Revise a dataset (package) selectively with match, filter andupdate parameters.

You must be authorized to edit the dataset and the groups that it belongsto.

Parameters:

  • match (dict) – a dict containing “id” or “name” values of the datasetto update, all values provided must match the currentdataset values or a ValidationError will be raised. e.g.{"name":"my-data","resources":{["name":"big.csv"]}}would abort if the my-data dataset’s first resource nameis not “big.csv”.

  • filter (comma-separated string patterns orlist ofstring patterns) – a list of string patterns of fields to remove from thecurrent dataset. e.g."-resources__1" would remove thesecond resource,"+title,+resources,-*" wouldremove all fields at the dataset level except title andall resources (default:[])

  • update (dict) – a dict with values to update/create after filteringe.g.{"resources":[{"description":"filehere"}]} wouldupdate the description for the first resource

  • include (comma-separated-string patterns orlist ofstring patterns) – a list of string pattern of fields to include in responsee.g."-*" to return nothing (default:[] allfields returned)

match andupdate parameters may also be passed as “flattened keys”, usingeither the item numeric index or its unique id (with a minimum of 5 characters), e.g.update__resources__1f9ab__description="guidebook" would set thedescription of the resource with id starting with “1f9ab” to “guidebook”, andupdate__resources__-1__description="guidebook" would do the sameon the last resource in the dataset.

Theextend suffix can also be used on the update parameter to adda new item to a list, e.g.update__resources__extend=[{"name":"newresource","url":"https://example.com"}]will add a new resource to the dataset with the providedname andurl.

Usage examples:

  • Change description in dataset, checking for old description:

    match={"notes":"old notes","name":"xyz"}update={"notes":"new notes"}

  • Identical to above, but using flattened keys:

    match__name="xyz"match__notes="old notes"update__notes="new notes"

  • Replace all fields at dataset level only, keep resources (note: dataset idand type fields can’t be deleted)

    match={"id":"1234abc-1420-cbad-1922"}filter=["+resources","-*"]update={"name":"fresh-start","title":"Fresh Start"}

  • Add a new resource (__extend on flattened key):

    match={"id":"abc0123-1420-cbad-1922"}update__resources__extend=[{"name":"new resource","url":"http://example.com"}]

  • Update a resource by its index:

    match={"name":"my-data"}update__resources__0={"name":"new name, first resource"}

  • Update a resource by its id (provide at least 5 characters):

    match={"name":"their-data"}update__resources__19cfad={"description":"right one for sure"}

  • Replace all fields of a resource:

    match={"id":"34a12bc-1420-cbad-1922"}filter=["+resources__1492a__id","-resources__1492a__*"]update__resources__1492a={"name":"edits here","url":"http://example.com"}
Returns:

a dict containing ‘package’:the updated dataset with fields filtered by include parameter

Return type:

dictionary

ckan.logic.action.update.package_resource_reorder(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Reorder resources against datasets. If only partial resource ids aresupplied then these are assumed to be first and the other resources willstay in their original order

Parameters:

  • id (string) – the id or name of the package to update

  • order (list) – a list of resource ids in the order needed

ckan.logic.action.update.package_relationship_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a relationship between two datasets (packages).

The subject, object and type parameters are required to identify therelationship. Only the comment can be updated.

You must be authorized to edit both the subject and the object datasets.

Parameters:

  • subject (string) – the name or id of the dataset that is the subject of therelationship

  • object (string) – the name or id of the dataset that is the object of therelationship

  • type (string) – the type of the relationship, one of'depends_on','dependency_of','derives_from','has_derivation','links_to','linked_from','child_of' or'parent_of'

  • comment (string) – a comment about the relationship (optional)

Returns:

the updated relationship

Return type:

dictionary

ckan.logic.action.update.group_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a group.

You must be authorized to edit the group.

Note

Update methods may delete parameters not explicitly provided in thedata_dict. If you want to edit only a specific attribute usegroup_patchinstead.

Plugins may change the parameters of this function depending on the valueof the group’stype attribute, see theIGroupForm plugin interface.

For further parameters seegroup_create().

Callers can choose to not specify packages, users or groups and they will beleft at their existing values.

Parameters:

id (string) – the name or id of the group to update

Returns:

the updated group

Return type:

dictionary

ckan.logic.action.update.organization_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a organization.

You must be authorized to edit the organization.

Note

Update methods may delete parameters not explicitly provided in thedata_dict. If you want to edit only a specific attribute useorganization_patchinstead.

For further parameters seeorganization_create().

Callers can choose to not specify packages, users or groups and they will beleft at their existing values.

Parameters:

  • id (string) – the name or id of the organization to update

  • packages – ignored. usepackage_owner_org_update()to change package ownership

Returns:

the updated organization

Return type:

dictionary

ckan.logic.action.update.user_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a user account.

Normal users can only update their own user accounts. Sysadmins can updateany user account and modify existing usernames.

Note

Update methods may delete parameters not explicitly provided in thedata_dict. If you want to edit only a specific attribute useuser_patchinstead.

For further parameters seeuser_create().

Parameters:

id (string) – the name or id of the user to update

Returns:

the updated user account

Return type:

dictionary

ckan.logic.action.update.task_status_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a task status.

Parameters:

  • id (string) – the id of the task status to update

  • entity_id (string)

  • entity_type (string)

  • task_type (string)

  • key (string)

  • value – (optional)

  • state – (optional)

  • last_updated – (optional)

  • error – (optional)

Returns:

the updated task status

Return type:

dictionary

ckan.logic.action.update.task_status_update_many(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update many task statuses at once.

Parameters:

data (list ofdictionaries) – the task_status dictionaries to update, for the format of taskstatus dictionaries seetask_status_update()

Returns:

the updated task statuses

Return type:

list of dictionaries

ckan.logic.action.update.term_translation_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create or update a term translation.

You must be a sysadmin to create or update term translations.

Parameters:

  • term (string) – the term to be translated, in the original language, e.g.'romanticnovel'

  • term_translation (string) – the translation of the term, e.g.'Liebesroman'

  • lang_code (string) – the language code of the translation, e.g.'de'

Returns:

the newly created or updated term translation

Return type:

dictionary

ckan.logic.action.update.term_translation_update_many(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Create or update many term translations at once.

Parameters:

data (list ofdictionaries) – the term translation dictionaries to create or update,for the format of term translation dictionaries seeterm_translation_update()

Returns:

a dictionary with key'success' whose value is a stringstating how many term translations were updated

Return type:

string

ckan.logic.action.update.vocabulary_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Update a tag vocabulary.

You must be a sysadmin to update vocabularies.

For further parameters seevocabulary_create().

Parameters:

id (string) – the id of the vocabulary to update

Returns:

the updated vocabulary

Return type:

dictionary

ckan.logic.action.update.package_owner_org_update(context:Context,data_dict:dict[str,Any])→None

Update the owning organization of a dataset

Parameters:

  • id (string) – the name or id of the dataset to update

  • organization_id (string) – the name or id of the owning organization

ckan.logic.action.update.bulk_update_private(context:Context,data_dict:dict[str,Any])→None

Make a list of datasets private

Parameters:

  • datasets (list ofstrings) – list of ids of the datasets to update

  • org_id (string) – id of the owning organization

ckan.logic.action.update.bulk_update_public(context:Context,data_dict:dict[str,Any])→None

Make a list of datasets public

Parameters:

  • datasets (list ofstrings) – list of ids of the datasets to update

  • org_id (string) – id of the owning organization

ckan.logic.action.update.bulk_update_delete(context:Context,data_dict:dict[str,Any])→None

Make a list of datasets deleted

Parameters:

  • datasets (list ofstrings) – list of ids of the datasets to update

  • org_id (string) – id of the owning organization

ckan.logic.action.update.config_option_update(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Added in version 2.4.

Allows to modify some CKAN runtime-editable config options

It takes arbitrary key, value pairs and checks the keys against theconfig options update schema. If some of the provided keys are not presentin the schema aValidationError is raised.The values are then validated against the schema, and if validation ispassed, for each key, value config option:

  • It is stored on thesystem_info database table

  • The Pylonsconfig object is updated.

  • Theapp_globals (g) object is updated (this only happens foroptions explicitly defined in theapp_globals module.

The following lists akey parameter, but this should be replaced bywhichever config options want to be updated, eg:

get_action('config_option_update)({}, {'ckan.site_title':'My Open Data site',})
Parameters:

key (string) – a configuration option key (egckan.site_title). It mustbe present on theupdate_configuration_schema

Returns:

a dictionary with the options set

Return type:

dictionary

Note

You can see all available runtime-editable configuration optionscallingtheconfig_option_list() action

Note

Extensions can modify which configuration options areruntime-editable.For details, checkMaking configuration options runtime-editable.

Warning

You should only add config options that you are comfortablethey can be edited during runtime, such as ones you’ve added in yourown extension, or have reviewed the use of in core CKAN.

ckan.logic.action.patch

Added in version 2.3.

API functions for partial updates of existing data in CKAN

ckan.logic.action.patch.package_patch(context:Context,data_dict:dict[str,Any])→str|dict[str,Any]

Patch a dataset (package).

Parameters:

id (string) – the id or name of the dataset

The difference between the update and patch methods is that the patch willperform an update of the provided parameters, while leaving all otherparameters unchanged, whereas the update methods deletes all parametersnot explicitly provided in the data_dict.

To partially update resources or other metadata not at the top levelof a package usepackage_revise() instead to maintainexisting nested values.

You must be authorized to edit the dataset and the groups that it belongsto.

ckan.logic.action.patch.resource_patch(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Patch a resource

Parameters:

id (string) – the id of the resource

The difference between the update and patch methods is that the patch willperform an update of the provided parameters, while leaving all otherparameters unchanged, whereas the update methods deletes all parametersnot explicitly provided in the data_dict

ckan.logic.action.patch.group_patch(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Patch a group

Parameters:

id (string) – the id or name of the group

The difference between the update and patch methods is that the patch willperform an update of the provided parameters, while leaving all otherparameters unchanged, whereas the update methods deletes all parametersnot explicitly provided in the data_dict

ckan.logic.action.patch.organization_patch(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Patch an organization

Parameters:

id (string) – the id or name of the organization

The difference between the update and patch methods is that the patch willperform an update of the provided parameters, while leaving all otherparameters unchanged, whereas the update methods deletes all parametersnot explicitly provided in the data_dict

ckan.logic.action.patch.user_patch(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Patch a user

Parameters:

id (string) – the id or name of the user

The difference between the update and patch methods is that the patch willperform an update of the provided parameters, while leaving all otherparameters unchanged, whereas the update methods deletes all parametersnot explicitly provided in the data_dict

ckan.logic.action.delete

API functions for deleting data from CKAN.

ckan.logic.action.delete.user_delete(context:Context,data_dict:dict[str,Any])→None

Delete a user.

Only sysadmins can delete users.

Parameters:

id (string) – the id or usernamename of the user to delete

ckan.logic.action.delete.package_delete(context:Context,data_dict:dict[str,Any])→None

Delete a dataset (package).

This makes the dataset disappear from all web & API views, apart from thetrash.

You must be authorized to delete the dataset.

Parameters:

id (string) – the id or name of the dataset to delete

ckan.logic.action.delete.dataset_purge(context:Context,data_dict:dict[str,Any])→None

Purge a dataset.

Warning

Purging a dataset cannot be undone!

Purging a database completely removes the dataset from the CKAN database,whereas deleting a dataset simply marks the dataset as deleted (it will nolonger show up in the front-end, but is still in the db).

You must be authorized to purge the dataset.

Parameters:

id (string) – the name or id of the dataset to be purged

ckan.logic.action.delete.resource_delete(context:Context,data_dict:dict[str,Any])→None

Delete a resource from a dataset.

You must be a sysadmin or the owner of the resource to delete it.

Parameters:

id (string) – the id of the resource

ckan.logic.action.delete.resource_view_delete(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Delete a resource_view.

Parameters:

id (string) – the id of the resource_view

ckan.logic.action.delete.resource_view_clear(context:Context,data_dict:dict[str,Any])→None

Delete all resource views, or all of a particular type.

Parameters:

view_types (list) – specific types to delete (optional)

ckan.logic.action.delete.package_relationship_delete(context:Context,data_dict:dict[str,Any])→None

Delete a dataset (package) relationship.

You must be authorised to delete dataset relationships, and to edit boththe subject and the object datasets.

Parameters:

  • subject (string) – the id or name of the dataset that is the subject of therelationship

  • object (string) – the id or name of the dataset that is the object of therelationship

  • type (string) – the type of the relationship

ckan.logic.action.delete.member_delete(context:Context,data_dict:dict[str,Any])→None

Remove an object (e.g. a user, dataset or group) from a group.

You must be authorized to edit a group to remove objects from it.

Parameters:

  • id (string) – the id of the group

  • object (string) – the id or name of the object to be removed

  • object_type (string) – the type of the object to be removed, e.g.packageoruser

ckan.logic.action.delete.package_collaborator_delete(context:Context,data_dict:dict[str,Any])→None

Remove a collaborator from a dataset.

Currently you must be an Admin on the dataset owner organization tomanage collaborators.

Note: This action requires the collaborators feature to be enabled withtheckan.auth.allow_dataset_collaborators configuration option.

Parameters:

  • id (string) – the id or name of the dataset

  • user_id (string) – the id or name of the user to remove

ckan.logic.action.delete.group_delete(context:Context,data_dict:dict[str,Any])→None

Delete a group.

You must be authorized to delete the group.

Parameters:

id (string) – the name or id of the group

ckan.logic.action.delete.organization_delete(context:Context,data_dict:dict[str,Any])→None

Delete an organization.

You must be authorized to delete the organizationand no datasets should belong to the organizationunless ‘ckan.auth.create_unowned_dataset=True’

Parameters:

id (string) – the name or id of the organization

ckan.logic.action.delete.group_purge(context:Context,data_dict:dict[str,Any])→None

Purge a group.

Warning

Purging a group cannot be undone!

Purging a group completely removes the group from the CKAN database,whereas deleting a group simply marks the group as deleted (it will nolonger show up in the frontend, but is still in the db).

Datasets in the organization will remain, just not in the purged group.

You must be authorized to purge the group.

Parameters:

id (string) – the name or id of the group to be purged

ckan.logic.action.delete.organization_purge(context:Context,data_dict:dict[str,Any])→None

Purge an organization.

Warning

Purging an organization cannot be undone!

Purging an organization completely removes the organization from the CKANdatabase, whereas deleting an organization simply marks the organization asdeleted (it will no longer show up in the frontend, but is still in thedb).

Datasets owned by the organization will remain, just not in anorganization any more.

You must be authorized to purge the organization.

Parameters:

id (string) – the name or id of the organization to be purged

ckan.logic.action.delete.task_status_delete(context:Context,data_dict:dict[str,Any])→None

Delete a task status.

You must be a sysadmin to delete task statuses.

Parameters:

id (string) – the id of the task status to delete

ckan.logic.action.delete.vocabulary_delete(context:Context,data_dict:dict[str,Any])→None

Delete a tag vocabulary.

You must be a sysadmin to delete vocabularies.

Parameters:

id (string) – the id of the vocabulary

ckan.logic.action.delete.tag_delete(context:Context,data_dict:dict[str,Any])→None

Delete a tag.

You must be a sysadmin to delete tags.

Parameters:

  • id (string) – the id or name of the tag

  • vocabulary_id (string) – the id or name of the vocabulary that the tag belongsto (optional, default: None)

ckan.logic.action.delete.unfollow_user(context:Context,data_dict:dict[str,Any])→None

Stop following a user.

Parameters:

id (string) – the id or name of the user to stop following

ckan.logic.action.delete.unfollow_dataset(context:Context,data_dict:dict[str,Any])→None

Stop following a dataset.

Parameters:

id (string) – the id or name of the dataset to stop following

ckan.logic.action.delete.group_member_delete(context:Context,data_dict:dict[str,Any])→None

Remove a user from a group.

You must be authorized to edit the group.

Parameters:

  • id (string) – the id or name of the group

  • username (string) – name or id of the user to be removed

ckan.logic.action.delete.organization_member_delete(context:Context,data_dict:dict[str,Any])→None

Remove a user from an organization.

You must be authorized to edit the organization.

Parameters:

  • id (string) – the id or name of the organization

  • username (string) – name or id of the user to be removed

ckan.logic.action.delete.unfollow_group(context:Context,data_dict:dict[str,Any])→None

Stop following a group.

Parameters:

id (string) – the id or name of the group to stop following

ckan.logic.action.delete.job_clear(context:Context,data_dict:dict[str,Any])→list[str]

Clear background job queues.

Does not affect jobs that are already being processed.

Parameters:

queues (list) – The queues to clear. If not given then ALLqueues are cleared.

Returns:

The cleared queues.

Return type:

list

Added in version 2.7.

ckan.logic.action.delete.job_cancel(context:Context,data_dict:dict[str,Any])→None

Cancel a queued background job.

Removes the job from the queue and deletes it.

Parameters:

id (string) – The ID of the background job.

Added in version 2.7.

ckan.logic.action.delete.api_token_revoke(context:Context,data_dict:dict[str,Any])→None

Delete API Token.

Parameters:

  • token (string) – Token to remove(required ifjti not specified).

  • jti (string) – Id of the token to remove(overridestoken ifspecified).

Added in version 3.0.

ckanext.activity.logic.action

Note

These actions are only available when theactivity plugin is enabled.

ckanext.activity.logic.action.send_email_notifications(context:Context,data_dict:dict[str,Any])→None

Send any pending activity stream notification emails to users.

You must provide a sysadmin’s API key/token in the Authorization header ofthe request, or call this action from the command-line via ackan notifysend_emails … command.

ckanext.activity.logic.action.dashboard_mark_activities_old(context:Context,data_dict:dict[str,Any])→None

Mark all the authorized user’s new dashboard activities as old.

This will resetdashboard_new_activities_count() to 0.

ckanext.activity.logic.action.activity_create(context:Context,data_dict:dict[str,Any])→dict[str,Any]|None

Create a new activity stream activity.

You must be a sysadmin to create new activities.

Parameters:

  • user_id (string) – the name or id of the user who carried out the activity,e.g.'seanh'

  • object_id – the name or id of the object of the activity, e.g.'my_dataset'

  • activity_type (string) – the type of the activity, this must be an activitytype that CKAN knows how to render, e.g.'newpackage','changeduser','deletedgroup' etc.

  • data (dictionary) – any additional data about the activity

Returns:

the newly created activity

Return type:

dictionary

ckanext.activity.logic.action.user_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]

Return a user’s public activity stream.

You must be authorized to view the user’s profile.

Parameters:

  • id (string) – the id or name of the user

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

  • after (int,str) – After timestamp(optional, default:None)

  • before (int,str) – Before timestamp(optional, default:None)

Return type:

list of dictionaries

ckanext.activity.logic.action.package_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]

Return a package’s activity stream (not including detail)

You must be authorized to view the package.

Parameters:

  • id (string) – the id or name of the package

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

  • after (int,str) – After timestamp(optional, default:None)

  • before (int,str) – Before timestamp(optional, default:None)

  • include_hidden_activity (bool) – whether to include ‘hidden’ activity, whichis not shown in the Activity Stream page. Hidden activity includesactivity done by the site_user, such as harvests, which are not shownin the activity stream because they can be too numerous, or activity byother users specified in config optionckan.hide_activity_from_users.NB Only sysadmins may set include_hidden_activity to true.(default: false)

  • activity_types (list) – A list of activity types to include in the response

  • exclude_activity_types (list) – A list of activity types to exclude from theresponse

Return type:

list of dictionaries

ckanext.activity.logic.action.group_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]

Return a group’s activity stream.

You must be authorized to view the group.

Parameters:

  • id (string) – the id or name of the group

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

  • include_hidden_activity (bool) – whether to include ‘hidden’ activity, whichis not shown in the Activity Stream page. Hidden activity includesactivity done by the site_user, such as harvests, which are not shownin the activity stream because they can be too numerous, or activity byother users specified in config optionckan.hide_activity_from_users.NB Only sysadmins may set include_hidden_activity to true.(default: false)

Return type:

list of dictionaries

ckanext.activity.logic.action.organization_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]

Return a organization’s activity stream.

Parameters:

  • id (string) – the id or name of the organization

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

  • include_hidden_activity (bool) – whether to include ‘hidden’ activity, whichis not shown in the Activity Stream page. Hidden activity includesactivity done by the site_user, such as harvests, which are not shownin the activity stream because they can be too numerous, or activity byother users specified in config optionckan.hide_activity_from_users.NB Only sysadmins may set include_hidden_activity to true.(default: false)

Return type:

list of dictionaries

ckanext.activity.logic.action.recently_changed_packages_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]

Return the activity stream of all recently added or changed packages.

Parameters:

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

Return type:

list of dictionaries

ckanext.activity.logic.action.dashboard_activity_list(context:Context,data_dict:dict[str,Any])→list[dict[str,Any]]
Return the authorized (via login or API key) user’s dashboard activity

stream.

Unlike the activity dictionaries returned by other*_activity_listactions, these activity dictionaries have an extra boolean value with keyis_new that tells you whether the activity happened since the user lastviewed her dashboard ('is_new':True) or not ('is_new':False).

The user’s own activities are always marked'is_new':False.

Parameters:

  • offset (int) – where to start getting activity items from(optional, default:0)

  • limit (int) – the maximum number of activities to return(optional, default:31 unless set in site’s configurationckan.activity_list_limit, upper limit:100 unless set insite’s configurationckan.activity_list_limit_max)

Return type:

list of activity dictionaries

ckanext.activity.logic.action.dashboard_new_activities_count(context:Context,data_dict:dict[str,Any])→int

Return the number of new activities in the user’s dashboard.

Return the number of new activities in the authorized user’s dashboardactivity stream.

Activities from the user herself are not counted by this function eventhough they appear in the dashboard (users don’t want to be notified aboutthings they did themselves).

Return type:

int

ckanext.activity.logic.action.activity_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Show details of an item of ‘activity’ (part of the activity stream).

Parameters:

id (string) – the id of the activity

Return type:

dictionary

ckanext.activity.logic.action.activity_data_show(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Show the data from an item of ‘activity’ (part of the activitystream).

For example for a package update this returns just the dataset dict butnone of the activity stream info of who and when the version was created.

Parameters:

  • id (string) – the id of the activity

  • object_type (string) – ‘package’, ‘user’, ‘group’ or ‘organization’

Return type:

dictionary

ckanext.activity.logic.action.activity_diff(context:Context,data_dict:dict[str,Any])→dict[str,Any]

Returns a diff of the activity, compared to the previous version of theobject

Parameters:

  • id (string) – the id of the activity

  • object_type (string) – ‘package’, ‘user’, ‘group’ or ‘organization’

  • diff_type (string) – ‘unified’, ‘context’, ‘html’