Using data on the Dataset Catalogue and Data Dashboards

Using the SEED API (Application Programming Interface)

This page describes the SEED API. It has been created for developers who would like to write code that interacts with SEED and the data it contains.

About the SEED API

The SEED API is a powerful, RPC-style API that exposes all of SEED’s data to external code. For example, using the SEED API your app can:

get JSON-formatted lists of the SEED datasets
get a full JSON representation of a dataset or resource
search for datasets or resources matching a query
get an activity stream of recently changed datasets on SEED.

Making an API request

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

One way to post a JSON dictionary to a URL is using the command-line HTTP client HTTPie. For example, to get a list of the names of all the organizations within SEED, install HTTPie and then call the organization_list API function by running this command in a terminal:

http https://datasets.seed.nsw.gov.au/api/action/organization_list

The JSON response from SEED will look like this:

{

"help": "https://datasets.seed.nsw.gov.au/api/action/help_show?name=organization_list",

"success": true,

"result": [

"doi-department-of-industry",

"dpe-department-of-planning-and-environment",

"dpi-department-of-primary-industries-water",

"dre-nsw-resources-and-energy",

"epa-environmental-protection-authority",

"lpi-land-property-information",

"oeh-office-of-environment-and-heritage",

"water-new-south-wales"

]

}

This response is a JSON dictionary with three keys:

1. "success": true or false.

The API aims to always return 200 OK as the status code of its HTTP response, whether there were errors with the request or not, so it’s important to always check the value of the "success" key in the response dictionary and (if success is false) check the value of the "error" key.

Note: If there are major formatting problems with a request to the API, SEED may still return an HTTP response with a 409, 400 or 500 status code (in increasing order of severity).

2. "result": the returned result from the function you called. The type and value of the result depend on which function you called. For example, in the case of the group_list function it’s a list of strings, which are the names of all the datasets that belong to the specified group.

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

{

"help": "Creates a package",

"success": false,

"error": {

"message": "Access denied",

"__type": "Authorization Error"

}

}

3. "help": the documentation string for the function you called. This links to documentation about the API call and will provide further information where required.

Authentication and API Keys

By default users of SEED can only access read-only API functions to get data out of the system and view it.

Some more advanced API functions require authorization and a user account for SEED. The API uses the same authorization functions and configuration as the web interface, so if a user is authorized to do something in the web interface they’ll be authorized to do it via the API as well. User accounts will be offered in a future iteration of the portal and are not currently available at this time.

All the API functions listed below are available to all users and cover read-only operations.

REST API

The API functions can also be called via an HTTP GET request. For example, to get the list of datasets (packages) from SEED, open this URL in your browser: https://datasets.seed.nsw.gov.au/api/action/package_list

Or, to search for datasets (packages) matching the search query water, on SEED open this URL in your browser: https://datasets.seed.nsw.gov.au/api/action/package_search?q=water

Tip: Browser plugins like JSONView for Firefox or Chrome will format and colour SEED's JSON response nicely in your browser.

The search query is given as a URL parameter ?q=water. Multiple URL parameters can be appended, separated by & characters, for example to get only the first 10 matching datasets open this URL: https://datasets.seed.nsw.gov.au/api/action/package_search?q=soil&rows=10

When an action requires a list of strings as the value of a parameter, the value can be sent by giving the parameter multiple times in the URL: https://datasets.seed.nsw.gov.au/api/action/term_translation_show?terms=water&terms=soil

JSONP support

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

https://datasets.seed.nsw.gov.au/api/action/package_show?id=nsw-forest-agreements&callback=myfunction

Note: this only works for GET requests.

API Examples

Tags (not in a vocabulary)

A list of all tags:

browser: https://datasets.seed.nsw.gov.au/api/action/tag_list
curl: curl https://datasets.seed.nsw.gov.au/api/action/tag_list

Top 10 tags used by datasets:

browser: https://datasets.seed.nsw.gov.au/api/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0
curl:curl 'https://datasets.seed.nsw.gov.au/api/action/package_search?facet.field=\["tags"\]&facet.limit=10&rows=0'

