Legacy APIs

Warning

The legacy APIs documented in this section are provided for backwards-compatibility, but support for new CKAN features will not be added to these APIs. These endpoints will be removed in the future.

Note

The REST API was deprecated in CKAN v2.0 and removed starting from CKAN v2.8.

Search API

Search resources are available at published locations. They are represented with a variety of data formats. Each resource location supports a number of methods.

The data formats of the requests and the responses are defined below.

Search Resources

Here are the published resources of the Search API.

Search Resource

Location

Dataset Search

/search/dataset

Resource Search

/search/resource

Revision Search

/search/revision

Tag Counts

/tag_counts

See below for more information about dataset and revision search parameters.

Search Methods

Here are the methods of the Search API.

Resource

Method

Request

Response

Dataset Search

POST

Dataset-Search-Params

Dataset-Search-Response

Resource Search

POST

Resource-Search-Params

Resource-Search-Response

Revision Search

POST

Revision-Search-Params

Revision-List

Tag Counts

GET

Tag-Count-List

It is also possible to supply the search parameters in the URL of a GET request, for example /api/search/dataset?q=geodata&allfields=1.

Search Formats

Here are the data formats for the Search API.

Name

Format

Dataset-Search-Params Resource-Search-Params Revision-Search-Params

{ Param-Key: Param-Value, Param-Key: Param-Value, … } See below for full details of search parameters across the various domain objects.

Dataset-Search-Response

{ count: Count-int, results: [Dataset, Dataset, … ] }

Resource-Search-Response

{ count: Count-int, results: [Resource, Resource, … ] }

Revision-List

[ Revision-Id, Revision-Id, Revision-Id, … ] NB: Ordered with youngest revision first. NB: Limited to 50 results at a time.

Tag-Count-List

[ [Name-String, Integer], [Name-String, Integer], … ]

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.

title, tags, notes, groups, author, maintainer, update_frequency, or any ‘extra’ field name e.g. department

Search-String

title=uk&tags=health
department=environment
tags=health&tags=pollution
tags=river%20pollution

Search in a particular a field.

order_by

field-name (default=rank)

order_by=name

Specify either rank or the field to sort the results by

offset, limit

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

offset=40&limit=20

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&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:

curl 'http://thedatahub.org/api/search/dataset?qjson=\{"author":"The%20Stationery%20Office%20Limited"\}'

Revision Parameters

Param-Key

Param-Value

Example

Notes

since_time

Date-Time

since_time=2010-05-05T19:42:45.854533

The time can be less precisely stated (e.g 2010-05-05).

since_id

Uuid

since_id=6c9f32ef-1f93-4b2f-891b-fd01924ebe08

The stated id will not be included in the results.

Util API

The Util API provides various utility APIs – e.g. auto-completion APIs used by front-end javascript.

All Util APIs are read-only. The response format is JSON. Javascript calls may want to use the JSONP formatting.

dataset autocomplete

There an autocomplete API for package names which matches on name or title.

This URL:

/api/2/util/dataset/autocomplete?incomplete=a%20novel

Returns:

{"ResultSet": {"Result": [{"match_field": "title", "match_displayed": "A Novel By Tolstoy (annakarenina)", "name": "annakarenina", "title": "A Novel By Tolstoy"}]}}

tag autocomplete

There is also an autocomplete API for tags which looks like this:

This URL:

/api/2/util/tag/autocomplete?incomplete=ru

Returns:

{"ResultSet": {"Result": [{"Name": "russian"}]}}

resource format autocomplete

Similarly, there is an autocomplete API for the resource format field which is available at:

/api/2/util/resource/format_autocomplete?incomplete=cs

This returns:

{"ResultSet": {"Result": [{"Format": "csv"}]}}

munge package name

For taking an readable identifier and munging it to ensure it is a valid dataset id. Symbols and whitespeace are converted into dashes. Example:

/api/util/dataset/munge_name?name=police%20spending%20figures%202009

Returns:

"police-spending-figures-2009"

munge title to package name

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:

/api/util/dataset/munge_title_to_name?title=police:%20spending%20figures%202009

Returns:

"police-spending-figures-2009"

munge tag

For taking a readable word/phrase and munging it to a valid tag (name). Symbols and whitespeace are converted into dashes. Example:

/api/util/tag/munge?tag=water%20quality

Returns:

"water-quality"

Status Codes

Standard HTTP status codes are used to signal method outcomes.

Code

Name

200

OK

201

OK and new object created (referred to in the Location header)

301

Moved Permanently

400

Bad Request

403

Not Authorized

404

Not Found

409

Conflict (e.g. name already exists)

500

Service Error