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"

PARAMETERS

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

 

LICENSE_ID TABLE

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

{
  "name": "hospital_directory",
  "title": "Directory of Hospitals",
  "tags": [{"name":"hospitals"}, {"name":"directory"}],
  "notes":"List of Hospitals, including facility name, city, and license number",
  "private":"False",
  "author":"joe blogger",
  "author_email":"joe.blogger@state.gov",
  "maintainer":"joe blogger",
  "maintainer_email":"joe.blogger@state.gov",
  "license_id":"gfdl",
  "owner_org": "department-of-public-health"
}

 

The response is a JSON dictionary with three keys:

  1. "success": true or false.
  2. "result": the returned result from the function you called.
  3.  "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. 

PARAMETERS

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:

{
"resource":{"package_id":"hospital_directory", "name":"Hospital Directory", "format":"csv","description":"Hospital data file"},
"fields": [ {"id": "Hospital Name"}, {"id": "City"}, {"id": "License #"}],
"primary_key": ["License #"],
"records": 
  [{
    "Hospital Name": "Abraham Lincoln Hospital",
    "City": "Lincoln",
    "License #": "0001357"
  },
  {
    "Hospital Name": "Jackson Park Hospital",
    "City": "Chicago",
    "License #": "0002468"
  }]
}

 

For both methods the response is a JSON dictionary with three keys:

  1. "success": true or false.
  2. "result": the returned result from the function you called.
  3. "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"

 

{
"resource_id":"{THE-RESOURCE-ID}",
"method" : "upsert",
"records" :
 [
  {
    "Hospital Name": "Waco Hospital",
    "City": "Waco",
    "License #": "0004358"
  },
  {
    "Hospital Name": "Tinley Community Hospital",
    "City": "Tinley Park",
    "License #": "0004467"
  }
 ]
}

 

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"

 

{
"resource_id":"{THE-RESOURCE-ID}",
"method" : "insert",
"records" :
 [
  {
    "Hospital Name": "Northwestern Memorial Hospital",
    "City": "Chicago",
    "License #": "0204458"
  },
  {
    "Hospital Name": "Rush University Medical Center",
    "City": "Chicago",
    "License #": "0205567"
  }
 ]
}

 

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"

 

{
"resource_id":"{THE-RESOURCE-ID}",
"method" : "update",
"records" : [
  {
    "Hospital Name": "Northwestern Memorial Hospital",
    "City": "Evanston",
    "License #": "0204458"
  },
  {
    "Hospital Name": "Rush",
    "City": "Chicago",
    "License #": "0205567"
  }
]
}

 

The response for all of these methods is a JSON dictionary with three keys:

  1. "success": true or false.
  2. "result": the returned result from the function you called.
  3.  "help": the documentation string for the function you called.