All datasets that have tag ‘soil’:

browser: https://datasets.seed.nsw.gov.au/action/package_search?fq=tags:soil
curl: curl 'https://datasets.seed.nsw.gov.au/api/3/action/package_search?fq=tags:soil'

Tag Vocabularies

Top 10 tags and vocabulary tags used by datasets:

browser: https://datasets.seed.nsw.gov.au/api/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0
curl:curl 'https://datasets.seed.nsw.gov.au/api/action/package_search?facet.field=\["tags"\]&facet.limit=10&rows=0'

API Reference

API functions for searching for and getting data from CKAN.

ckan.logic.action.get.site_read

Return True

Return Type Boolean

ckan.logic.action.get.package_list

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 of at most limit datasets per page and only one page will be returned at a time (optional) offset (int) – when limit is given, the offset to start returning packages from
Return Type	list of strings

ckan.logic.action.get.current_package_list_with_resources

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) offset (int) – when limit is given, the offset to start returning packages from page (int) – when limit is given, which page to return, Deprecated: use offset
Return Type	list of dictionaries

ckan.logic.action.get.revision_list

Return a list of the IDs of the site’s revisions. They are sorted with the newest first.

Since the results are limited to 50 IDs, you can page through them using parameter since_id.

Parameters	since_id – the revision ID after which you want the revisions since_time – the timestamp after which you want the revisions sort (string) – the order to sort the related items in, possible values are ‘time_asc’, ‘time_desc’ (default). (optional)
Return Type	list of revision IDs, limited to 50

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

ckan.logic.action.get.package_revision_list

Parameters

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

ckan.logic.action.get.member_list

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
Raises	ckan.logic.notfound : if the group does not exist

ckan.logic.action.get.group_list

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’, ‘package_count’ and ‘title’
limit (int) – if given, the list of groups will be broken into pages of at most limit groups per page and only one page will be returned at a time (optional)
offset (int) – when limit is given, the offset to start returning groups from
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 group dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the packages property for each group is deprecated, but there is a count of the packages in the package_count property. (optional, default: False)
include_extras (boolean) – if all_fields, include the group extra fields (optional, default: False)
include_tags (boolean) – if all_fields, include the group tags (optional, default:False)
include_groups (boolean) – if all_fields, include the groups the groups are in (optional, default: False).
include_users (boolean) – if all_fields, include the group users (optional, default:False).

Return Type

list of strings

