Reference: CKAN API

The CKAN API provides programmatic access to the catalog of metadata stored in CKAN.

Overview

The CKAN data catalog is not only available in a web browser, but also via its Application Programming Interface (API).

The API can be used to view and change the catalog. This document describes the resource locations, data formats, and status codes which comprise the CKAN API, so that anyone can create software applications that use the API service.

The CKAN API follows the RESTful (Representational State Transfer) style. Resource locations are separated both from the methods supported by the resources, and from the data formats and status codes used by the methods.

Examples

For a tutorial and examples of using the CKAN API, see: http://wiki.ckan.net/Using_the_API

Code Modules for Client Applications

There are also some code modules (Python, PHP, Drupal, Perl etc.) that provide convenient wrappers around much of the CKAN API. For full details of these, please consult http://wiki.ckan.net/API

Versions

The CKAN API is versioned, so that backwards incompatible changes can be introduced without removing existing support. A particular version of the API can be used by including its version number after the API location and before the resource location.

If the API version is not specified in the request, then the API will default to version 1.

Versions 1 & 2

These are very similar, but when the API returns a reference to an object, Version 1 API will return the Name of the object (e.g. “river-pollution”) and Version 2 API will return the ID of the object (e.g. “a3dd8f64-9078-4f04-845c-e3f047125028”).

The reason for this is that Names can change, so to reliably refer to the same package every time, you will want to use the ID and therefore use API v2. Alternatively, many people prefer to deal with Names, so API v1 suits them.

When making requests, you can call objects by either their Name or ID, interchangeably.

The only exception for this is for Tag objects. Since Tag names are immutable, they are always referred to with their Name.

API Details - Versions 1 & 2

Overview

The CKAN data catalog is not only available in a web browser, but also via its Application Programming Interface (API).

The API can be used to view and change the catalog. This document describes the resource locations, data formats, and status codes which comprise the CKAN API, so that anyone can create software applications that use the API service.

The CKAN API follows the RESTful (Representational State Transfer) style. Resource locations are separated both from the methods supported by the resources, and from the data formats and status codes used by the methods.

The CKAN API version 1 & 2 is separated into three parts.

The resources, methods, and data formats of each are described below.

Locators

The locator for a given resource can be formed by appending the relative path for that resource to the API locator.

Resource Locator = API Locator + Resource Path

The API locators for the CKAN APIs (by version) are:

  • http://ckan.net/api (version 1)
  • http://ckan.net/api/1 (version 1)
  • http://ckan.net/api/2 (version 2)

The relative paths for each resource are listed in the sections below.

Model API

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

Model Resources

Here are the resources of the Model API.

Model Resource Location
Package Register /rest/package
Package Entity /rest/package/PACKAGE-REF
Group Register /rest/group
Group Entity /rest/group/GROUP-REF
Tag Register /rest/tag
Tag Entity /rest/tag/TAG-NAME
Rating Register /rest/rating
Package Relationships Register /rest/package/PACKAGE-REF/relationships
Package Relationships Register /rest/package/PACKAGE-REF/RELATIONSHIP-TYPE
Package Relationships Register /rest/package/PACKAGE-REF/relationships/PACKAGE-REF
Package Relationship Entity /rest/package/PACKAGE-REF/RELATIONSHIP-TYPE/PACKAGE-REF
Package’s Revisions Entity /rest/package/PACKAGE-REF/revisions
Revision Register /rest/revision
Revision Entity /rest/revision/REVISION-ID
License List /rest/licenses

Possible values for PACKAGE-REF are the package id, or the current package name.

Possible values for RELATIONSHIP-TYPE are described in the Relationship-Type data format.

Model Methods

Here are the methods of the Model API.

Resource Method Request Response
Package Register GET   Package-List
Package Register POST Package  
Package Entity GET   Package
Package Entity PUT Package  
Group Register GET   Group-List
Group Register POST Group  
Group Entity GET   Group
Group Entity PUT Group  
Tag Register GET   Tag-List
Tag Entity GET   Package-List
Rating Register POST Rating  
Rating Entity GET   Rating
Package Relationships Register GET   Pkg-Relationships
Package Relationship Entity GET   Pkg-Relationship
Package Relationship Entity PUT Pkg-Relationship  
Package’s Revisions Entity GET   Pkg-Revisions
Revision List GET   Revision-List
Revision Entity GET   Revision
License List GET   License-List
  • POSTing data to a register resource will create a new entity.
  • PUT/POSTing data to an entity resource will update an existing entity.
  • PUT operations may instead use the HTTP POST method.

Model Formats

Here are the data formats for the Model API.

To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.

