API – Technical Guide

Contents

  1. Introduction
  2. Search
  3. Get metadata records
  4. Look up associated data
  5. Appendices

 

1. Introduction

A basic overview of the Trove API can be found here.

The Trove API has three main operations:

By default you will receive an XML response, but JSON is also available using the “encoding” parameter.

If you want to use the Trove API for something it doesn’t yet support, let us know.

 

1.1 What is not available through the API?

Some information included in Trove is not accessible through the API:

  • MARC records. We are not authorised to distribute the vast majority of full MARC records in Trove. Instead, we have made a citation-level modified Dublin Core record available.
  • Full text of articles from the Australian Women’s Weekly.
  • Book cover art (as we are not authorised to distibute these links).

Two zones have also been excluded for now – “People and Organisations” and “Archived Websites”. A separate SRU interface for accessing people and organisations is available.

The API does not provide any information about records that have been deleted from Trove. If you have harvested records from Trove you should periodically delete all of these records and re-harvest them. (Note that not all contributors to Trove supply information about records that have been deleted from their systems. In these cases there may be a significant delay before deleted records are removed from Trove.)

 

2. Search

Search Trove newspaper articles, lists and works. (Works are made up of “versions”. They can be books, images, maps, music, sound, video, archives, journal articles…) Archived websites, people and organisations have not been included at this point.

A simple search request looks basically like this: http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=<ZONE NAME>&q=<YOUR SEARCH TERMS>

As this request is a URL, any values (the bits between the = and the next &) may need to be URL encoded when used within your code. To do this,  replace all reserved characters with the appropriate URL encoding. For example, instead of a space between search terms, use “%20″. When cutting and pasting into a browser the URL may work without being URL encoded.

You must choose one or more zones to search. You can add other parameters if you want to do something more complicated. Advanced search functionality is available through the “q” and “l-<facet-name>” parameters.

By default, you will only get a brief metadata record that does NOT include information like tags, comments, full text, library holdings, links etc. If you want this information, you will need to use the reclevel and include parameters which are described below. If you don’t want this information for every record in your results, you can retrieve metadata for individual records instead.

As a general principle, it is better to only ask the API for the information you need – this will give you and all the other Trove users a more responsive service.

 

2.1 Examples

Don’t forget that the search terms and other values need to be URL encoded when used within your code. For example, separate multiple search terms with %20 or + rather than a space.

Limiting the search

The relevant part of the URL is shown in bold.

Description Example URL
Single word search http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=tangled
Multi word search
(separate multiple terms with %20 rather than a space)
http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=piers%20anthony
Phrase search http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=%22piers%20anthony%22
Boolean NOT search http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=tangled%20%2Dessential
http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=tangled%20NOT%20essential
Search for an author’s name (using the creator index) http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=creator%3Aanthony
Search both the book and map zones http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book%2Cmap&q=<INSERT SEARCH TERMS>
Limit the search to theses (using the format facet) http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=<INSERT SEARCH TERMS>&l-format=Thesis
Limit the search to items which have been tagged http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=all&q=has%3Atags
Limit the search to items which have been commented on http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=all&q=has%3Acomments
Limit the search to items which were commented on during 7 March 2012 (UTC) * http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=all&q=has:comments commentlastupdated:[2012-03-07T00:00:00Z TO 2012-03-07T23:59:59Z]
Find digitised newspaper articles about markets from the Australasian Chronicle between 1830 and 1840 * http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=newspaper&q=markets date:[1830 TO 1840]&l-title=48

* Note that text after “q=” (for the examples marked with an asterix) needs to be URL encoded before being used by your code. It has not been URL encoded here to preserve readability.

 

Navigating and sorting the results

The relevant part of the URL is shown in bold.

Description Example URL
Get the second page of results http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=blue%20rabbits&s=20
Sort the results with most recent dates first http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=blue%20rabbits&sortby=datedesc

 

Controlling the metadata returned

The relevant part of the URL is shown in bold.