ckan.logic.action.get.organization_list

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

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’, ‘package_count’ and ‘title’
limit (int) – if given, the list of organizations will be broken into pages of at mostlimit organizations per page and only one page will be returned at a time (optional)
offset (int) – when limit is given, the offset to start returning organizations from
organizations (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 group dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the packages property for each group is deprecated, but there is a count of the packages in the package_count property. (optional, default: False)
include_extras (boolean) – if all_fields, include the organization extra fields (optional, default: False)
include_tags (boolean) – if all_fields, include the organization tags (optional, default:False)
include_groups – if all_fields, include the organizations the organizations are in (optional, default: False)
include_users (boolean) – if all_fields, include the organization users (optional, default: False).

Return Type

list of strings

Return a group’s revisions.ckan.logic.action.get.group_revision_list

Parameters	id (string) – the name or id of the group
Return Type	list of dictionaries

ckan.logic.action.get.organization_revision_list

Return an organization's revisions.

Parameters	id (string) – the name or id of the organization
Return Type	list of dictionaries

ckan.logic.action.get.tag_list

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

ckan.logic.action.get.package_show

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

Parameters

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

Return Type

dictionary

ckan.logic.action.get.resource_show

Return the metadata of a resource.

Parameters	id (string) – the id of the resource include_tracking (bool) – add tracking information to dataset and resources (default: False)
Return Type	dictionary

Parameters	id (string) – the id of the resource include_tracking (bool) – add tracking information to dataset and resources (default: False)
Return Type	dictionary

ckan.logic.action.get.resource_view_show

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

Return the list of resource views for a particular resource.

Parameters	id (string) – the id of the resource
Return Type	list of dictionaries

ic.action.get.revision_show

Return the details of a revision.

Parameters	id (string) – the id of the revision
Return Type	dictionary

ckan.logic.action.get.group_show

Return the details of a group.

Only its first 1000 datasets are returned.

Parameters

id (boolean) – the id or name of the group
include_datasets – include a list of the group’s datasets (optional, default: False)
include_extras – include the group’s extra fields (optional, default: True)
include_users – include the group’s users (optional, default: True)
include_groups – include the group’s sub groups (optional, default: True)
include_tags – include the group’s tags (optional, default: True)
include_followers – include the group’s number of followers (optional, default:True)

Return Type

dictionary

ckan.logic.action.get.organization_show

Return the details of an organization.

Only its first 1000 datasets are returned.

Parameters

id (boolean) – the id or name of the organization
include_datasets – include a list of the organization’s datasets (optional, default:False)
include_extras – include the organization’s extra fields (optional, default: True)
include_users – include the organization’s users (optional, default: True)
include_groups – include the organization’s sub groups (optional, default: True)
include_tags – include the organization’s tags (optional, default: True)
include_followers – include the organization’s number of followers (optional, default: True)

Return Type

dictionary

ckan.logic.action.get.tag_show

Return the details of a tag and all its datasets.

Parameters	d (string) – the name or id of the tag vocabulary_id (string) – the id or name of the tag vocabulary that the tag is in - 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 a limit of 1000 - for more flexibility, use package_search - see package_search() for an example.) (optional, default: False)
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.package_autocomplete

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 limit (int) – the maximum number of resource formats to return (optional, default: 10)
Return Type	list of dictionaries

ckan.logic.action.get.format_autocomplete

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.organization_autocomplete

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

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.

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. sort (string) – sorting of the search results. Optional. Default:'relevance asc, metadata_modified desc'. As per the solr documentation, this is a comma-separated string of field names and sort-orderings. rows (int) – the number of matching rows to return. There is a hard limit of 1000 datasets per query. start (int) – the offset in the complete result for where the set of returned datasets should begin. 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 values the facet fields return. A negative value means unlimited. This can be set instance-wide with the search.facets.limit config option. Default is 50. facet.field (list of strings) – the fields to facet upon. Default empty. If empty, then the returned facet information is empty. include_drafts (boolean) – if True, draft datasets will be included in the results. A user will only be returned their own draft datasets, and a sysadmin will be returned all draft datasets. Optional, the default is False. use_default_schema (bool) – use default package schema instead of a custom schema defined with an IDatasetForm plugin (default: False)
Returns	a dictionary with the following keys:
	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.

Searches for resources satisfying a given search criteria.ckan.logic.action.get.resource_search

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 ‘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. 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.hashfield.

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 settingckan.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	dictionary with a count field, and a results field.
Return Type	dictionary

ckan.logic.action.get.tag_search

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 offset (int) – when limit is given, the offset to start returning tags from limit (int) – the maximum number of tags to return
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_autocomplete

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.vocabulary_list

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

Return Type

list of dictionaries

ckan.logic.action.get.vocabulary_show

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.recently_changed_packages_activity_list

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, the default value is configurable via the ckan.activity_list_limit setting)
Return Type	list of dictionaries

ckan.logic.action.get.package_activity_list_html

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 offset (int) – where to start getting activity items from (optional, default: 0) limit (int) – the maximum number of activities to return (optional, default: 31, the default value is configurable via the ckan.activity_list_limit setting)
Return Type	string

ckan.logic.action.get.help_show

Return the help string for a particular API action.

Parameters	name (string) – Action function name (eg user_create, package_search)
Returns	The help string for the action function, or None if the function does not have a docstring.
Return Type	string
Raises	ckan.logic.NotFound : if the action function doesn’t exist

Bushfire-related Datasets

Data software and Resource formats