Response data will be in the response body in JSON format.

Notes:

  • When you update an object, fields that you don’t supply will remain as they were before.
  • To delete an ‘extra’ key-value pair, supply the key with JSON value: null
  • When you read a package then some additional information is supplied that cannot current be adjusted throught the CKAN API. This includes info on Package Relationship (‘relationships’), Group membership (‘groups’), ratings (‘ratings_average’ and ‘ratings_count’), full URL of the package in CKAN (‘ckan_url’) and Package ID (‘id’). This is purely a convenience for clients, and only forms part of the Package on GET.

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
Package Search /search/package
Resource Search /search/resource
Revision Search /search/revision
Tag Counts /tag_counts

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

Search Methods

Here are the methods of the Search API.

Resource Method Request Response
Package Search POST Package-Search-Params Package-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/package?q=geodata&allfields=1.

Search Formats

Here are the data formats for the Search API.

Name Format
Package-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.
Package-Search-Response { count: Count-int, results: [Package, Package, ... ] }
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], ... ]

The Package and Revision data formats are as defined in Model Formats.

Package Parameters

Param-Key Param-Value Examples Notes
q Search-String
q=geodata
q=government+sweden
q=%22drug%20abuse%22
Criteria to search the package fields for. URL-encoded search text. (You can also concatenate words with a ‘+’ symbol in a URL.) Search results must contain all the specified words.
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.
title, tags, notes, groups, author, maintainer, update_frequency, or any ‘extra’ field name e.g. department Search-String
title=uk&tags=health+census
department=environment
Search in a particular a field.
order_by field-name (default=rank) order_by=name Specify either rank or the field to sort the results by
offset, limit result-int (defaults: offset=0, limit=20) offset=40&limit=20 Pagination options. Offset is the number of the first result and limit 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 package name (0) or the full package record (1).
filter_by_openness 0 (default) or 1 filter_by_openness=1 Filters results by ones which are open.
filter_by_downloadable 0 (default) or 1 filter_by_downloadable=1 Filters results by ones which have at least one resource URL.

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 package 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&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.

API Keys

You will need to supply an API Key for certain requests to the CKAN API:

  • For any action which makes a change to a resource (i.e. all POST methods on register resources, and PUT/POST methods on entity resources).
  • If the particular resource’s authorization set-up is not open to visitors for the action.

To obtain your API key:

  1. Log-in to the particular CKAN website: /user/login
  2. The user page has a link to the API Key: /user/apikey

The key should be passed in the API request header:

Header Example value
Authorization fde34a3c-b716-4c39-8dc4-881ba115c6d4

If requests that are required to be authorized are not sent with a valid Authorization header, for example the user associated with the key is not authorized for the operation, or the header is somehow malformed, then the requested operation will not be carried out and the CKAN API will respond with status code 403.

For more information about HTTP Authorization header, please refer to section 14.8 of RFC 2616.

Status Codes

Standard HTTP status codes are used to signal method outcomes.

Code Name
200 OK
201 OK and new object created (referred to in the Location header)
301 Moved Permanently
400 Bad Request
403 Not Authorized
404 Not Found
409 Conflict (e.g. name already exists)
500 Service Error

JSONP formatted responses

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.

Example normal request:

GET /api/rest/package/pollution_stats
returns: {"name": "pollution_stats", ... }

but now with the callback parameter:

GET /api/rest/package/pollution_stats?callback=jsoncallback
returns: jsoncallback({"name": "pollution_stats", ... });

This parameter can apply to all GET requests in the API.

Util API

Some of CKAN’s client-side Javascript code makes calls to the CKAN API. For example, to generate a suggestion for a package name when adding a new package the following API call is made:

/api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far

The return value is a JSON data structure:

{"valid": true, "name": "package_1_title_typed_so_far"}

These are the keys returned:

valid

Can be True or False. It is true when the title entered can be successfully turned into a package name and when that package name is not already being used. It is false otherwise.

name

The suggested name for the package, based on the title

You can also add callback=callback to have the response returned as JSONP. eg:

This URL:

/api/2/util/package/create_slug?title=Package+1+Title+Typed+So+Far&callback=callback

Returns:

callback({"valid": true, "name": "package_1_title_typed_so_far"});

In some CKAN deployments you may have the API deployed at a different domain from the main CKAN code. In these circumstances you’ll need to add a new option to the config file to tell the new package form where it should make its API requests to:

ckan.api_url = http://api.example.com/

There is also an autocomplete API for tags which looks like this:

This URL:

/api/2/util/tag/autocomplete?incomplete=ru

Returns:

{"ResultSet": {"Result": [{"Name": "russian"}]}}