Description Example URL
Get any tags that have been added (does not include tags at the version level) http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=computers+play+chess&include=tags
Get all tags and comments added
including tags and comments at the version level, and a count of tags and comments added for each work and version.
http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=picture&q=H2005.88%2F%E2%80%8B231&include=tags%2Ccomments%2Cworkversions&reclevel=full
Get the response in JSON http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=picture&q=yellow&encoding=json

 

For the query: http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=%22essential%20guide%20to%20Rapunzel%27s%20world%22

The xml response is:

<response>
  <query>"essential guide to Rapunzel's world"</query>
  <zone name="book">
    <records s="0" n="1" total="1">
      <work id="38392547" url="/work/38392547">
        <troveUrl>http://trove.nla.gov.au/work/38392547</troveUrl>
        <title>Tangled : the essential guide to Rapunzel's world / written by Barbara Bazaldua</title>
        <contributor>Bazaldua, Barbara</contributor>
        <issued>2011</issued>
        <type>Book</type>
        <type>Book/Illustrated</type>
        <holdingsCount>10</holdingsCount>
        <versionCount>1</versionCount>
        <relevance score="10.396133">very relevant</relevance>
      </work>
    </records>
  </zone>
</response>

 

Notice that tags, comments, library holdings and other detailed information are not included. To get this information, use the include and reclevel parameters. To find out more about the fields returned for each type of record, check out the documentation for works , newspaper articles or lists. You can choose to receive a JSON response instead of XML, using the “encoding” parameter.

 

2.2 Parameters available when searching

 

Limiting the search

 

Parameter Possible values Required Default Description
zone book, picture, article, music, map, collection, newspaper, list, website, people, all mandatory none Allows searching in a particular zone. Multiple zones can be searched by separating them with a comma. If no zone is specified, an error occurs. To get a faster response, search only the zones you need.
q mandatory The search query. 

Your query can use indexes which let you do things like search for words in the title, or limit your search to items tagged recently. Supported indexes are described here.

l-<facet name> controlled list optional Limit the search results using one of the available facets. e.g. l-format=Book 

Supported facets are described here.

 

Navigating and sorting the results

 

Parameter Possible values Required Default Description
s optional 0 The result number to start from. The first record is zero. Use this to page through a long list of results.
n optional 20 The number of results to return per zone. maximum is 100.
sortby datedesc, dateasc, relevance optional relevance The sort order for the results. Both date of publication and relevance are supported. 

Some information on relevance ranking can be found here.

 

Controlling the metadata returned

 

Parameter Possible values Required Default Description
reclevel full, brief optional brief
include controlled list optional Include optional pieces of information in the records returned, such as tags, comments, holdings and links.
encoding json, xml optional xml Get the response in xml (default) or json. Alternately, specify a HTTP accept content type of application/xml or application/json
callback optional The name of your function to process the json response. We will wrap this around the json response.
facet controlled list optional, repeatable Facets are categories that describe the results for your search. For example, if you ask for the decade facet, the response will include the list of decades your results span across, and how many results are found in each decade. 

You can separate multiple values with commas.

Some facets only apply to certain zones. A maximum number of values will be returned, which varies per facet.

3. Get metadata records

After doing a search, you might be interested in a particular record from the results. A request to get more information about a particular record looks like this: http://api.trove.nla.gov.au/<RECORD TYPE/<ID>

You need to know what type of record you are after, as well as the record id.

  • You can figure out what type of record you want by checking which zone it came from and comparing to the record type table below.
  • The record id can be found in the @id attribute for the search result e.g. <work id=”37757621″>

By default, you will only get a brief metadata record that does NOT include information like tags, comments, full text, library holdings, links etc. If you want this information, you will need to use the reclevel and include parameters which are described below in section 3.3.

For works, to find out where the metadata record originally came from, check the value stored in: work/version/record/metadataSource. Find out more about this element in the documentation for work records.

3.1 Record types

