Model, Search and Action API: Version 3

API Versions

To use a particular version of the API, include the version number in the base of the URL:
  • http://ckan.net/api/1 (version 1)
  • http://ckan.net/api/2 (version 2)
  • http://ckan.net/api/3 (version 3)
e.g. Searching using API version 2::
http://ckan.net/api/2/search/dataset?q=spending
If you don’t specify the version number then you will default to version 1 of the Model, Search and Util APIs and version 3 of the Action API.
  • http://ckan.net/api/rest (version 1)
  • http://ckan.net/api/search (version 1)
  • http://ckan.net/api/util (version 1)
  • http://ckan.net/api/action (version 3)

Action API

Warning

The Action API is in beta in this release. Please feed back comments and problems. There is a known issue that incorrect parameters cause unhelpful errors with status 500.

Overview

The Action API is a powerful RPC-style way of accessing CKAN data. Its intention is to have access to all the core logic in ckan. It calls exactly the same functions that are used internally which all the other CKAN interfaces (Web interface / Model API) go through. Therefore it provides the full gamut of read and write operations, with all possible parameters.

A client supplies parameters to the Action API via a JSON dictionary of a POST request, and returns results, help information and any error diagnostics in a JSON dictionary too. This is a departure from the CKAN API versions 1 and 2, which being RESTful required all the request parameters to be part of the URL.

In addition to the above, any of the actions defined in ckan/logic/action/get.py can be accessed with a GET request to the same URI endpoint. See below for examples.

URL

The basic URL for the Action API is:

/api/action/{logic_action}

Examples:

/api/action/package_list
/api/action/package_show
/api/action/user_create

Parameters

All actions accept POST request including parameters in a JSON dictionary. If there are no parameters required, then an empty dictionary is still required (or you get a 400 error).

Examples:

curl http://test.ckan.net/api/action/package_list -d '{}'
curl http://test.ckan.net/api/action/package_show -d '{"id": "fd788e57-dce4-481c-832d-497235bf9f78"}'
GET-able Actions

Actions defined in get.py can also be accessed with a GET request in addition to the POST method described just above.

Each parameter is specified as a url parameter, for example:

curl http://test.ckan.net/api/3/action/package_search?q=police

Or if the action expects a list of string for a given paramter, then that parameter may be specified more than once, for example:

curl http://test.ckan.net/api/3/action/term_translation_show?terms=russian&terms=romantic%20novel

will result in the following parameters being sent to the term_translation_show action:

{
  'terms': ['russian', 'romantic novel']
}

This interface is slightly more limited than the POST interface because it doesn’t allow passing nested dicts into the action be accessed. As a consequence of this, currently the resource_search action is limited in its functionality when accessed with a GET request.

resource_search:
This action is not currently usable via a GET request as it relies upon a nested dict of fields.

Also, it is worth bearing this limitation in mind when creating your own actions via the IActions interface.

Actions

ckan.logic.action.get.activity_detail_list(context, data_dict)

Return an activity’s list of activity detail items.

Parameters:id (string) – the id of the activity
Return type:list of dictionaries.
ckan.logic.action.get.am_following_dataset(context, data_dict)

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

Parameters:id (string) – the id or name of the dataset
Return type:boolean
ckan.logic.action.get.am_following_user(context, data_dict)

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

Parameters:id (string) – the id or name of the user
Return type:boolean
ckan.logic.action.get.current_package_list_with_resources(context, data_dict)

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 of at most limit datasets per page and only one page will be returned at a time (optional)
  • page (int) – when limit is given, which page to return
Return type:

list of dictionaries

ckan.logic.action.get.dashboard_activity_list(context, data_dict)

Return the dashboard activity stream of the given user.

Parameters:id (string) – the id or name of the user
Return type:list of dictionaries
ckan.logic.action.get.dashboard_activity_list_html(context, data_dict)

Return the dashboard activity stream of the given user as HTML.

The activity stream is rendered as a snippet of HTML meant to be included in an HTML page, i.e. it doesn’t have any HTML header or footer.

Parameters:id (string) – The id or name of the user.
Return type:string
ckan.logic.action.get.dataset_followee_count(context, data_dict)

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.dataset_followee_list(context, data_dict)

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.dataset_follower_count(context, data_dict)

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.dataset_follower_list(context, data_dict)

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.format_autocomplete(context, data_dict)

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.group_activity_list(context, data_dict)

