Steps to call the CKAN API¶
To call both the CKAN and DataStore APIs, either an HTTP POST or GET request can be made to one of the API endpoint URLs. In return, the API will send a JSON dictionary with its response.
Therefore, we can break down a call into 2 steps:
- Finding the appropriate endpoint
- Making the HTTP request.
1. Finding the endpoint¶
Note
An API endpoint is the location where the API receives requests about a specific resource on its server.
For both APIs, an endpoint would look like:
For example, an endpoint for the CKAN API is:
An example of a DataStore API endpoint is:
-
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.
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.
Examples¶
Tip
To make it easy to read JSON responses directly in your browser, use a browser extension that automatically reformats the API response. An extension for chrome is the JSON Viewer extension which you can find here.
The package_search function (CKAN API)¶
In this example, we are only adding the query parameter, q, with the query value being fish. Notice that we begin the parameter listing with the ? character. This will return a JSON dictionary of packages that have fish somewhere in their metadata.
Click here for a list of all applicable parameters for the package_search function.
The datastore_search function (DataStore API)¶
The datastore_search function is quite powerful and can take several parameters to further refine your search within a specific resource (data table).
The only mandatory parameter is the resource_id (see below for how to find this ID). Some other useful parameters are:
| Parameter | Description |
|---|---|
| filter (dictionary) | Matching conditions to select |
| q (string or dictionary) | Full text query. If it’s a string, it’ll search on all fields on each row. If it’s a dictionary as {“key1”: “a”, “key2”: “b”}, it’ll search on each specific field |
| limit (int) | Maximum number of rows to return |
| fields (list or comma separated string) | Fields to return (default: all fields in original order) |
| sort (string) | Comma separated field names with ordering e.g.: “fieldname1, fieldname2 desc” |
This function call returns a JSON dictionary with several parameters, the most useful being:
| Parameter | Description |
|---|---|
| fields (list of dictionaries) | Fields/columns and their extra metadata |
| records (default is list of dictionaries) | list of matching results |
| total (int) | number of total matching records |
Let's look at some examples:
Example 1 – Using q
https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search?resource_id=c5c16064-e2b3-4618-9b27-0dbf5c1388c2&q=Greenedge
This will return all the rows that contain Greenedge
Example 2 – Using q
https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search?resource_id=c5c16064-e2b3-4618-9b27-0dbf5c1388c2&q={"Bottle":"17","Cast":"3"}
This will return all the rows where Bottle is 17 and the Cast is 3.
Example 3 – Using filters
https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search?resource_id=c5c16064-e2b3-4618-9b27-0dbf5c1388c2&filters={"Cast":"3","sample_date":"2016-06-09T00:00:00" }
This is similar to using q with a dictionary, and will return all the rows where the Cast is 3 and the sample_date is 2016-06-09T00:00:00
Example 4 – Using limit
https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/datastore_search?resource_id=c5c16064-e2b3-4618-9b27-0dbf5c1388c2&limit=2
This limits the number of rows returned to 2.
Click here for a list of all applicable parameters for the datastore_search function.
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.
2. Making the HTTP request¶
Now that we know how to find our endpoints, making the HTTP GET or POST request can be done using several tools or programming languages.
Here we look at examples using: