Skip to content
a Ruby library for building OAI-PMH clients and servers
Latest commit 52aa1cc May 8, 2015 @no-reply no-reply Prepare Release 0.4.0
Failed to load latest commit information.
bin Merge of provider_integration back into trunk Feb 5, 2007
examples Fixing activerecord tests, and adding them as default. Aug 13, 2012
lib Merge pull request #44 from code4lib/oai-record May 8, 2015
test Merge pull request #44 from code4lib/oai-record May 8, 2015
tools reverting accidental trunk commit to rev 810 May 7, 2007
.gitignore Replacing RDoc with YARD. Oct 26, 2012
.yardopts Replacing RDoc with YARD. Oct 26, 2012
Gemfile add test-unit to the gemfile Mar 22, 2015 Allow OAI::Client consumers to pass through additional request header… Mar 22, 2015
Rakefile Replacing RDoc with YARD. Oct 26, 2012


ruby-oai is a Open Archives Protocol for Metadata Harvesting (OAI-PMH) library for Ruby. OAI-PMH is a somewhat archaic protocol for sharing metadata between digital library repositories. If you are looking to share metadata on the web you are probably better off using a feed format like RSS or Atom. If have to work with a backwards digital repository that only offers OAI-PMH access then ruby-oai is your friend.

The OAI-PMH spec defines six verbs (Identify, ListIdentifiers, ListRecords, GetRecords, ListSets, ListMetadataFormat) used for discovery and sharing of metadata.

The ruby-oai gem includes a client library, a server/provider library and a interactive harvesting shell.


The OAI client library is used for harvesting metadata from repositories. For example to initiate a ListRecords request to pubmed you can:

  require 'oai'
  client = '', :headers => { "From" => "" }
  response = client.list_records
  # Get the first page of records
  response.each do |record| 
    puts record.metadata
  # Get the second page of records
  response = client.list_records(:resumption_token => response.resumption_token)
  response.each do |record|
    puts record.metadata
  # Get all pages together (may take a *very* long time to complete)
  client.list_records.full.each do |record|
    puts record.metadata

See {OAI::Client} for more details


The OAI provider library handles serving local content to other clients. Here's how to set up a simple provider:

  class MyProvider < Oai::Provider
    repository_name 'My little OAI provider'
    repository_url  'http://localhost/provider'
    record_prefix 'oai:localhost'
    admin_email 'root@localhost'   # String or Array
    source_model       # Subclass of OAI::Provider::Model

See {OAI::Provider} for more details

Interactive Harvester

The OAI-PMH client shell allows OAI Harvesting to be configured in an interactive manner. Typing oai on the command line starts the shell. After initial configuration, the shell can be used to manage harvesting operations.

See {OAI::Harvester::Shell} for more details


Normally the best way to install oai is as part of your Gemfile:

source :rubygems
gem 'oai'

Alternately it can be installed globally using RubyGems:

$ gem install oai


CC0 - Public Domain

Something went wrong with that request. Please try again.