Return a group’s activity stream.

Parameters:id (string) – the id or name of the group
Return type:list of dictionaries
ckan.logic.action.get.group_activity_list_html(context, data_dict)

Return a group’s activity stream as HTML.

The activity stream is rendered as a snippet of HTML meant to be included in an HTML page, i.e. it doesn’t have any HTML header or footer.

Parameters:id (string) – the id or name of the group
Return type:string
ckan.logic.action.get.group_list(context, data_dict)

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

Parameters:
  • 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: “name asc” string of field name and sort-order. The allowed fields are ‘name’ and ‘packages’
  • groups (list of strings) – a list of names of the groups to return, if given only groups whose names are in this list will be returned (optional)
  • all_fields (boolean) – return full group dictionaries instead of just names (optional, default: False)
Return type:

list of strings

ckan.logic.action.get.group_list_authz(context, data_dict)

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

Parameters:available_only (boolean) – remove the existing groups in the package (optional, default: False)
Returns:the names of groups that the user is authorized to edit
Return type:list of strings
ckan.logic.action.get.group_package_show(context, data_dict)

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.group_revision_list(context, data_dict)

Return a group’s revisions.

Parameters:id (string) – the name or id of the group
Return type:list of dictionaries
ckan.logic.action.get.group_show(context, data_dict)

Return the details of a group.

Parameters:id (string) – the id or name of the group
Return type:dictionary
ckan.logic.action.get.licence_list(context, data_dict)

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

Return type:list of dictionaries
ckan.logic.action.get.member_list(context, data_dict=None)

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 given capacity, e.g. 'member', 'editor', 'admin', 'public', 'private' (optional, default: None)
Return type:

list of (id, type, capacity) tuples

ckan.logic.action.get.package_activity_list(context, data_dict)

Return a package’s activity stream.

Parameters:id (string) – the id or name of the package
Return type:list of dictionaries
ckan.logic.action.get.package_activity_list_html(context, data_dict)

Return a package’s activity stream as HTML.

The activity stream is rendered as a snippet of HTML meant to be included in an HTML page, i.e. it doesn’t have any HTML header or footer.

Parameters:id (string) – the id or name of the package
Return type:string
ckan.logic.action.get.package_autocomplete(context, data_dict)

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

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

Parameters:q (string) – the string to search for
Return type:list of dictionaries
ckan.logic.action.get.package_list(context, data_dict)

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

Return type:list of strings
ckan.logic.action.get.package_relationships_list(context, data_dict)

Return a dataset (package)’s relationships.

Parameters:
  • id (string) – the id or name of the package
  • id2
  • rel
Return type:

list of dictionaries

ckan.logic.action.get.package_revision_list(context, data_dict)

Return a dataset (package)’s revisions as a list of dictionaries.

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

Searches for packages satisfying a given search criteria.

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

Solr Parameters:

For more in depth treatment of each paramter, please read the Solr Documentation.

This action accepts a subset 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.
  • rows (int) – the number of matching rows to return.
  • sort (string) – sorting of the search results. Optional. Default: “score desc, name asc”. As per the solr documentation, this is a comma-separated string of field names and sort-orderings.
  • start (int) – the offset in the complete result for where the set of returned datasets should begin.
  • qf (string) – the dismax query fields to search within, including boosts. See the Solr Dismax Documentation for further details.
  • facet (string) – whether to enable faceted results. Default: “true”.
  • facet.mincount (int) – the minimum counts for facet fields should be included in the results.
  • facet.limit (int) – the maximum number of constraint counts that should be returned for the facet fields. A negative value means unlimited
  • facet.field (list of strings) – the fields to facet upon. Default empty. If empty, then the returned facet information is empty.

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 number of results found, not the total number of results returned (which is affected by limit and row parameters used in the input).
  • results (list of dictized datasets.) – ordered list of datasets matching the query, where the ordering defined by the sort parameter used in the query.
  • facets (DEPRECATED dict) – DEPRECATED. Aggregated information about facet counts.
  • search_facets (nested dict of dicts.) – aggregated information about facet counts. The outer dict 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, and an “items” key. The “items” key’s value is a list of dicts, each with “count”, “display_name” and “name” entries. The display_name is a form 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 solr query cannot be changed. CKAN always returns the matched datasets as dictionary objects.
