Using the API
From CKAN
Here is our TEST instance for experimenting with:
Contents |
Introduction
Let's say you're using test.ckan.net and want a list of all the datasets. If you GET http://test.ckan.net/api/rest/dataset then it will return the list of the dataset names in JSON format:
["2000-us-census-rdf", "32000-naples-florida-businesses-kml", "aaoe-87", "acawiki", "adb-sdbs", "addgene", "advances-in-dental-research", ... ]
There are several ways you might access this URL:
- simply put this URL into your web browser and save the resulting text file
- you could use a command-line program such as `curl` or `wget`
- you could write a program that uses an http library
- use the Python library `CKAN Client http://pypi.python.org/pypi/ckanclient
- use command-line tool Datapkg http://packages.python.org/datapkg/ It manages datasets in a similar way as getting software packages with `apt-get` or `CPAN`.
Setup
You can use the API without an APIKEY, but you will be given read-only access. To get an apikey for a particular CKAN site:
- Login or register. e.g. for test.ckan.net: http://test.ckan.net/user/register
- Get an API key: it is on your user account page. (When you log in you are sent to this page) e.g. for test.ckan.net: http://test.ckan.net/user/me
Full documentation: http://docs.ckan.org/en/latest/api.html
Example queries
Search
{"count": 4, "results": ["uk-naptan-osm", "osm-uk", "osm", "naptan"]}
Get dataset
{"id": "a3dd8f64-9078-4f04-845c-e3f047125028", "name": "osm", "title": "Open Street Map", ...
...
Create a dataset
You'll need an api key (see 'setup')
$ curl http://test.ckan.net/api/rest/dataset -d '{"name":"test", "title":"Test dataset"}' -H "Authorization:your-api-key"
Here's a more complicated example using lots of extra fields. This is an example government dataset:
$ curl http://test.ckan.net/api/rest/dataset -d '{"name": "abstract_of_scottish_agricultural_statistics", "title": "Abstract of Scottish Agricultural Statistics", "version": null, "url": null, "author": "Scottish Government", "author_email": null, "maintainer": null, "maintainer_email": null, "notes": "A long term series of all the main agriculture census items collected in the June census.\n\nSource agency: Scottish Government\n\nDesignation: National Statistics\n\nLanguage: English\n\nAlternative title: Abstract of Scottish Agricultural Statistics", "license_id": "ukcrown-withrights", "tags": ["farm-outputs", "environment", "agriculture", "farming", "agriculture-and-environment"], "extras": {"geographic_coverage": "010000: Scotland", "geographical_granularity": "Country", "external_reference": "ONSHUB", "temporal_granularity": "", "date_updated": "", "agency": "", "precision": "", "temporal_coverage_to": "", "temporal_coverage_from": "", "national_statistic": "yes", "import_source": "ONS-ons_data_50_days_to_2010-05-04", "department": "Scottish Government", "update_frequency": "", "date_released": "2010-03-17", "categories": "Agriculture and Environment"}, "resources": [{"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2008 | hub/id/119-33192", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1982-2007 | hub/id/119-34917", "format": ""}, {"url": "http://www.scotland.gov.uk/Topics/Statistics/Browse/Agriculture-Fisheries", "description": "1983-2009 | hub/id/119-44310", "format": ""}]}' -H "Authorization: d6c3349a-6ccf-45ef-88d4-a8e59a574bf2"
Update a dataset
(using POST or PUT)
$ curl http://test.ckan.net/api/rest/dataset/test -d '{"name":"test", "title":"Changed Test dataset"}' -H "Authorization:your-api-key"
Viewing permissions
To view authorization roles on a dataset:
$ curl http://test.ckan.net/api/action/roles_show -d '{"domain_object": "freshwateratlasrivers"}' {"help": "Returns the roles that users (and authorization groups) have on a\n particular domain_object.\n \n If you specify a user (or authorization group) then the resulting roles\n will be filtered by those of that user (or authorization group).\n\n domain_object can be a package/group/authorization_group name or id.\n ", "success": true, "result": {"domain_object_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a", "domain_object_type": "Package", "roles": [{"user_id": "4229c297-fe28-4597-a191-3ebbbee6c47a", "authorized_group_id": null, "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a", "role": "editor", "context": "Package", "user_object_role_id": "481b6cd8-350b-4599-bd20-5e3c0ed0a8cb", "id": "481b6cd8-350b-4599-bd20-5e3c0ed0a8cb"}, {"user_id": "e7f30c0d-944b-4a69-84c4-61b08bbf6b98", "authorized_group_id": null, "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a", "role": "admin", "context": "Package", "user_object_role_id": "aba38fa7-2fb4-4f84-98e1-02cb76c5d95a", "id": "aba38fa7-2fb4-4f84-98e1-02cb76c5d95a"}, {"user_id": "41cb1162-3d61-4b16-a3af-4cae27836ac5", "authorized_group_id": null, "package_id": "9da77628-2ac5-4965-af12-c7c51cc1d99a", "role": "reader", "context": "Package", "user_object_role_id": "e06b1293-86ec-4417-8e28-b9499161348e", "id": "e06b1293-86ec-4417-8e28-b9499161348e"}]}}
Looking at the list of "roles" we can see who has what permissions on this dataset. User with id="4229..." is an "editor", id="e7f3..." is an "admin", "41cb..." is a "reader". By using the user_show call to reveal the names of the users, we see that "visitor" (i.e. anyone who is not logged in) is the "reader" (no write permission), "logged-in" (any logged-in user) is the "editor" and the admin is "OKFN" who is the user who created this dataset in the first place and can therefore confer permissions to other users.
Adding permissions
To give user "dread" the "admin" authorization role on dataset "freshwateratlasrivers":
$ curl http://test.ckan.net/api/action/user_role_update -d '{"user": "dread", "domain_object": "freshwateratlasrivers", "roles": ["admin"]}' -H "Authorization:{your-api-key}"
Client software
Full list of javascript, python, perl, PHP and command-line clients in API
Using the API with Javascript
Javascript examples
You can also call the API from Javascript. Here are some examples:
- http://rufuspollock.org/code/ckanjs/
- https://bitbucket.org/rgrp/ckanjs/src - fork this to get started
- see ckan.js for a basic JQuery client
