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 = 
{
  :search => 'records/${version}.xml/'
}
ARGS = 
{
  :search => Set.new([
    :search_text,
    :api_key,
    :num_results,
    :start,
    :sort,
    :direction,
    :facets,
    :facet_num_results,
    :facet_start
  ])
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, base_url = 'http://api.digitalnz.org', version = 'v1') ⇒ 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



50
51
52
53
54
 
# File 'lib/dnz/client.rb', line 50

def initialize(api_key, base_url = 'http://api.digitalnz.org', version = 'v1')
  @api_key = api_key
  @base_url = base_url
  @version = version
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

The dnz API key



17
18
19
 
# File 'lib/dnz/client.rb', line 17

def api_key
  @api_key
end

#base_url ⇒ Object (readonly)

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



19
20
21
 
# File 'lib/dnz/client.rb', line 19

def base_url
  @base_url
end

#version ⇒ Object (readonly)

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



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

def version
  @version
end

Instance Method Details

#categories ⇒ Object

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

Example

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



63
64
65
 
# File 'lib/dnz/client.rb', line 63

def categories
  search('*:*', :facets => 'category', :facet_num_results => 100).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.



98
99
100
101
102
103
104
105
 
# File 'lib/dnz/client.rb', line 98

def fetch(api, options = {})
  validate_options(api, options)

  options = options.reverse_merge(:api_key => self.api_key)
  qs = options.map{|k,v| '%s=%s' % [k,v] }.join('&')
  url = self.base_url + '/' + APIS[api].gsub('${version}', self.version) + '?' + qs
  open(url)
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.

Example

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



80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/dnz/client.rb', line 80

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

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

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