There are two versions of the legacy APIs. When the API returns a reference to
an object, version 1 of the API will return the name of the object (e.g.
"river-pollution"), whereas version 2 will return the ID of the object
(e.g. "a3dd8f64-9078-4f04-845c-e3f047125028"). Tag objects are an
exception, tag names are immutable so tags are always referred to with their
name.

You can specify which version of the API to use in the URL. For example,
opening this URL in your web browser will list demo.ckan.org’s datasets using
API version 1:

Dataset names can change, so to reliably refer to the same dataset over time,
you will want to use the dataset’s ID and therefore use API v2. Alternatively,
many people prefer to deal with Names, so API v1 suits them.

When posting parameters with your API requests, you can refer to objects by
either their name or ID, interchangeably.

To send request data, create the JSON-format string (encode in UTF8) put it in the request body and send it using PUT or POST.

Response data will be in the response body in JSON format.

Notes:

When you update an object, fields that you don’t supply will remain as they were before.

To delete an ‘extra’ key-value pair, supply the key with JSON value: null

When you read a dataset, some additional information is supplied that you cannot modify and POST back to the CKAN API. These ‘read-only’ fields are provided only on the Dataset GET. This is a convenience to clients, to save further requests. This applies to the following fields:

Key

Description

id

Unique Uuid for the Dataset

revision_id

Latest revision ID for the core Package data (but is not affected by changes to tags, groups, extras, relationships etc)

metadata_created

Date the Dataset (record) was created

metadata_modified

Date the Dataset (record) was last modified

relationships

info on Dataset Relationships

ratings_average

ratings_count

ckan_url

full URL of the Dataset

download_url (API v1)

URL of the first Resource

isopen

boolean indication of whether dataset is open according to Open Knowledge Definition, based on other fields

The Dataset and Revision data formats are as defined in Model Formats.

Dataset Parameters

Param-Key

Param-Value

Examples

Notes

q

Search-String

q=geodata

q=government+sweden

q=%22drug%20abuse%22

q=tags:”river pollution”

Criteria to search the dataset
fields for. URL-encoded search
text. (You can also concatenate
words with a ‘+’ symbol in a
URL.) Search results must contain
all the specified words. You
can also search within specific
fields.

qjson

JSON encoded
options

[‘q’:’geodata’]

All search parameters can be
json-encoded and supplied to this
parameter as a more flexible
alternative in GET requests.

Pagination options. Offset is the
number of the first result and
limit is the number of results to
return.

all_fields

0 (default)
or 1

all_fields=1

Each matching search result is
given as either a dataset name
(0) or the full dataset record
(1).

Note

filter_by_openness and filter_by_downloadable were dropped from CKAN version 1.5 onwards.

Note

Only public datasets can be accessed via the legacy search API, regardless of
the provided authorization. If you need to access private datasets via the
API you will need to use the package_search method of the API guide.

Resource Parameters

Param-Key

Param-Value

Example

Notes

url, format,
description

Search-String

url=statistics.org

format=xls

description=Research+Institute

Criteria to search the dataset
fields for. URL-encoded search
text. This search string must be
found somewhere within the field
to match.
Case insensitive.

qjson

JSON encoded
options

[‘url’:’www.statistics.org’]

All search parameters can be
json-encoded and supplied to this
parameter as a more flexible
alternative in GET requests.

hash

Search-String

hash=b0d7c260-35d4-42ab-9e3d-c1f4db9bc2f0

Searches for an match of the
hash field. An exact match or
match up to the length of the
hash given.

all_fields

0 (default)
or 1

all_fields=1

Each matching search result is
given as either an ID (0) or the
full resource record

offset, limit

result-int
(defaults:
offset=0,
limit=20)

offset=40&amp;limit=20

Pagination options. Offset is the
number of the first result and
limit is the number of results to
return.

Note

Powerful searching from the command-line can be achieved with curl and the qjson parameter. In this case you need to remember to escapt the curly braces and use url encoding (e.g. spaces become %20). For example:

For taking a title of a package and munging it to a readable and valid dataset id. Symbols and whitespeace are converted into dashes, with multiple dashes collapsed. Ensures that long titles with a year at the end preserves the year should it need to be shortened. Example: