[ckan-discuss] Examples of how to query CKAN api

Thu Jun 27 09:56:17 BST 2013

> Hi, looking at "examples" in the CKAN documentation at
> http://docs.ckan.org/en/latest/apiv3.html#examples I see that there is in
> fact only one example, and it's simplistic.

The API docs got updated and that link no longer works, you might find
the examples in the new docs slightly better:

http://docs.ckan.org/en/latest/api.html

> It would be good to have some documentation on how to query the api
> with various combinations of search parameters. For example, how do
> you find all datasets published by a certain organization with
> specific tags published between two dates, etc.

Here I think you're talking about the package_search API endpoint
specifically:

http://docs.ckan.org/en/latest/api.html#ckan.logic.action.get.package_search

I agree the `gq` and `sort` parameters of this function are left a bit
mysterious by the docstring. `facet.field` also. They could all do with
a few examples being added to the docstring.

Pull requests are welcome, or if people just want to come up with good
examples and reply to this thread, I'll put them into the docs.

CKAN developers: in general when writing doscstrings, especially ones
for public consumption like action function docstrings, it's good to
have examples values for parameters as well as a description of what the
parameter means. Examples really make it a lot clearer, without them we
tend to leave people guessing.

And for a complex function like package_search, which has multiple
complex parameters that can be combined, I think the main body of the
docstring probably wants a couple of complete examples as well.

I'll add something about this to the docstring standards.