GovHack tips & tricks

Thinking about using Trove data in your GovHack entry? Here’s some things you should know.

Trove has a free, public API

Most of the data in Trove is available in machine-readable form through our API. You’ll need an API key to get started, but don’t worry, the process is automatic for non-commercial projects. Find out more from our API Overview.

One API — hundreds of collections

Trove is a collection of collections, it brings together resources from hundreds of Australian libraries, archives, museums, universities, research organisations, government agencies and more! So if you want to include cultural resources in your project, Trove is a great place to start!

You can even use the Trove API to retrieve a list of organisations that contribute collection data. Once you know an organisation’s identifier (we call it a NUC), you can use it to construct queries limited to their collection. For example, here’s all the theses from ANU’s institutional respository (nuc ANU:IR).

All these collections contain a wonderful, rich variety of resources — books, photographs, objects, reports, ephemera, videos, radio broadcasts and much, much more. Have a look Inside Trove for more details and examples.

Trove aggregates metadata, not objects

Trove currently provides access to more than 400 million resources. But in most cases what we deliver through the API is metadata about the resource, rather than its complete content. Usually there’ll be standard descriptive information as well as a link to more details on the contributing organisation’s website. Often there’ll be a url for a thumbnail image. For example, here’s the API record for a cartoon from the State Library of Queensland.

You can also retrieve user-contributed content such as comments and tags. Have a look at this tagged photograph from the State Library of Victoria.

The API Technical Guide includes full details on the structure of Trove’s metadata records.

Zones, works and versions

Trove’s content is divided into 10 zones. You’ll need to provide a zone parameter when you’re using the API to search the collections — use ‘all’ if you want results from every available zone.

Within zones, resources are wrapped up in ‘works’. Works are metadata containers that can bring together multiple versions of a particular resource, such as all the editions of a book. Basic metadata is available at the work level, but you can get more information about each individual version by including the ‘include=workVersions’ parameter.

API results are structured hierarchically by zone, work and version. So it’s useful to understand how they fit together.

And then there’s the newspapers

Newspapers. Lots of them. Trove provides access to more than 160 million newspapers articles from close to 1000 different newspaper titles, mostly dating from 1803 to 1954. The possibilities are endless.

In this case the API can deliver the full OCR’d text of every article, as well as the metadata — just add the ‘include=articletext’ parameter to your query. Here’s the text of an article about Clement Wragge, the Queensland meteorologist.

Start exploring

The easiest way to learn about the Trove API is to play around in our experimental API Console. All the API links in this page will open in the Console where you can modify parameters and see what happens.

Once you understand the basics you can dive into the detailed API Technical Guide.

You might also like to browse through some applications, experiments and examples using the API.

Grabbing thumbnails

You’ll often want to grab thumbnail images of resources to display in your own application. Have a look at Trove Mosaic and Culture Collage for examples of what’s possible using Trove’s pictures zone. It’s not hard to do, but there are a few tricks.

First of all, there’s currently no way of limiting your search to return only records that include a thumbnail link. If you set your query to retrieve resources that are freely available online using the ‘l-availability=y/f’ parameter, there’s a good chance there’ll be a thumbnail — but there’s no guarantee. You’ll have to inspect each record to be sure.

Once you have a record you need to do a bit of extra work to check for a thumbnail. The ‘identifier’ field includes an array of links to related resources such as web pages and thumbnails. Here’s an example. You’ll need to loop through all the identifiers looking for one that has the ‘type’ of ‘url’ and the ‘linktype’ of ‘thumbnail’.

Sometimes collections of images are grouped into works. To get all the thumbnails for images in a collection you'll need to add 'include=workVersions,links' parameter and then loop through all the versions, extracting the thumbnail links from the identifier field.

Yes, we know that this is unnecessarily complicated and we hope to make it easier in future versions of the API. 

Pre-packaged data

The API delivers current data direct from the Trove database. But if you feel like something a bit more processed in your data diet you could have a look at these CSV files that include details of Radio National programs harvested using the Trove API.

For something a little more exotic, try the Face API which delivers around 4,000 faces extracted from Trove newspaper articles using OpenCV. You can also download the complete set of faces.

For more help

If you'd like more information about the Trove API the first place to check is the Building with Trove help zone and, in particular, the detailed API Technical Guide.

If you can't find what you need, you can start a thread in the API section of the Trove Forum, or ask the Trove team for help. You can also contact us at @TroveAustralia.

Over the GovHack weekend we'll be keeping an eye on the Trove Forum and on Twitter -- so feel free to fire questions at us.

Tim Sherratt (@wragge) from the Trove Management Team will be lurking at one or more GovHack nodes in Sydney and he's always happy to talk metadata.