ckan.logic.action.get.package_show(context, data_dict)

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

Parameters:id (string) – the id or name of the dataset
Return type:dictionary
ckan.logic.action.get.recently_changed_packages_activity_list(context, data_dict)

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

Return type:list of dictionaries
ckan.logic.action.get.recently_changed_packages_activity_list_html(context, data_dict)

Return the activity stream of all recently changed packages as HTML.

The activity stream includes all recently added or changed packages. It is rendered as a snippet of HTML meant to be included in an HTML page, i.e. it doesn’t have any HTML header or footer.

Return type:string
ckan.logic.action.get.related_list(context, data_dict=None)

Return a dataset’s related items.

Either the id or the dataset parameter must be given.

Parameters:
  • id (string) – id or name of the dataset (optional)
  • dataset (dictionary) – dataset dictionary of the dataset (optional)
Return type:

list of dictionaries

ckan.logic.action.get.related_show(context, data_dict=None)

Return a single related item.

Parameters:id (string) – the id of the related item to show
Return type:dictionary

Searches for resources satisfying a given search criteria.

It returns a dictionary with 2 fields: count and results. The count field contains the total number of Resources found without the limit or query parameters having an effect. The results field is a list of dictized Resource objects.

The ‘q’ parameter is a required field. It is a string of the form {field}:{term} or a list of strings, each of the same form. Within each string, {field} is a field or extra field on the Resource domain object.

If {field} is "hash", then an attempt is made to match the {term} as a prefix of the Resource.hash field.

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

Note: The search is limited to search against extra fields declared in the config setting ckan.extra_resource_fields.

Note: Due to a Resource’s extra fields being stored as a json blob, the match is made against the json string representation. As such, false positives 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 this approach.

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 are AND-ed together.

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

The fields parameter is deprecated as it is not compatible with calling this action with a GET request to the action API.

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

Parameters:
  • query (string or list of strings of the form “{field}:{term1}”) – The search criteria. See above for description.
  • fields (dict of fields to search terms.) – Deprecated
  • 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 a count field, and a results field.

Return type:

dict

ckan.logic.action.get.resource_show(context, data_dict)

Return the metadata of a resource.

Parameters:id (string) – the id of the resource
Return type:dictionary
ckan.logic.action.get.resource_status_show(context, data_dict)

Return the statuses of a resource’s tasks.

Parameters:id (string) – the id of the resource
Return type:list of (status, date_done, traceback, task_status) dictionaries
ckan.logic.action.get.revision_list(context, data_dict)

Return a list of the IDs of the site’s revisions.

Return type:list of strings
ckan.logic.action.get.revision_show(context, data_dict)

Return the details of a revision.

Parameters:id (string) – the id of the revision
Return type:dictionary
ckan.logic.action.get.roles_show(context, data_dict)

Return the roles of all users and authorization groups for an object.

Parameters:
  • domain_object (string) – a package, group or authorization_group name or id to filter the results by
  • user (string) – a user name or id
  • authorization_group (string) – an authorization group name or id
Return type:

list of dictionaries

ckan.logic.action.get.site_read(context, data_dict=None)

Return True.

Return type:boolean
ckan.logic.action.get.status_show(context, data_dict)

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

ckan.logic.action.get.tag_autocomplete(context, data_dict)

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

By default only free tags (tags that don’t belong to any vocabulary) are searched. If the vocabulary_id argument is given then only tags belonging 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) – when limit is given, the offset to start returning tags from
Return type:

list of strings

ckan.logic.action.get.tag_list(context, data_dict)

Return a list of the site’s tags.

By default only free tags (tags that don’t belong to a vocabulary) are returned. If the vocabulary_id argument is given then only tags belonging to that vocabulary will be returned instead.

Parameters:
  • query (string) – a tag name query to search for, if given only tags whose names contain this string will be returned (optional)
  • vocabulary_id (string) – the id or name of a vocabulary, if give only tags that belong to this vocabulary will be returned (optional)
  • all_fields (boolean) – return full tag dictionaries instead of just names (optional, default: False)
Return type:

list of dictionaries

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

By default only free tags (tags that don’t belong to any vocabulary) are searched. If the vocabulary_id argument is given then only tags belonging to that vocabulary will be searched instead.

Parameters:
  • query (string or list of strings) – 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) – when limit is given, the offset to start returning tags from
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 of dictionaries.

