Trove

INTRODUCTION

What is Trove?

Find and get over 391,876,505 Australian and online resources:
books, images, historic newspapers, maps, music, archives and more

Trove helps you find and use resources relating to Australia. It’s more than a search engine. Trove brings together content from libraries, museums, archives and other research organisations and gives you tools to explore and build.

(From the Trove website)

The Trove module provides a simple Drupal API around the National Library of Australia's Trove API service.

The Trove module can be used as a standalone API for other modules wishing to use the Trove API service. It provides the following:

• Caching of requests, with user defined cache expiry.
• Storage of API key
• Simple interface and wrapper functions and around the Trove API services.
• Utility functions to return lists of facet, zones, parameters, and other Trove API information.
• Error handling and logging.

For more information on Trove, visit http://trove.nla.gov.au

REQUIREMENTS

• Registry autoload module
• A free Trove API key

INSTALLATION

• Install as you would normally install a contributed Drupal module. See: https://drupal.org/documentation/install/modules-themes/modules-7 for further information.

CONFIGURATION

• Visit https://trove.nla.gov.au/signup to sign up as a registered user. Once registered you can request a free API key.
• Once the Trove module is enabled, visit admin/config/services/trove and enter your API key.
• For more information on using the Trove API, visit

http://help.nla.gov.au/trove/building-with-trove/api

INTEGRATION

Modules that use the Trove module:

• Trovequery: provides Trove views integration.

Using the Trove module API (for developers)

Using the API provided by the Trove module is straightforward once the module is enabled and a valid API key is in place.

Examples

Getting a list of all Trove contributors:

use Drupal\trove\TroveApi;
use Drupal\trove\TroveApiContributor;

$contributors = TroveAPI::factory(TROVE_CONTRIBUTOR);
$contributors->query();
$list = $contributors->parse();

Getting a result set for items in the Trove books zone with the keyword query "fish":

use Drupal\trove\TroveApi;
use Drupal\trove\TroveApiQuery;

$my_search = TroveAPI::factory(TROVE_RESULT);
$my_search->set_filter('zone','book')
   ->set_filter('q','fish')
   ->query();
$list = $my_search->parse();

Get the list of years available for the Sydney Morning Herald and get the dates it was issued in 1926 and 1927:

use Drupal\trove\TroveApi;
use Drupal\trove\TroveApiQueryNewspaperTitle;

$title = TroveAPI::factory(TROVE_NEWSPAPER_TITLE);
$title->setId('35')
   ->setFilter('include','years')
   ->setFilter('range','19260101-19271231')
   ->query();
$list = $title->parse();

Get the full record for a digitised newspaper article:

use Drupal\trove\TroveApi;
use Drupal\trove\TroveApiQueryRecord;

$newspaper = TroveAPI::factory(TROVE_RECORD_NEWSPAPER);
$newspaper->setId('18342701')
   ->setFilter('include','articletext')
   ->setFilter('reclevel','full')
   ->query();
$list = $newspaper->parse();

All public Trove module API methods can be chained.

Other utilities offered by the Trove module include:

// get the trove search zones
$zones = trove_get_zones(); 

// get a list of trove format facets
$formats = trove_get_facets_format();

// get trove availability facets:
$availability = trove_get_facets_availability();

// get the trove category facets:
$category = trove_get_facets_category();

THANKS

Thanks to the National Library of Australia and all of the contributors to Trove for the amazing, vast, and free Trove service. Be sure to acknowledge them if you use this module on your site. See http://trove.nla.gov.au/general/api-powered-by-trove for more information on acknowledging Trove.

FEEDBACK

I'd love to know how people are using this module. I'd also be keen for feature requests as well as co-maintainers. If you are interested, please get in touch!