Class: DNZ::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dnz/client.rb

Overview

This is a simple client for accessing the digitalnz.org API for searching New Zealand’s digital content. It provides access to search results and facet information.

Author

Jeremy Wells, Boost New Media (www.boost.co.nz)

Copyright

Copyright © 2009 Boost New Media

License

MIT

Constant Summary collapse

APIS =

API URLS

{
  :search => 'records/${version}.xml/',
  :custom_search => 'custom_searches/${version}/${custom_search}.xml',
  :custom_search_preview => 'custom_searches/${version}/test.xml',
  :record => 'records/${version}/${id}.xml'
}
ARGS =

API Arguments

{
  :v1 => {
    :search => Set.new([
      :search_text,
      :api_key,
      :num_results,
      :start,
      :sort,
      :direction,
      :facets,
      :facet_num_results,
      :facet_start
    ]),
    :custom_search => Set.new([
      :custom_search,
      :search_text,
      :api_key,
      :num_results,
      :start,
      :sort,
      :direction
    ])
  },
  :v2 => {
    :search => Set.new([
      :search_text,
      :api_key,
      :num_results,
      :start,
      :sort,
      :direction,
      :facets,
      :facet_num_results,
      :facet_start
    ]),
    :custom_search => Set.new([
      :custom_search,
      :search_text,
      :api_key,
      :num_results,
      :start,
      :sort,
      :direction,
      :facets,
      :facet_num_results,
      :facet_start
    ]),
    :custom_search_preview => Set.new([
      :api_key
    ])
  }      
}
FACETS =

List of available facets that can be passed to search

[
  :category, :content_partner, :creator, :language, :rights, :century, :decade, :year
]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, version = 'v1', base_url = 'http://api.digitalnz.org') ⇒ Client

Constructor method for the Client class. An API key must be provided. The base url and version default to “api.digitalnz.org” and “v1”.

Example

client = DNZ::Client.new('abcdefghijklmnoq')
search = client.search('some text')
search.results.each do |result|
  puts result.title
end



114
115
116
117
118
119
120
121
122
 
# File 'lib/dnz/client.rb', line 114

def initialize(api_key, version = 'v1', base_url = 'http://api.digitalnz.org')
  @api_key = api_key
  @base_url = base_url
  @version = version
  
  if @base_url =~ /^(.*)\/$/
    @base_url = $1
  end
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

The dnz API key



32
33
34
 
# File 'lib/dnz/client.rb', line 32

def api_key
  @api_key
end

#base_url ⇒ Object (readonly)

The base URL (defaults to api.digitalnz.org)



34
35
36
 
# File 'lib/dnz/client.rb', line 34

def base_url
  @base_url
end

#version ⇒ Object (readonly)

The version of the API to use (defaults to v1)



36
37
38
 
# File 'lib/dnz/client.rb', line 36

def version
  @version
end

Class Method Details

.connect(*args) ⇒ Object 



22
23
24
 
# File 'lib/dnz/client.rb', line 22

def connect(*args)
  self.connection = self.new(*args)
end

.method_missing(method, *args, &block) ⇒ Object 



26
27
28
 
# File 'lib/dnz/client.rb', line 26

def method_missing(method, *args, &block)
  self.connection.send(method, *args, &block)
end

Instance Method Details

#categories(options = {}) ⇒ Object

Get a list of all categories using the ‘category’ facet.

Options

  • :custom_search - The name of a custom search created at digitalnz.org

Example

categories = client.categories
categories.each do |category|
  puts category.name
end



135
136
137
138
 
# File 'lib/dnz/client.rb', line 135

def categories(options = {})
  options = options.merge(:facets => 'category', :facet_num_results => 100, :num_results => 0)
  search('*:*', options).facets['category'].values
end

#fetch(api, options = {}) ⇒ Object

Make a direct call to the digitalnz.org API.

  • api - The api call to make. This must be listed in the APIS constant.

  • options - A hash of options to pass to the API call. These options must be defined in the ARGS constant.



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/dnz/client.rb', line 181

def fetch(api, options = {})
  options = options.dup
  
  unless options.delete(:validate) === false
    validate_options(api, options)
  end

  options = options.reverse_merge(
    :api_key => self.api_key,
    :version => self.version
  )
  
  url = create_url(api, options)
  
  begin
    open(url)
  rescue OpenURI::HTTPError => e
    if e.to_s =~ /^401/
      raise InvalidApiKeyError.new(self.api_key)
    else
      raise
    end
  end
end

#search(text, options = {}) ⇒ Object

Run a search using the digitalnz.org API.

Options

  • :num_results - The number of results to return in this call. Defaults to 20.

  • :start - The starting offset of the results.

  • :facets - The facets to return for this search.

  • :filter - A hash of filters to apply to the results. Filters can be a string value or an array of string values.

  • :custom_search - The name of a custom search created at digitalnz.org

Example

search = client.search('rugby', :num_results => 50)
search.results.each_with_index do |result, index|
  puts "#{index+1}: #{result.title}"
end

Filter example

This example will search for rugby items with the category Images or Web pages.

search = client.search('rugby', :filter => {:category => ['Images', 'Web pages']})



162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/dnz/client.rb', line 162

def search(text, options = {})
  options.reverse_merge!(
    :search_text => text,
    :num_results => 20,
    :start => 0,
    :filter => {}
  )

  # Select the correct page
  page = options.delete(:page)
  options[:start] = (page-1) * options[:num_results] if page

  DNZ::Search.new(self, options)
end