Digital Public Library of America Ruby API Wrapper
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
spec
.coveralls.yml
.gitignore
.ruby-version
.travis.yml
DPLibrary.gemspec
Gemfile
LICENSE.txt
README.md
Rakefile

README.md

Build Status Code Climate Coverage Status

DPLibrary

A simple ruby API wrapper around the Digital Public Library of America

Installation

Add this line to your application's Gemfile:

gem 'DPLibrary'

And then execute:

$ bundle

Or install it yourself as:

$ gem install DPLibrary

Configuration

  1. Acquire an API KEY from dp.la. To do this, simply run the following command from your terminal (replace YOUR_EMAIL with your email):
curl -v -XPOST http://api.dp.la/v2/api_key/YOUR_EMAIL@example.com

You will receive an email with an api key (should take less than 5 minutes).

  1. Before making any api calls you will need to set your api key in your application. To do that, do the following:
DPLibrary.api_key = '<API KEY GOES HERE>'

If you are using a rails app, putting this in a config/initializer makes the most sense.

Usages

After setting your api_key to DPLibrary.api_key, it's time to start querying the DPLA!!

For reference, you should glance at the DPLA API Reference.

Let's get started!

@documents_collection = DPLibrary::DocumentCollection.new({q: 'chicken'})
@documents_collection.count # => returns the total count of your query.
@documents_collection.limit # => the limit of documents per query
@documents_collection.offset # => pagination offset in results
@documents_collection.documents # => Returns an array of document objects
@document = DPLibrary::DocumentCollection.new({q: 'chicken'}).documents.first
@document.collection # => returns a collection object
@document.original_record # => returns an original record object

## Attributes for documents
:id, :url, :source, :title, :description, :subject, :language, :format,
:type, :publisher, :creaetor, :provider, :collection, :intermediate_provider,
:score, :original_record

You can retrieve multiple records by ID by passing an array for the :id parameter, like this:

@documents_collection = DPLibrary::DocumentCollection.new({id: ['id1', 'id2']})

Now there are many types of parameters you can pass in the DocumentCollection initialize method. For a complete list, check out the DPLA API Reference.

For the lazy, here is a brief list of what those params can be. It's pretty straightforward what the params do.

q # => query string 
sourceResource.id
sourceResource.contributor
sourceResource.date.begin
sourceResource.date.end
sourceResource.extent
sourceResource.language.name
sourceResource.language.iso639
sourceResource.format
sourceResource.stateLocatedIn.name
sourceResource.stateLocatedIn.iso3166-2
sourceResource.spatial.name
sourceResource.spatial.country
sourceResource.spatial.region
sourceResource.spatial.county
sourceResource.spatial.state
sourceResource.spatial.city
sourceResource.spatial.iso3166-2
sourceResource.spatial.coordinates
sourceResource.subject.@id
sourceResource.subject.type
sourceResource.subject.name
sourceResource.temporal.begin
sourceResource.temporal.end
sourceResource.title
sourceResource.type
hasView.@id
hasView.format
isPartOf.@id
isPartOf.name
isShownAt
object
provider.@id
provider.name
intermediate_provider

ToDo's

  • Write Tests
  • Create fixtures for tests
  • Dry up lib files
  • Write up collection.find method for querying collections

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request