#DPyLA - A Python client for the DPLA API
The DPLA (Digital Public Library of America) is an aggregated digital library, archive and museum collections. What really makes it stand out is its awesome API. This python library is a wrapper around that API, making it easier to interact with.
Tested and working with Python 2.7, 3.2, and 3.3
Depends on the awesome Requests package
####Getting started
pip install dpla
Then fire up your fave python interpreter and:
>>> from dpla.api import DPLA
Then create the dpla object with your DPLA API key.
>>> dpla = DPLA('your-key-here')
If you don't have a DPLA API key yet, you can follow their instructions or simply:
>>> DPLA.new_key("[email protected]")
And then check you email.
Now, let's create your first search
>>> result = dpla.search('chicken')
Records returned are in result.items
>>> result.items[0] #gets you a multidimensional dictionary of the first result. Much omitted below for brevity.
{u'@context': {u'@vocab': u'https://purl.org/dc/terms/',
...
u'@id': u'https://dp.la/api/items/bc944ed8339050bbbcf25f3838895a03',
u'_id': u'kentucky--https://kdl.kyvl.org/catalog/xt7sf7664q86_1755_1',
...
u'hasView': {u'@id': u'https://nyx.uky.edu/dips/xt7sf7664q86/data/1/016_0006_p/016_0006/016_0006.jpg'},
...
u'sourceResource': {u'collection': [],
u'creator': u'University of Kentucky',
u'language': [{u'iso639_3': u'eng', u'name': u'English'}],
u'stateLocatedIn': [{u'name': u'University of Kentucky'}],
u'subject': [{u'name': u'Agriculture-United States'},
{u'name': u'Animal Culture-United States'},
{u'name': u'Photographs of animals'},
{u'name': u'Photographs of livestock'}],
u'title': u'Chicken'}}
You can also find out how many records were found matching that criteria
>>> result.count #
925
But you don't have all 925 records. Unless you tell it otherwise, DPLA API sets a limit of ten records returned.
>>> results.limit
10 #
But if you want more, it's easy. Just do this:
>>> result = dpla.search(q="chicken", page_size=100)
>>> result.limit
100 # More records, YAY!
If you have the id of of a record you want to retrieve, or a series of IDs, you can use the fetch_by_id
method. Just pass an array of IDs and it will return all fields for those records.
>>> result = dpla.fetch_by_id(["93583acc6425f8172b7b506f44a32121"])
>>> result.items[0]["@id"]
'https://dp.la/api/items/93583acc6425f8172b7b506f44a32121'
Or multiple IDs
>>> ids = ["93583acc6425f8172b7b506f44a32121","fe47a8b71de4c136fe115a19ead13e4d" ]
>>> result = dpla.fetch_by_id(ids)
>>> result.count
2
###More Options The DPLA gives you a lot of options for tailoring your search to get back exactly what you want. DPyLA helps make creating those fine grained searches easier (easier than creating your own 250-charcter url anyway!)
####Query A standard keyword query that searches across all fields. Just enter a string with your search terms. If combining with other search parameters, make sure it is the first param passed.
>>> result = dpla.search("chicken")
>>> result = dpla.search("chicken man")
>>> result = dpla.search("chicken", fields=["sourceResource.title"])
####Search within specific fields
You can search within specific fields to narrow your search.
Pass a dictionary of key / value pairs to the searchFields
parameter, where field names are the keys and search values are the value.
>>> fields = {"sourceResource.title" : "crime", "sourceResource.spatial.state" : "Illinois"}
>>> result = dpla.search(searchFields=fields)
####Return Fields
You can also choose what fields should be included with returned records, so you only get back what you need.
Pass a list or tuple of filed names to the fields
parameter
result = dpla.search("chicken", fields=["sourceResource.title"])
>>> result.items[0]
{u'sourceResource.title': u'Chicken'}
####Facets Get back a list of the most common terms within a field for this set of results. See the DPLA facet docs for more info
>>> result = dpla.search("chicken", facets=["sourceResource.subject"])
>>> result.facets[0]
{u'sourceResource.subject.name': {u'_type': u'terms',
u'missing': 151,
u'other': 3043,
u'terms': [{u'count': 88, u'term': u'Poultry'},
{u'count': 77, u'term': u'Social Life and Customs'},
{u'count': 64, u'term': u'Agriculture'},
{u'count': 60, u'term': u'People'},
{u'count': 53, u'term': u'Chickens'},
{u'count': 51, u'term': u'Restaurants'},
{u'count': 51, u'term': u'Ethnology'},
{u'count': 41, u'term': u'Domestic Animals'},
{u'count': 39, u'term': u'Customs'},
{u'count': 32, u'term': u'Festivals'},
....
####Spatial Facet You can also facet by distance from a set of geo-coordinates. It requires extra work in the search url, so it is a seperate parameter. Pass a length 2 list of [lat, lng] to the parameter spatial_facet
>>> result = dpla.search("chicken", spatial_facet=[37,-48])
>>> result.facets[0]
{u'sourceResource.spatial.coordinates': {u'_type': u'geo_distance',
u'ranges': [{u'from': 1200.0,
u'max': 1296.205781266114,
u'mean': 1277.6015482976388,
u'min': 1265.9189942665018,
u'to': 1300.0,
u'total': 6388.007741488194,
u'total_count': 5},
...
]}
###Facet Size Normally, asking for facets will return A LOT OF FACETS! If you only want a few, this is for you. Pass an int to the paramters facet_size.
>>> result = dpla.search("chicken", facets=["sourceResource.subject"], facet_size=2)
>>> result.facets[1]
{u'sourceResource.subject.name': {u'_type': u'terms',
u'missing': 151,
u'other': 4097,
u'terms': [{u'count': 69, u'term': u'Poultry'},
{u'count': 47, u'term': u'Social Life and Customs'}],
u'total': 4213}}
####Sort How do you want the records sorted? Pass a string field name to the sort parameter
result = dpla.search("chicken", sort="sourceResource.title")
####Spatial Sort
You can alse sort by distance from a geo-coordinate. Pass the length 2 tuple of [lat, lng] to the spatial_sort parameter
>>> result = dpla.search("chicken", spatial_sort=[37, -48])
####Page size By Default, only ten records are returned per request. To increase that number, pass an integer (or string integer) to page_size paramter. The upper limit is 100 per request.
>>> result = dpla.search(q="chicken", page_size=100)
####Page If that’s not enough, you can get the next ten items incrementing the page parameter (it’s one-indexed).
>>> result = dpla.search(q="chicken", page_size=100, page=2)
##Limitations This project is still in its infancy. It ain't purrfect.
- Right now, the client only does items search. Collections search
and individual item fetchto come eventually. - It does not do a great job catching exceptions, so be warned!
- Test coverage is limited.
##License
GPLV2. See license.txt