Record type Record description Example Found when searching these zones
work Work (a work is made up of versions, which are made up of records) http://api.trove.nla.gov.au/work/37757621?key=<INSERT KEY> book, picture, (journal) article,  music, map, collection
newspaper Digitised newspaper article http://api.trove.nla.gov.au/newspaper/18342701?key=<INSERT KEY> newspaper
list Public, user created list http://api.trove.nla.gov.au/list/1234?key=<INSERT KEY> list

Read more about the metadata record returned for:

 

3.2 Examples

 

Description Example URL
Get the brief record for a work http://api.trove.nla.gov.au/work/37757621?key=<INSERT KEY>
Get the full metadata record for a work (not including all links, version level records, tags or comments http://api.trove.nla.gov.au/work/37757621?key=<INSERT KEY>&reclevel=full
Get the full record for a work including tags and comments at both the work and version level http://api.trove.nla.gov.au/work/37757621?key=<INSERT KEY>&reclevel=full&include=tags%2Ccomments%2Cworkversions
Get a brief record for a digitised newspaper article, and include the full text of the article http://api.trove.nla.gov.au/newspaper/18342701?key=<INSERT KEY>&include=articletext

 

3.3 Parameters available when requesting a record

 

Parameter name Possible values Required Default Description
reclevel brief, full optional brief Indicates whether to return a full or brief metadata record. 

Can also be used when performing a search

include controlled list optional, repeatable none Values may be separated by commas. 

This parameter is used to include extra information such as:

  • comments or tags
  • newspaper article full text
  • libraries, museums etc that  hold a copy of a work or version

Not all types of information are available for all types of records.

encoding json, xml optional xml Get the response in xml (default) or json. Alternately, specify a HTTP accept content type of application/xml or application/json
callback optional The name of your function to process the json response. We will wrap this around the json response.

 

Possible values for the ‘include’ parameter.

To get a faster response, include only the information you need.

Value Description Applies to content in the following zones
tags
Include any public tags on this item. 

If versions are being returned, include tags on versions as well as tags on works.

book, picture, article, music, map, collection, newspaper, list
comments Include any public comments on this item. 

If versions are being returned, include comments on versions as well as comments on works

book, picture, article, music, map, collection, newspaper, list
lists Include the name and id of any public lists this item belongs to. book, picture, article, music, map, collection, newspaper
holdings Get information on which organisations have a copy of this work or version. 

Returns the organisation’s NUC (ID), the best link to this item in the holding organisation’s system, local ID, call number.

Use the NUC (ID) to look up organisation details such as name, shortname, if open to public.

book, picture, article, music, map, collection
links Return the URLs which appear on the “online” tabs on the work screen for this work. For a work, this is the full list of links that belong to any version included in the work. 

If versions are being returned, include links for specific on versions as well as links on works.

book, picture, article, music, map, collection
subscribinglibs For works/versions known to be accessible through subscription, get the subscribing organisations’ NUC (ID) and for each organisation, a link to access the item through the organisation’s subscription. 

If versions are being returned, include subscribing organisations for each version as well as the full list at the work level.

Use the NUC (ID) to look up organisation details such as name, shortname, if open to public.

book, picture, article, music, map, collection
(but specifically journal articles, book chapters etc loaded from vendors such as Gale and Informit)
workversions Return all versions that make up this work. Works include one or more versions, and versions are made up of one or more records. book, picture, article, music, map, collection
articletext Include the full text of the digitised article. newspaper
years Include a list of years for which digitised articles from this newspaper title appear in Trove none – applies to digitised newspaper titles (see section 4.1)
listitems
Get the brief works, articles, people, external websites that belong to this list. list
all Get all the tags, comments and everything else listed in this table, where available. (This may be a lot of data – do you really want it all?) all

4. Look up associated data

 

4.1. List newspaper titles

A newspaper title is a paper or magazine that published articles included in the Trove “newspaper” zone. For example: The Sydney Morning Herald.

 

4.1.1 Get a list of newspaper titles

A basic query to list all newspaper titles looks like this: http://api.trove.nla.gov.au/newspaper/titles?key=<INSERT KEY>

 

Examples:
Description Example URL
Get the full list of newspaper titles in Trove http://api.trove.nla.gov.au/newspaper/titles?key=<INSERT KEY>
Get the list of newspaper titles in Trove from a particular state http://api.trove.nla.gov.au/newspaper/titles?key=<INSERT KEY>&state=vic
Possible states: nsw, act, qld, tas, sa, nt, wa, vic, national

 

4.1.2 Get information about one newspaper title

When getting information about just one newspaper title, you can also ask for the list of years for this title included in Trove, and for the dates of each issue published in a particular year. Read more about the metadata available for each title.

A basic query to get information about one title looks like this: http://api.trove.nla.gov.au/newspaper/title/<TITLE ID>?key=<INSERT KEY>

 

Examples:
Description Example URL
Get information about a particular newspaper title, using the title id http://api.trove.nla.gov.au/newspaper/title/35?key=<INSERT KEY>
Get the list of years available in Trove for the Sydney Morning Herald http://api.trove.nla.gov.au/newspaper/title/35?key=<INSERT KEY>&include=years
Get the dates the Sydney Morning Herald was issued in 1926 and 1927 http://api.trove.nla.gov.au/newspaper/title/35?key=<INSERT KEY>&include=years&range=19260101%2D19271231

 

Parameters available:
Parameter Possible values Required Default Description
include years optional Return a list of years this title was published (Only lists years included in Trove)
range YYYYMMDD-YYYYMMDD optional If include=years has also been used, then for the given date range, also return a list of dates an issue of this title was published. 

Replace “-” with %2D (URL encoding)

encoding xml, json optional xml Replace “,” with %2C (URL encoding)
callback optional The name of your function to process the response. We will wrap the json response with this function name.

 

4.2. List Trove contributors

Get a list of all Trove contributors, or information about a particular contributor. Individual OAIster and Picture Australia contributors are not included in this list.

 

4.2.1 List all contributors

You can get the full list or search by name or NUC code. By default, you will get only the name and id code of each contributor. To get other information such as short name, catalogue URL, access policy etc, use the parameter reclevel=full.

A basic query to briefly list all contributors looks like this: http://api.trove.nla.gov.au/contributor?key=<INSERT KEY>

 

Examples

 

Description Example URL
Get a list of all Trove contributors in json http://api.trove.nla.gov.au/contributor?encoding=json&key=<INSERT KEY>
Search the list of Trove contributors http://api.trove.nla.gov.au/contributor?q=geoscience&key=<INSERT KEY>

 

Parameters available

 

Parameter Possible values Required Default Description
q optional Search the contributors by name or nuc symbol. (Location may also be searched.)
reclevel brief, full optional brief Get all the details for the contributors, instead of just the name and id.
encoding json, xml optional xml Get the response in xml (default) or json. Alternately, specify a HTTP accept content type of application/xml or application/json.
callback optional The name of your function to process the response. We will wrap the json response with this function name.

 

4.2.2 Get information about one contributor

Use the contributor’s id/nuc code to find out information about just one contributor. By default, you will get only the name and id/nuc code. To get other information such as short name, catalogue URL, access policy etc, use the parameter reclevel=full.

Examples

 

Description Example URL
Get all the information about the contributor whose id is ‘AMG’ http://api.trove.nla.gov.au/contributor/AMG?reclevel=full&key=<INSERT KEY>

 

Parameters available

Parameters available are reclevel, encoding, callback – described in section 4.2.1.

 

5. Appendices

 

5.1 List of supported facets

Facets are categories that describe all the records in a particular result set. For example, if you have 10 results, you can check the format facet to find out that 8 are books and 2 are theses. You could also modify your search to retrieve only the theses, or only the books.

To check a particular facet, ask for it to be included in the search response using the parameter: “facet”. The facet values will then be found under the element: response/zone/facets/facet/term . These values are case-sensitive.
e.g. http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=<INSERT SEARCH TERMS>&facet=format
(Note that in the newspaper zone, year facet values will not be listed unless a decade facet limit is applied to the search e.g. &l-decade=188. Month facet values will not be listed unless a year facet limit is applied e.g. &l-year-1881.)

To limit your search using a facet, use the parameter: “l-<facet name>”
e.g. http://api.trove.nla.gov.au/result?key=<INSERT KEY>&zone=book&q=<INSERT SEARCH TERMS>&l-format=Audio+book

Facet Name Value Description Applicable zones
format controlled list The format of the resource. For example, is it a book or a piece of sheet music? book, picture, article, music, map, collection
decade YYY Publication decade. e.g 199 represents 1990 – 1999. book, picture, article, music, map, collection, newspaper, list
year YYYY Publication year. For newspapers, only available if the decade facet is also applied. book, picture, article, music, map, collection, newspaper, list
month MM Publication month. Only available if the year facet is also applied newspaper
language book, picture, article, music, map, collection
availability y
y/f
y/r
y/s
y/u
Whether the item is online or not. 

y – online
y/f – freely accessible online
y/r – payment, subscription or membership required
y/s – subscription required
y/u – possibly online

book, picture, article, music, map, collection, list 

Replace “/” with %2F (URL encoding)

australian y Works identified as published primarily in Australia, or written by Australians book, picture, article, music, map, collection
occupation collection
zoom Map scale map
vendordb Database code article
vendor GALE
Informit
The vendor who sells subscriptions to access a database containing these articles. article
audience Trade
General
Academic
Professional
Children’s
Children’s — Upper elementry
Children’s — Lower elementry
Only applies to articles from Gale. article
title numeric The newspaper title id. newspaper
category Article
Advertising
Detailed lists, results, guides
Family Notices
Literature
Newspaper article category newspaper
illustrated Y Is a newspaper article illustrated? newspaper
illtype cartoon
illustration
graph
map
photo
Type of illustration for newspaper article. Only available if illustrated facet is applied newspaper
word 0
1
3
Newspaper article word count
0 is less than 100 words
1 is 100-1000 words
3 is more than 1000 words
newspaper
all all

 

5.2. List of supported indexes

Example values  have not been URL encoded, in order to preserve readability. You will need to URL encode them.

Index Example Description Applicable zones
creator creator:(Donald Norman) Includes authors, photographers, illustrators, editors and other contributors.
(For lists, this is the username of the person who created the list.)
book, picture, article, music, map, collection, list
subject subject:(cognitive psychology) book, picture, article, music, map, collection
title title:(short history of Australia) book, picture, article, music, map, collection
s_creator s_creator:(Donald Norman) Stemmed form of the creator. Includes authors, photographers, illustrators, editors and other contributors book, picture, article, music, map, collection
s_subject s_subject:(cognitive psychology) Stemmed form of the subject book, picture, article, music, map, collection
s_title s_title:(short history of Australia) Stemmed form of the title book, picture, article, music, map, collection
exact_creator exact_creator:”public:glowbrain” The username of the person who created the list. The username must include the prefix “public:” for normal user accounts, or no prefix for NLA staff accounts. You only need to use this index if you are searching for lists created by NLA staff members. Otherwise, use the “creator” index instead. Double quotes are needed around the username (including prefix) to escape the colon. list
format format:book The format of the resource. For example, is it a book or a piece of sheet music? The available values are part of a controlled list book, picture, article, music, map, collection
language language:english book, picture, article, music, map, collection
isbn isbn:0333337352 book, picture, article, music, map, collection
issn issn:15386597 book, picture, article, music, map, collection
publictag publictag:(sydney) public tags added by users. Exact match only (searching for “Sydney” doesn’t return results with the tag “Sydney Harbour”) book, picture, article, music, map, collection, newspaper
nuc nuc:QU (Items held by QU but not QU:NET) 

nuc:QU\:NET (Items held by QU:NET. Need to escape the : with a \ )

nuc:QU* (Items held by QU, QU:NET and other NUCs starting with QU)

NUC (id) of an organisation who has a copy of this work book, picture, article, music, map, collection
id id:6311198 work number book, picture, article, music, map, collection
identifier identifier:0333337352 any identifiers included with the work. eg: ISBN, ISSN, ISMN. Doesn’t include local identifiers. book, picture, article, music, map, collection
anbdid anbdid:46285585 Libraries Australia record identifier book, picture, article, music, map, collection
ddc ddc:”791.4372″ Dewey Decimal Classification number book, picture, article, music, map, collection
lastupdated lastupdated:[2012-04-04T00:00:00Z TO *] (items updated since 4 April 2012 UTC) 

lastupdated:[2012-04-04T00:00:00Z TO 2012-04-04T00:00:00Z] (items updated only on the 4 April 2012 UTC)

Find everything that has been added or updated in Trove in a particular time frame. Only dates in or after April 2012 are supported. 

Dates must be in the format yyyy-mm-ddT00:00:00Z

Adding a tag or comment does not flag an item as updated.

UTC timezone is used but during indexing the time is truncated to zero. If you are in New South Wales, Victoria, Tasmania or Queensland, for example, to find everything updated since 12:00pm April 4th 2012, subtract 10 hours (or 11 during daylight savings), truncate the time to zero and use the query lastupdated:[2012-04-04T00:00:00Z TO *]

To find everything only updated between 10am April 4th 2012 EST and 9:59am April 5th 2012 EST, use the query lastupdated:[2012-04-04T00:00:00Z TO 2012-04-04T00:00:00Z]

For digitised newspaper articles (the newspaper zone), user text correction flags an article as updated. New articles are included before they are fully approved. These articles have a status of “coming soon”. They don’t include the full text or a link to view the article in Trove. They may be deleted from Trove. If you want to harvest newspaper articles into your own system, you may prefer to only harvest those added more than a month ago, as most articles which are “coming soon” will be approved within this timeframe. If you do harvest any articles which are “coming soon” you will need to check back later to find out whether they still exist/have been approved/get the Trove link and full text.

book, picture, article, music, map, collection, newspaper, list
taglastupdated taglastupdated:[2012-03-06T00:00:00Z TO *] (items tagged since 6 March 2012 UTC) 

taglastupdated:[2012-03-06T00:00:00Z TO 2012-03-06T00:00:00Z] (items tagged on the 6 March 2012 UTC)

Find everything that has been tagged in Trove in a particular time frame. 

Adding a tag flags the item and it is included in these search results. Deleting a tag does not flag the item.

UTC timezone is used. Only dates in or after March 2012 are supported.

book, picture, article, music, map, collection, newspaper, list
commentlastupdated commentlastupdated:[2012-03-06T00:00:00Z TO *] (items commented on since 6 March 2012 UTC) commentlastupdated:[2012-03-06T00:00:00Z TO 2012-03-06T00:00:00Z] (items commented on on 6 March 2012 UTC) Find everything that has been commented on in Trove in a particular time frame. 

Adding or editing a comment flags the item and it is included in these search results. Deleting a comment does not flag the item.

UTC timezone is used. Only dates in or after March 2012 are supported.

book, picture, article, music, map, collection, newspaper, list
date date:[* TO 1900] (items from 1900 or older) 

date:[2010 TO *] (items from 2010 or more recent)

date:[1850 TO 1890] (items between 1850 and 1890)

date of publication book, picture, article, music, map, collection, newspaper
decade YYY Publication decade. e.g 199 represents 1990 – 1999. book, picture, article, music, map, collection
has has:tags
has:comments
Does this item have any tags or comments? book, picture, article, music, map, collection, newspaper, list
text text:Jackes find items containing the exact word “Jackes” (not “Jack” or “Jacke”) book, picture, article, music, map, collection
fulltext fulltext:Jackes find items containing the exact word “Jackes” (not “Jack” or “Jacke”) newspaper

You may search more than one field at a time. e.g. title:(heat) creator:(neil hargreaves)
You may use boolean logic.
e.g. title:(heat) NOT creator:(neil hargreaves)
e.g. creator:(hargreaves NOT neil)