pyDnz - A Python client for the DigitalNZ API

DigitalNZ aims to make New Zealand digital content more useful. DigitalNZ provides an API to help developers people find digital material from libraries, museums, government departments, publicly funded organisations, the private sector, and community groups. This python library is a wrapper around that API, making it easier to interact with.

pyDNZ is based on DPyLA - A Python client for the The DPLA (Digital Public Library of America).

Should work in Python 2.6+ and Python 3. See the DigitalNZ API v3 docs for more information about the API.

Dependencies

Depends on the Requests package.

Getting started

sudo python setup.py install

Start a python interpreter and type:

>>> from dnz.api import Dnz

Then create the dnz object with your DigitalNZ API key.

>>> dnz = Dnz('YOUR_API_KEY')

Now, create your first search. Let's look for items that mention kiwis and tuis.

>>> result = dnz.search('kiwi tui')

Matching records returned are in result.records as a dictionary of values. Let's take a look. First import the standard pretty printer to get a sense of the response structure.

>>> from pprint import pprint as pp

And now pretty print the record results.

>>> pp(result.records)

You can also find out how many records were found matching that criteria with a result_count.

>>> print result.result_count
6323

Sometimes you only want to see certain fields in your result. Feed a list of fields as an array or tuple.

>>> result = dnz.search('kiwi tui', fields=['id', 'title', 'collection', 'content_partner'])
>>> pp(result.records)

Pagination

See more or fewer results using the per_page parameter (maximum value of 100) and paginate through with the page paramater.

>>> result = dnz.search('kiwi tui', per_page=50, page=10, fields=['id', 'title', 'collection', 'content_partner'])
>>> pp(result.records)

Geo-search

Search for results within a specific [North, West, South, East] bounding box.

>>> r1 = dnz.search('kiwi')
>>> print(r1.result_count)
>>> r2 = dnz.search('kiwi', geo_bbox=[-41,174,-42,175])
>>> print(r2.result_count)

AND / OR scoping

You can scope your search to certain field values using '_and' and '_or' statements. Supply a dictionary where the values your fields of interest and the values are a list of attributes to limit by.

>>> result = dnz.search(_or={'category':['Videos', 'Images']}, _and={'content_partner':['Ministry for Culture and Heritage']})
>>> pp(result.records) 

Facets

Get back a list of the most common terms within a field for this set of results as result.facets. See the DigitalNZ API v3 docs for more info.

>>> result = dnz.search('kiwi tui', facets=['year', 'collection'])
>>> pp(result.facets)

You can also increase the number of facets returned (up to a maximum of 150) with the facets_per_page parameter.

>>> result = dnz.search('kiwi tui', facets=['year', 'collection'], facets_per_page=30)
>>> pp(result.facets)

Iterate through facet results with the facets_page parameter.

>>> r1 = dnz.search('kiwi tui', facets=['year', 'collection'], facets_page=1)
>>> r2 = dnz.search('kiwi tui', facets=['year', 'collection'], facets_page=2)
>>> pp(r1.facets)
>>> pp(r2.facets)

Sort

Pass a sortable field along with the sort field and a direction to order the result set. Sortable fields are 'category', 'content_partner', 'date', 'syndication_date', 'title'. Directions can be 'asc' or 'desc'.

result = dnz.search('penguin', sort='date', direction='desc', fields=['title', 'date'])
pp(result.records)

Limitations

Early days. Still a fair few rough edges.

• Does not support without[field] searches... yet.
• Oh, you know... all that other stuff.

License

GPLV2. See license.txt