API Guide
API key
Some API functions require authorization. The API 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’ll be authorized to do it via the API as well.
When calling an API function that requires authorization, you must authenticate yourself by providing your API key with your HTTP request. To find your API key, login to the CKAN site using its web interface and visit your user profile page.
Resources and Recommendations
When posting a resource using CKAN APIs the data must be in JSON format. There are numerous online tools that can help you convert csv, xls or xlsx files to JSON. You can find a set of python and Windows PowerShell scripts that will convert csv to JSON in our github repository.
One way to post a JSON dictionary to a URL is using the command-line tool and library cURL. For servers without cURL preloaded users can find install files here.
Note: It is recommended that PowerShell users place the body of the HTTP request in a file to avoid all the necessary escape characters.
package_create
Creates a new dataset (package). You must be authorized to create new datasets.
Note: On early CKAN versions, datasets were called “packages” and this name has stuck in some places, specially internally and on API calls. Package has exactly the same meaning as “dataset"
name |
Required |
The name of the new dataset, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, - and _, e.g. 'war_and_peace'. Name parameter must be unique and can be used for resource_id value in datastore_create api |
title |
Required |
The title of the dataset, must be between 2 and 100 characters long. Allows for the creation of a more human-readable file name with capitalization and punctuation |
author |
Required |
The name of the dataset’s author |
author_email |
Required |
The email address of the dataset’s author |
maintainer |
Required |
The name of the dataset’s maintainer |
maintainer_email |
Required |
The email address of the dataset’s maintainer |
license_id |
Required |
The id of the dataset’s license, see license table below for available ids. The recommended id is cc-by “Creative Commons Attribution”. |
notes |
Required |
A description of the dataset, may not be a multi-line string |
tags |
Required |
The dataset’s tags. Must be a string between 2 and 100 characters long containing only alphanumeric characters and -, _ and . |
owner_org |
Required |
The id of the dataset’s owning organization. |
private |
Optional |
If True creates a private dataset. Default value is False |
url |
Optional |
A URL for the dataset’s source |
version |
Optional |
A string, no longer than 100 characters |
ID |
Title |
---|---|
notspecified |
License not specified |
odc-pddl |
Open Data Commons Public Domain Dedication and License (PDDL) |
odc-odbl |
Open Data Commons Open Database License (ODbL) |
odc-by |
Open Data Commons Attribution License |
cc-zero |
Creative Commons CCZero |
cc-by |
Creative Commons Attribution |
cc-by-sa |
Creative Commons Attribution Share-Alike |
gfdl |
GNU Free Documentation License |
other-open |
Other (Open) |
other-pd |
Other (Public Domain) |
other-at |
Other (Attribution) |
uk-ogl |
UK Open Government License (OGL) |
cc-nc |
Creative Commons Non-Commercial (Any) |
other-nc |
Other (Non-Commercial) |
other-closed |
Other (Not Open) |
* We recommend cc-by “Creative Commons Attribution” as the default value
EXAMPLE
For example, to create a new dataset in the department-of-public-health group on data.illinois.gov, create a file with all the parameters first, then call the package_create API function by running the following command in a terminal:
curl -X POST https://data.illinois.gov/api/3/action/package_create -H "Authorization: {YOUR-API-KEY}" -d "@path-to-file/file.json" |
file.json
{ |
The response is a JSON dictionary with three keys:
- "success": true or false.
- "result": the returned result from the function you called.
- "help": the documentation string for the function you called.
datastore_create
Adds a new table to the DataStore. The datastore_create action allows you to post tabular JSON data to be stored against a resource. A DataStore resource cannot be created on its own; A dataset (package) must exist for DataStore API to work. One can be created using the package_create API.
resource |
Required |
Resource dictionary that is passed to resource_create. It contains values for the following keys: package_id, name, description |
package_id |
Required |
A resource dictionary item. Id of the package that the data is going to be stored in. If package was created using package_create then you may use the name parameter from that API |
name |
Required |
A resource dictionary item. Id of the package that the data is going to be stored in. If package was created using package_create then you may use the name parameter from that API |
description |
Required |
A resource dictionary item. Description of the resource being created. |
format |
Required |
A resource dictionary item. Applies icons to index page and resource. |
fields |
Required |
Fields/columns and their extra metadata. |
records |
Required |
The data in JSON format. Record keys are case sensitive and must match field values. |
primary_key |
Optional |
Fields that represent a unique key. Values are entered as an array. A primary key is required in order to use datastore_upsert. |
indexes |
Optional |
Indexes on table |
force |
Optional |
Set to True to edit a read-only resource |
aliases |
Optional |
Names for read only aliases of the resource. Must be unique. |
EXAMPLE
To use the datastore_create API, store all your parameters and converted JSON data in a separate file. Using cURL the API command can be written like this:
curl -X POST https://data.illinois.gov/api/3/action/datastore_create -H "Authorization: {YOUR-API-KEY}" -d "@path-to-file/file.json" |
file.json would contain the body of the cURL command:
{ |
For both methods the response is a JSON dictionary with three keys:
- "success": true or false.
- "result": the returned result from the function you called.
- "help": the documentation string for the function you called.
datastore_upsert
Updates or inserts into a table in the DataStore
The datastore_upsert API action allows you to add or edit records to an existing DataStore resource. In order for the upsert and update methods to work, a unique key has to be defined via the datastore_create action. The available methods are:
upsert
Update if record with same key already exists, otherwise insert. Requires unique key.
insert
Insert only. This method is faster than upsert, but will fail if any inserted record matches an existing one. Does not require a unique key.
update
Update only. An exception will occur if the key that should be updated does not exist. Requires unique key.
resource_id |
Required |
Resource id that the data is going to be stored under. It can be found in the resources additional information table. |
records |
Required |
The data in JSON format. Record keys are case sensitive and must match field values. |
force |
Optional |
Set to True to edit a read-only resource |
method |
Optional |
The method to use to put the data into the datastore. Possible options are: upsert, insert, update. The default value is upsert |
EXAMPLE
When performing an upsert using the datastore_upsert API the data must be in JSON format. Store all your parameters and data in a separate file. Then the upsert method for the datastore_upsert API can be executed using the cURL command:
curl -X POST https://data.illinois.gov/api/3/action/datastore_upsert -H "Authorization: {YOUR-API-KEY}" –d "@path-to-file/file.json" |
{ |
The insert method:
curl -X POST https://data.illinois.gov/api/3/action/datastore_upsert -H "Authorization: {YOUR-API-KEY}" –d "@path-to-file/file.json" |
{ |
The update method:
curl -X POST https://data.illinois.gov/api/3/action/datastore_upsert -H "Authorization: {YOUR-API-KEY}" –d "@path-to-file/file.json" |
{ |
The response for all of these methods is a JSON dictionary with three keys:
"success":
true or false.- "result": the returned result from the function you called.
- "help": the documentation string for the function you called.