Return type:

dictionary

ckan.logic.action.get.tag_show(context, data_dict)

Return the details of a tag and all its datasets.

Parameters:id (string) – the name or id of the tag
Returns:the details of the tag, including a list of all of the tag’s datasets and their details
Return type:dictionary
ckan.logic.action.get.task_status_show(context, data_dict)

Return a task status.

Either the id parameter or the entity_id, task_type and key 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 – 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, data_dict)

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

Parameters:
  • terms (list of strings) – the terms to search for translations of, e.g. 'Russian', 'romantic novel'
  • lang_codes (list of language code strings) – the language codes of the languages to search for translations into, e.g. 'en', 'de' (optional, default is to search 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.user_activity_list(context, data_dict)

Return a user’s public activity stream.

Parameters:id (string) – the id or name of the user
Return type:list of dictionaries
ckan.logic.action.get.user_activity_list_html(context, data_dict)

Return a user’s public activity stream as HTML.

The activity stream is rendered as a snippet of HTML meant to be included in an HTML page, i.e. it doesn’t have any HTML header or footer.

Parameters:id (string) – The id or name of the user.
Return type:string
ckan.logic.action.get.user_autocomplete(context, data_dict)

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.user_followee_count(context, data_dict)

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.user_followee_list(context, data_dict)

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.user_follower_count(context, data_dict)

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.user_follower_list(context, data_dict)

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.user_list(context, data_dict)

Return a list of the site’s user accounts.

Parameters:
  • q (string) – restrict the users returned to those whose names contain a string (optional)
  • order_by (string) – which field to sort the list by (optional, default: 'name')
Return type:

list of dictionaries

ckan.logic.action.get.user_show(context, data_dict)

Return a user account.

Either the id or the user_obj parameter must be given.

Parameters:
  • id (string) – the id or name of the user (optional)
  • user_obj (user dictionary) – the user dictionary of the user (optional)
Return type:

dictionary

ckan.logic.action.get.vocabulary_list(context, data_dict)

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

Return type:list of dictionaries
ckan.logic.action.get.vocabulary_show(context, data_dict)

Return a single tag vocabulary.

Parameters:id (string) – the id or name of the vocabulary
Returns:the vocabulary.
Return type:dictionary
ckan.logic.action.create.activity_create(context, activity_dict, ignore_auth=False)

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 activity type that CKAN knows how to render, e.g. 'new package', 'changed user', 'deleted group' etc. (for a full list see activity_renderers in ckan/logic/action/get.py
  • data (dictionary) – any additional data about the activity
Returns:

the newly created activity

Return type:

dictionary

ckan.logic.action.create.follow_dataset(context, data_dict)

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 yourself and the dataset
Return type:dictionary
ckan.logic.action.create.follow_user(context, data_dict)

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 yourself and the other user
Return type:dictionary
ckan.logic.action.create.group_create(context, data_dict)

Create a new group.

You must be authorized to create groups.

Plugins may change the parameters of this function depending on the value of the type parameter, see the IGroupForm plugin interface.

Parameters:
  • name (string) – the name of the group, a string between 2 and 100 characters long, 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), IGroupForm plugins associate themselves with different group types and provide custom group handling behaviour for these types
  • state (string) – the current state of the group, e.g. 'active' or 'deleted', only active groups show up in search results and other lists of groups, this parameter will be ignored if you are not authorized to change the state of the group (optional, default: 'active')
  • approval_status (string) – (optional)
  • extras (list of dataset extra dictionaries) – the group’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to groups, each extra dictionary should have keys 'key' (a string), 'value' (a string), and optionally 'deleted'
  • packages (list of dictionaries) – the datasets (packages) that belong to the group, a list of dictionaries each with keys 'name' (string, the id or name of the dataset) and optionally 'title' (string, the title of the dataset)
  • groups (list of dictionaries) – the groups that belong to the group, a list of dictionaries each with key 'name' (string, the id or name of the group) and optionally 'capacity' (string, the capacity in which the group is a member of the group)
  • users (list of dictionaries) – the users that belong to the group, a list of dictionaries each with key 'name' (string, the id or name of the user) and optionally 'capacity' (string, the capacity in which the user is a member of the group)
Returns:

the newly created group

Return type:

dictionary

ckan.logic.action.create.member_create(context, data_dict=None)

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 the membership 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_create(context, data_dict)

Create a new dataset (package).

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

Plugins may change the parameters of this function depending on the value of the type parameter, see the IDatasetForm plugin interface.

Parameters:
  • name (string) – the name of the new dataset, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, - and _, e.g. 'warandpeace'
  • title (string) – the title of the dataset (optional, default: same as name)
  • 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, see license_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 and other lists of datasets, this parameter will be ignored if you are not authorized to change the state of the dataset (optional, default: 'active')
  • type (string) – the type of the dataset (optional), IDatasetForm plugins associate themselves with different dataset types and provide custom dataset handling behaviour for these types
  • resources (list of resource dictionaries) – the dataset’s resources, see resource_create() for the format of resource dictionaries (optional)
  • tags (list of tag dictionaries) – the dataset’s tags, see tag_create() for the format of tag dictionaries (optional)
  • extras (list of dataset extra dictionaries) – the dataset’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to datasets, each extra dictionary should have keys 'key' (a string), 'value' (a string), and optionally 'deleted'
  • relationships_as_object (list of relationship dictionaries) – see package_relationship_create() for the format of relationship dictionaries (optional)
  • relationships_as_subject (list of relationship dictionaries) – see package_relationship_create() for the format of relationship dictionaries (optional)
  • groups (list of dictionaries) – the groups to which the dataset belongs (optional), each group dictionary should have one or more of the following keys which identify an existing group: 'id' (the id of the group, string), 'name' (the name of the group, string), 'title' (the title of the group, string), to see which groups exist call group_list()
Returns:

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

Return type:

dictionary

ckan.logic.action.create.package_relationship_create(context, data_dict)

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 the relationship
  • object – the id or name of the dataset that is the object of the relationship
  • 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.rating_create(context, data_dict)

Rate a dataset (package).

You must provide your API key in the Authorization header.

Parameters:
  • package (string) – the name or id of the dataset to rate
  • rating (int) – the rating to give to the dataset, an integer between 1 and 5
Returns:

a dictionary with two keys: 'rating average' (the average rating of the dataset you rated) and 'rating count' (the number of times the dataset has been rated)

Return type:

dictionary

ckan.logic.action.create.related_create(context, data_dict)

Add a new related item to a dataset.

You must provide your API key in the Authorization header.

Parameters:
  • title (string) – the title of the related item
  • type (string) – the type of the related item, e.g. 'Application', 'Idea' or 'Visualisation'
  • id (string) – the id of the related item (optional)
  • description (string) – the description of the related item (optional)
  • url (string) – the URL to the related item (optional)
  • image_url (string) – the URL to the image for the related item (optional)
  • dataset_id (string) – the name or id of the dataset that the related item belongs to (optional)
Returns:

the newly created related item

Return type:

dictionary

ckan.logic.action.create.resource_create(context, data_dict)

Appends a new resource to a datasets list of resources.

Parameters:
  • package_id (string) – id of package that the resource needs should be added to.
  • url (string) – url of resource
  • revision_id – (optional)
  • description (string) – (optional)
  • format (string) – (optional)
  • hash (string) – (optional)
  • name (string) – (optional)
  • resource_type (string) – (optional)
  • mimetype (string) – (optional)
  • mimetype_inner (string) – (optional)
  • webstore_url (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)
  • webstore_last_updated (iso date string) – (optional)
Returns:

the newly created resource

Return type:

dictionary

ckan.logic.action.create.tag_create(context, tag_dict)

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 to a package, e.g. using the package_update function.)

