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