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
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.
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’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.
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 more help
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.