Parameters:
  • name (string) – the name for the new tag, a string between 2 and 100 characters long containing only alphanumeric characters and -, _ and ., e.g. 'Jazz'
  • vocabulary_id (string) – the name or id of the vocabulary that the new tag should be added to, e.g. 'Genre'
Returns:

the newly-created tag

Return type:

dictionary

ckan.logic.action.create.user_create(context, data_dict)

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 100 characters in length, containing only lowercase alphanumeric characters, - and _
  • email (string) – the email address for the new user
  • password (string) – the password of the new user, a string of at least 4 characters
  • 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)
  • openid (string) – (optional)
Returns:

the newly created yser

Return type:

dictionary

ckan.logic.action.create.vocabulary_create(context, data_dict)

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 of tag dictionaries) – the new tags to add to the new vocabulary, for the format of tag dictionaries see tag_create()
Returns:

the newly-created vocabulary

Return type:

dictionary

ckan.logic.action.update.group_update(context, data_dict)

Update a group.

You must be authorized to edit the group.

Plugins may change the parameters of this function depending on the value of the group’s type attribute, see the IGroupForm plugin interface.

For further parameters see group_create().

Parameters:id (string) – the name or id of the group to update
Returns:the updated group
Return type:dictionary
ckan.logic.action.update.make_latest_pending_package_active(context, data_dict)

TODO: What does this function do?

You must be authorized to update the dataset.

Parameters:id (string) – the name or id of the dataset, e.g. 'warandpeace'
ckan.logic.action.update.package_relationship_update(context, data_dict)

Update a relationship between two datasets (packages).

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

Parameters:
  • id (string) – the id of the package relationship to update
  • subject (string) – the name or id of the dataset that is the subject of the relationship (optional)
  • object – the name or id of the dataset that is the object of the relationship (optional)
  • 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' (optional)
  • comment (string) – a comment about the relationship (optional)
Returns:

the updated relationship

Return type:

dictionary

ckan.logic.action.update.package_update(context, data_dict)

Update a dataset (package).

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

Plugins may change the parameters of this function depending on the value of the dataset’s type attribute, see the IDatasetForm plugin interface.

For further parameters see package_create().

Parameters:id (string) – the name or id of the dataset to update
Returns:the updated dataset (if ‘return_package_dict’ is True in the context, which is the default. Otherwise returns just the dataset id)
Return type:dictionary
ckan.logic.action.update.related_update(context, data_dict)

Update a related item.

You must be the owner of a related item to update it.

For further parameters see related_create().

Parameters:id (string) – the id of the related item to update
Returns:the updated related item
Return type:dictionary
ckan.logic.action.update.resource_update(context, data_dict)

Update a resource.

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

For further parameters see resource_create().

Parameters:id (string) – the id of the resource to update
Returns:the updated resource
Return type:string
ckan.logic.action.update.task_status_update(context, data_dict)

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, data_dict)

Update many task statuses at once.

Parameters:data (list of dictionaries) – the task_status dictionaries to update, for the format of task status dictionaries see task_status_update()
Returns:the updated task statuses
Return type:list of dictionaries
ckan.logic.action.update.term_translation_update(context, data_dict)

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. 'romantic novel'
  • 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, data_dict)

Create or update many term translations at once.

Parameters:data (list of dictionaries) – the term translation dictionaries to create or update, for the format of term translation dictionaries see term_translation_update()
Returns:a dictionary with key 'success' whose value is a string stating how many term translations were updated
Return type:string
ckan.logic.action.update.user_role_bulk_update(context, data_dict)

Update the roles of many users or authorization groups for an object.

You must be authorized to update the domain object.

Parameters:user_roles (list of dictionaries) – the updated user roles, for the format of user role dictionaries see user_role_update()
Returns:the updated roles of all users and authorization groups for the domain object
Return type:dictionary
ckan.logic.action.update.user_role_update(context, data_dict)

Update a user or authorization group’s roles for a domain object.

Either the user or the authorization_group parameter must be given.

You must be authorized to update the domain object.

To delete all of a user or authorization group’s roles for domain object, pass an empty list [] to the roles parameter.

Parameters:
  • user (string) – the name or id of the user
  • authorization_group (string) – the name or id of the authorization group
  • domain_object (string) – the name or id of the domain object (e.g. a package, group or authorization group)
  • roles (list of strings) – the new roles, e.g. ['editor']
Returns:

the updated roles of all users and authorization_groups for the domain object

Return type:

dictionary

ckan.logic.action.update.user_update(context, data_dict)

Update a user account.

Normal users can only update their own user accounts. Sysadmins can update any user account.

For further parameters see user_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.vocabulary_update(context, data_dict)

Update a tag vocabulary.

You must be a sysadmin to update vocabularies.

For further parameters see vocabulary_create().

Parameters:id (string) – the id of the vocabulary to update
Returns:the updated vocabulary
Return type:dictionary
ckan.logic.action.delete.group_delete(context, data_dict)

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.member_delete(context, data_dict=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 of the object to be removed
  • object_type (string) – the type of the object to be removed, e.g. package or user
ckan.logic.action.delete.package_delete(context, data_dict)

Delete a dataset (package).

You must be authorized to delete the dataset.

Parameters:id (string) – the id or name of the dataset to delete
ckan.logic.action.delete.package_relationship_delete(context, data_dict)

Delete a dataset (package) relationship.

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

Parameters:
  • subject (string) – the id or name of the dataset that is the subject of the relationship
  • object (string) – the id or name of the dataset that is the object of the relationship
  • type (string) – the type of the relationship
ckan.logic.action.delete.related_delete(context, data_dict)

Delete a related item from a dataset.

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

Parameters:id (string) – the id of the related item
ckan.logic.action.delete.tag_delete(context, data_dict)

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 belongs to (optional, default: None)
ckan.logic.action.delete.task_status_delete(context, data_dict)

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.unfollow_dataset(context, data_dict)

Stop following a dataset.

Parameters:id (string) – the id or name of the dataset to stop following
ckan.logic.action.delete.unfollow_user(context, data_dict)

Stop following a user.

Parameters:id (string) – the id or name of the user to stop following
ckan.logic.action.delete.vocabulary_delete(context, data_dict)

Delete a tag vocabulary.

You must be a sysadmin to delete vocabularies.

Parameters:id (string) – the id of the vocabulary

In case of doubt, refer to the code of the logic actions, which is found in the CKAN source in the ckan/logic/action directory.

Responses

The response is wholly contained in the form of a JSON dictionary. Here is the basic format of a successful request:

{"help": "Creates a package", "success": true, "result": ...}

And here is one that incurred an error:

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

Where:

  • help is the ‘doc string’ (or null)
  • success is true or false depending on whether the request was successful. The response is always status 200, so it is important to check this value.
  • result is the main payload that results from a successful request. This might be a list of the domain object names or a dictionary with the particular domain object.
  • error is supplied if the request was not successful and provides a message and __type. See the section on errors.

Errors

The message types include:
  • Authorization Error - an API key is required for this operation, and the corresponding user needs the correct credentials
  • Validation Error - the object supplied does not meet with the standards described in the schema.
  • (TBC) JSON Error - the request could not be parsed / decoded as JSON format, according to the Content-Type (default is application/x-www-form-urlencoded;utf-8).

Examples

$ curl http://ckan.net/api/action/package_show -d '{"id": "fd788e57-dce4-481c-832d-497235bf9f78"}'
{"help": null, "success": true, "result": {"maintainer": null, "name": "uk-quango-data", "relationships_as_subject": [], "author": null, "url": "http://www.guardian.co.uk/news/datablog/2009/jul/07/public-finance-regulators", "relationships_as_object": [], "notes": "### About\r\n\r\nDid you know there are nearly 1,200 unelected bodies with power over our lives? This is the full list, complete with number of staff and how much they cost. As a spreadsheet\r\n\r\n### Openness\r\n\r\nNo licensing information found.", "title": "Every Quango in Britain", "maintainer_email": null, "revision_timestamp": "2010-12-21T15:26:17.345502", "author_email": null, "state": "active", "version": null, "groups": [], "license_id": "notspecified", "revision_id": "f645243a-7334-44e2-b87c-64231700a9a6", "tags": [{"revision_timestamp": "2009-08-08T12:46:40.920443", "state": "active", "id": "b10871ea-b4ae-4e2e-bec9-a8d8ff357754", "name": "country-uk"}, {"revision_timestamp": "2009-08-08T12:46:40.920443", "state": "active", "id": "ed783bc3-c0a1-49f6-b861-fd9adbc1006b", "name": "quango"}], "id": "fd788e57-dce4-481c-832d-497235bf9f78", "resources": [{"resource_group_id": "49ddadb0-dd80-9eff-26e9-81c5a466cf6e", "hash": null, "description": "", "format": "", "url": "http://spreadsheets.google.com/ccc?key=tm4Dxoo0QtDrEOEC1FAJuUg", "revision_timestamp": "2011-07-08T14:48:38.967741", "state": "active", "position": 0, "revision_id": "188ac88b-1573-48bf-9ea6-d3c503db5816", "id": "888d00e9-6ee5-49ca-9abb-6f216e646345"}], "extras": []}}

Search API

Search resources are available at published locations. They are represented with a variety of data formats. Each resource location supports a number of methods.

The data formats of the requests and the responses are defined below.

Search Resources

Here are the published resources of the Search API.

Search Resource Location
Dataset Search /search/dataset
Resource Search /search/resource
Revision Search /search/revision
Tag Counts /tag_counts

See below for more information about dataset and revision search parameters.

Search Methods

Here are the methods of the Search API.

Resource Method Request Response
Dataset Search POST Dataset-Search-Params Dataset-Search-Response
Resource Search POST Resource-Search-Params Resource-Search-Response
Revision Search POST Revision-Search-Params Revision-List
Tag Counts GET   Tag-Count-List

It is also possible to supply the search parameters in the URL of a GET request, for example /api/search/dataset?q=geodata&amp;allfields=1.

Search Formats

Here are the data formats for the Search API.

Name Format
Dataset-Search-Params Resource-Search-Params Revision-Search-Params { Param-Key: Param-Value, Param-Key: Param-Value, ... } See below for full details of search parameters across the various domain objects.
Dataset-Search-Response { count: Count-int, results: [Dataset, Dataset, ... ] }
Resource-Search-Response { count: Count-int, results: [Resource, Resource, ... ] }
Revision-List [ Revision-Id, Revision-Id, Revision-Id, ... ] NB: Ordered with youngest revision first
Tag-Count-List [ [Name-String, Integer], [Name-String, Integer], ... ]

Dataset Parameters

These parameters are all the standard SOLR syntax (in contrast to the syntax used in CKAN API versions 1 and 2). Here is a summary of the main features:

Param-Key Param-Value Examples Notes
q Search-String
q=geodata
q=government%20sweden
q=%22drug%20abuse%22
q=title:census
q=tags:maps&tags:country-uk
Criteria to search the dataset fields for. URL-encoded search text. Search results must contain all the specified words. Use colon to specify which field to search in. (Extra fields are not currently supported.)
qjson JSON encoded options [‘q’:’geodata’] All search parameters can be json-encoded and supplied to this parameter as a more flexible alternative in GET requests.
fl list of fields
fl=name
fl=name,title
fl=*
Which fields to return. * is all.
sort field name, asc / dec
sort=name asc
sort=metadata_modified asc
Changes the sort order according to the field and direction given. default: score desc, name asc
start, rows result-int (defaults: start=0, rows=20) start=40&amp;rows=20 Pagination options. Start is the number of the first result and rows is the number of results to return.
all_fields 0 (default) or 1 all_fields=1 Each matching search result is given as either a dataset name (0) or the full dataset record (1).

Resource Parameters

Param-Key Param-Value Example Notes
url, format, description Search-String
url=statistics.org
format=xls
description=Research+Institute
Criteria to search the dataset fields for. URL-encoded search text. This search string must be found somewhere within the field to match. Case insensitive.
qjson JSON encoded options [‘url’:’www.statistics.org’] All search parameters can be json-encoded and supplied to this parameter as a more flexible alternative in GET requests.
hash Search-String hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0 Searches for an match of the hash field. An exact match or match up to the length of the hash given.
all_fields 0 (default) or 1 all_fields=1 Each matching search result is given as either an ID (0) or the full resource record
offset, limit result-int (defaults: offset=0, limit=20) offset=40&amp;limit=20 Pagination options. Offset is the number of the first result and limit is the number of results to return.

Revision Parameters

Param-Key Param-Value Example Notes
since_time Date-Time since_time=2010-05-05T19:42:45.854533 The time can be less precisely stated (e.g 2010-05-05).
since_id Uuid since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08 The stated id will not be included in the results.

Status Codes

The Action API aims to return status 200 OK, whether there are errors or not. The response body contains the success field indicating whether an error occurred or not. When "success": false then you will receive details of the error in the error field. For example requesting a dataset that doesn’t exist:

curl http://test.ckan.net/api/action/package_show -d '{"id": "unknown_id"}'

gives:

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

Alternatively, requests to the Action API that have major formatting problems may result in a 409, 400, or 500 error (in order of increasing severity), but future CKAN releases aim to avoid these responses in favour of the previously described method of providing the error message.

The Search API returns standard HTTP status codes to signal method outcomes:

Code Name
200 OK
201 OK and new object created (referred to in the Location header)
301 Moved Permanently (redirect)
400 Bad Request
403 Not Authorized - have you forgotton to specify your API Key?
404 Not Found
409 Conflict - error during processing of the request
500 Service Error - unhandled error - the system administrator has been notified