Accessing the Data

There are a variety of methods users can use to download data from CanWIN. The most common method is to directly download data from the data catalogue. Each element of a dataset is called a data resource or a data file, and these can be in a variety of formats. Each resource can be downloaded individually, or all resources can be downloaded as a data package. Additionally, CanWIN ckan RPC-style (Remote Procedure Call) API (Application Programming Interface) can be used to download data through various applications.

For more information on downloading data from the Data Catalogue, click on the link below: 

  • Downloading Data and Metadata - provides different options for downloading packaged datasets and metadata formats.
  • Using ckan API - pre-scripted code for users to utilize in downloading data available on the Data Catalogue.

 

 

For example, to get a list of the names of all the organizations within the CanWIN datahub, install HTTPie and then call the organization_list API function by running this command in a terminal:

Note: In CanWIN "tag" is the same as "keyword", "theme" is the same as "group" and "organization" is the same as "facility" so the original CKAN labels must be used for the call (tag, group, organization). The JSON response will look like this:

This response is composed of a JSON dictionary with three keys:

1. "help": the dcoumentation string for the function you called. This links to documentation about the API call and will provide further information where required.

2. "result": this is the resturned result from the funciton you called. The type and value of the result depend on which function you called. For example, in the case of the group_list function it's a list of strings, which are the names of all the themes in CanWIN. If there was an error responding to your request, the dictionary will contain an "error" key with details of the error instead of the "result" key. A response dictionary containing an error will look like this:

3. "success": true or false 

The API aims to always return "200 OK" as the status code of its HTTP response, whether there were errors with the request or not, so it's important to always check the value of the "success" key in the response dictionary and (if success is false) check the value of the "error" key. 

Note: If there are major formatting problems with a request to the API, CanWIN may still return an HTTP respone with a 409, 400 or 500 status code (in increasing order of severity).

Authentication and API tokens

By default CanWIN users can only access read-only API functions to get data out of the system and view it. 

Certain advanced API functions require authorization and a CanWIN user account. The API then uses the same authorization functions and configuration as the web interface, so if a user is authorized to do something in the web interface they will be authorized to do it via the API as well.

When calling an API function that requires authorization, you must authenticate yourself by providing an authentication key with your HTTP request. For our version of CKAN, the recommended mechanism to use are API tokens. These are encrypted keys that can be generated manually from the user interface by clicking on the system icon next to the dashboard icon on the top right menu. At the bottom you will see the Regenerate API Key orange button. Click to generate a new API key. 

Image showing orange button for users to click the Regenerate API Key button

To provide your API token in an HTTP request, include it in an Authorization  line placed before your request.

For example, to conduct the same request above but including the "Authorization" line, type in the following line, where XX is the users' Private API Key.  In this example, we are using the command line tool curl to access the data. 

 

All the API functions listed below are available to all users and cover read-only operations.

REST API

The API functions can also be called via an HTTP GET request typed directly into a web browser. For example, to get a list of datasets (called packages by the API), type the URL below in your browser:

To search for datasets(packages) by keyword for example, "Freshwaters", type the URL below into your browser:

Note: Browser plugins like JSONView will format and colour your JSON response nicely in your browser

Example HTTP query for water using Chrome webbrowser and JSONView plugin
Example query using REST API in web browser and water as query parameter.

The search query is given as a URL parameter "?q=Freshwaters". Multiple URL parameters can be appended, separated by & characters. For example, to get only the first 10 matching datasets for the query using the keyword "Freshwaters" use the following URL: