REST API - Index

API

Introduction

In addition to use of this website, CKAN data can be viewed and changed by using an Application Programming Interface (API).

The API takes the form of a RESTful (Representational State Transfer) style API for accessing CKAN database objects and a Search API.

This document specifies the API so that anyone can create software applications to use the CKAN service. The specification describes the RESTful API in terms of which resources are available, what their locations are, what methods each resource supports, and what the responses might be. It also species the usage and responses to the search API.

API Keys

For any action which makes a change to a resource (i.e. all non-GET methods) you will require an API key. To obtain your API key:

  1. Login as a normal user.
  2. Visit the API Key page.

API Locations

A REST interface presents resources at published locations. Here are the names locations of the CKAN REST API resources. This is followed by a table of non-REST API locations.

Resource Name Location
Package Register /api/rest/package
Package Entity /api/rest/package/PACKAGE-NAME
Group Register /api/rest/group
Group Entity /api/rest/group/GROUP-NAME
Tag Register /api/rest/tag
Tag Entity /api/rest/tag/TAG-NAME
API functions Location
Package Search /api/search/package
Tag Counts /api/tag_counts

Methods and data formats

Each resource location supports a number of methods, which may send or receive a piece of data. Standard http status codes are used to signal the outcome of the operation.

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 Tag Package-List
Search GET Search-Response
Search POST Query-String Search-Response
Tag Counts GET Tag-Count-List

Note: 'PUT' operations may instead use the HTTP POST method.

Note: To search, there are two ways to provide parameters - you can use either or both ways in each search request. The first method is to provide them as parameters in the URL, (e.g. /api/rest/search?q=geodata&allfields=1 ) The second way is to encode the parameters as a JSON dictionary and supply them in the POST request.

Data Formats

Name Format
Package-List [ Name-String, Name-String, Name-String, ... ]
Package { name: Name-String, title: String, version: String, url: String, resources: [ Resource-Dict, Resource-Dict, ... ], author: String, author_email: String, maintainer: String, maintainer_email: String, license: String, tags: Tag-List, notes: String, extras: { Name-String: Value-String, ... } }
Group-List [ Name-String, Name-String, Name-String, ... ]
Group { name: Name-String, title: String, description: String, packages: Group-List }
Tag-List [ Name-String, Name-String, Name-String, ... ]
Tag { name: Name-String }
Name-String An alphanumeric string.
Resource-Dict { url: String, format: String, description: String }
Query-String [ q: String ]
Search-Response { count: Count-int, results: [Package-Name-String, Package-Name-String, ... ] } or { count: Count-int, results: [{ name:Name-String, title: String ... }, { name:Name-String, title: String ... }, etc. ] }
Tag-Count-List [ [tag-name, tag-count], [tag-name, tag-count], ... ]

To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body.

Response data will be in the response body.

Note that 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 a None value.

Search parameters

Key Value Example 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 contatenate 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 URL parameter as a more flexible alternative.
title, tags, notes,
groups, author, maintainer, update_frequency, geographic_granularity, geographic_coverage, temporal_granularity, temporal_coverage, national_statistic, categories, precision, department, agency, external_reference
Search-String title=uk%20stat&tags=health+census Search a particular a field. Note that the latter fields mentioned here are in the 'extra' fields.
order_by field-name (default=rank) order_by=name Specify either rank or the field to sort the results by
offset, limit result-int (default offset=0, default 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 a download URL.

Status Codes

Code Name
200 OK
301 Moved Permanently
400 Bad Request
403 Not Authorized
404 Not Found
409 Conflict (e.g. name already exists)
500 Service Error

Authorized Requests

All requests that are to result in a change to the CKAN register must be sent with a valid Authorization header. In addition, the user must have the authorization to perform the request.

Header Value
HTTP_AUTHORIZATION A valid CKAN REST API authorization token.

The value passed with this header must satisfy the currently operating requirements of CKAN. The current requirment for a valid Authorization header is the value should be a valid API key.

Header Example Value
HTTP_AUTHORIZATION fde34a3c-b716-4c39-8dc4-881ba115c6d4

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