GitHub - bibliotechy/DPyLA: A python client for the DPLA API Skip to content Sign up Why GitHub? Features → Mobile → Actions → Codespaces → Packages → Security → Code review → Project management → Integrations → GitHub Sponsors → Customer stories → Security → Team Enterprise Explore Explore GitHub → Learn & contribute Topics → Collections → Trending → Learning Lab → Open source guides → Connect with others The ReadME Project → Events → Community forum → GitHub Education → GitHub Stars program → Marketplace Pricing Plans → Compare plans → Contact Sales → Nonprofit → Education → In this repository All GitHub ↵ Jump to ↵ No suggested jump to results In this repository All GitHub ↵ Jump to ↵ In this user All GitHub ↵ Jump to ↵ In this repository All GitHub ↵ Jump to ↵ Sign in Sign up {{ message }} bibliotechy / DPyLA Watch 5 Star 35 Fork 5 A python client for the DPLA API GPL-2.0 License 35 stars 5 forks Star Watch Code Issues 0 Pull requests 1 Actions Projects 0 Security Insights More Code Issues Pull requests Actions Projects Security Insights master 4 branches 7 tags Go to file Code Clone HTTPS GitHub CLI Use Git or checkout with SVN using the web URL. Work fast with our official CLI. Learn more. Open with GitHub Desktop Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit   Git stats 63 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time dpla     tests     .gitignore     .travis.yml     README.md     license.txt     requirements.txt     setup.cfg     setup.py     View code README.md DPyLA - A Python client for the DPLA API under active development! 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.3, 3.4, and 3.5. Dependencies Depends on the awesome Requests package ####Getting started First, install the module: 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 run the following: >>> DPLA.new_key("your.email.address@here.com") And then check your 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'http://purl.org/dc/terms/', # ... u'@id': u'http://dp.la/api/items/bc944ed8339050bbbcf25f3838895a03', u'_id': u'kentucky--http://kdl.kyvl.org/catalog/xt7sf7664q86_1755_1', # ... u'hasView': {u'@id': u'http://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! You can also use the all_records() helper method to get back a generator that allows you to iterate through all of the records in your result list. >>> result = dpla.search(q="chicken", page_size=100) >>> result.count 925 >>> for item in result.all_records(): print(item["sourceResource"]["title"]) "Chicken" "Chicken and cow" "Chicken and pig" # ...(922 more titles) "Last of the Chicken records" Fetch item(s) by ID 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"] 'http://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 parameter 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 also 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 the page_size parameter. 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 fetch to come eventually. It does not do a great job catching exceptions, so be warned! Test coverage is limited. License GPLV2. See license.txt About A python client for the DPLA API Resources Readme License GPL-2.0 License Releases 7 Use https Latest Jun 2, 2016 + 6 releases Packages 0 No packages published Contributors 4         Languages Python 100.0% © 2021 GitHub, Inc. Terms Privacy Security Status Docs Contact GitHub Pricing API Training Blog About You can’t perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.