Skip to content

Using the CKAN API 🧑🏻‍💻

The CanWIN site is powered by CKAN, an open-source data management system that is also used by the government of Canada, multiple agencies, citizen science, and NGO’s.

CKAN’s API allows users to write code that interacts with CKAN sites and their data. The DataStore extension expands the capabilities of the API by allowing for manipulation of data resources (tables) in the DataStore.

In a Nutshell:

  • CKAN API: Used for accessing CKAN's core features such as listing datasets, resources, and retrieving metadata.

  • DataStore API: Used for accessing and manipulating structured data, such as data stored in CSV files.

Calling the API

To call both the CKAN and DataStore APIs, you can post a JSON dictionary in an HTTP POST request to one of the API endpoint URLs. In return, the API will also send a JSON dictionary with its response.

Find your endpoint

For both APIs, an endpoint would look like:

https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/action_function

  • A full list of the different CKAN API action functions can be found here.
  • A full list of the DataStore action functions can be found here.

Endpoint Examples

https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/package_list

https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search


Adding parameters to endpoints

For each action function for the CKAN and DataStore APIs, there are certain parameters that can be added to the endpoint URL to refine the response of the API request, such as querying, filtering, sorting, and so on.

For example, the package_search function for the CKAN API, and the datastore_search function for the DataStore API, both have the query parameter q that can be added to the endpoint URL.

To indicate that we are adding parameters, we use ? to begin the parameter list, and use & between each parameter=value pair. Let's look at the two examples below:

Search Examples

https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/package_search?q=fish

https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search?resource_id=c5c16064-e2b3-4618-9b27-0dbf5c1388c2&q=fish

In the CKAN API example, we are only adding the querying parameter, q, and the query value is fish. Notice that we begin the parameter listing with the ? character.

In the DataStore example, we are using two parameters – the resource_id which has a value of c5c16064-e2b3-4618-9b27-0dbf5c1388c2 and the query parameter q which has the value of fish. Note that they are separated with the & character.

To get a list of all applicable parameters for each function, see the CKAN API and the DataStore API reference.

Finding resource and package IDs

  • Go to any dataset page on CanWIN's CKAN site.
  • Under Data and Resources, click on any of the resources.
  • Scroll down the page to Additional Information and look for the field label Resource id. This will be the ID for this specific resource. You can also find the Package id here.