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:

"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. 

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:

"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"

 

        {
        "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:

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