API technical guide

API 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.

API 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.

 

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&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 worksnewspaper articles or lists. You can choose to receive a JSON response instead of XML, using the “encoding” parameter.

 

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.

 

API 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.

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/38392547?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:

 

Examples

 

Description Example URL
Get the brief record for a work http://api.trove.nla.gov.au/work/38392547?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/38392547?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

 

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

Look up associated data

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.

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

 

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.

 

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.

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.

 

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>

API Work related structured

A work is made up of one or more versions. A version is made up of one or more records.

Fields available in the brief record are also available in the full record.

Work records are based on Dublin Core.

Field Where or how to access this field Description Example value, or list of possible values
work Brief record Container for all other elements describing the work.  
work@id Brief record The Trove work id “123456789″
troveUrl Brief record A link to view this article in the Trove web interface.  
title Brief record The title or name of the work. “Tangled : the essential guide to Rapunzel’s world / written by Barbara Bazaldua”
contributor Brief record The main creator of this work. Some works have multiple creators listed, others have only one even if multiple creators exist. “Bazaldua, Barbara”
issued Brief record The year/s this work was issued, created or published. May also include month and day. May be a range. 

 

YYYY-MM-DD
YYYY-MM
YYYY

YYYY-YYYY

“2011″
“2001-2011″
type Brief record The format of this work. There may be more than one type element. “Book/Illustrated”
See the list of possible format values below.
isPartOf Brief record For articles, the journal or periodical this article belongs to (if known). 

 

@url may include the API access point to get more information about this periodical e.g. “/work/13110632″

“Access”
subject Full record Subjects describe what a work is about. A variety of vocabularies are used, including LCSH

 

More than one subject element may be present.

“Global warming — Health aspects.”
abstract Full record A description, summary, abstract, or first few words of this work, if available. “Damaged rainforest trees in a backyard in Babinda.”
tableOfContents Full record A table of contents for this work, if available. 

 

Where possible, each item is listed on a separate line within the same tableOfContents element.

“<tableOfContents>Executive summary
Introduction
Causes of climate change
Trends and projections of physical changes</tableOfContents>”
language Full record The language/s this work is available in. More than one language element may be present. “English”
wikipedia Full record Links to any known associated wikipedia articles. Includes markup. “Read associated articles: <a href=”http://en.wikipedia.org/wiki/Golomb_coding”> Golomb coding</a>, <a href=”http://en.wikipedia.org/wiki/Incremental_encoding”> Incremental encoding</a>”
holdingsCount Brief record The number of organisations (libraries, archives, etc) who have a copy of this work. “5″
versionCount Brief record A work is made up of one or more versions. This is the number of versions that are grouped together to make up this work. “2″
tagCount Full record Tags can be placed on the work as a whole, or on a particular version that is part of the work. This element shows the number of public tags on this work or any of its versions. There is no way to access private tags through the API. “5″
tagCount@level=”work” Full record The number of public tags on this work (not including tags placed on a particular version.) “4″
commentCount Full record Comments can be placed on the work as a whole, or on a particular version that is part of the work. This element shows the number of public comments on this work or any of its versions. “1″
commentCount@level=”work” Full record The number of public comments on this work (not including comments placed on a particular version.) “0″
listCount Full record The number of public lists this work is in. “1″
tag include=tags A public tag added to the work. There may be more than one tag element. Tags can also be added to a version (the version/tag element). “lightning”
tag@lastupdated include=tags When the tag was added. (UTC timezone) “2011-12-12T15:44:01Z″
comment include=comments A public comment added to the work. There may be more than one comment element. Comments can also be added to a version (the version/comment element). “Have any names been listed as to who is in the photo?”
comment@lastupdated include=comments When the comment was most recently added/edited. (UTC timeszone) “2011-12-09T09:43:00Z”
comment@by include=comments The username of the person who added the comment. “public:bobbyfamilytree”
“rholley” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
comment@rating include=comments An optional rating of the item from 0 to 5 5
list include=lists The name of a public, user created list this work belongs to. There may be more than one list element. “Beacher-Craggs Family”
list@url include=lists A partial URL to retrieve more information about this list using the Trove API. “/list/21922″
list@by include=lists The username of the person who created the list “public:bobbyfamilytree”
“dance” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
list@lastupdated include=lists When the list was most recently added/edited. (UTC timeszone) “2012-02-29T01:02:15Z”
identifier@type=”url”
@linktype=”fulltext”,”restricted”,”unknown”
Brief record includes one URL.
Add “include=links” to access  any other URLs.
If available, the best known link to this work is included automatically in the brief record. 

 

@linktype indicates the type of URL. Possible values are listed below.

@linktext may also be provided.

<identifier type=”url” linktype=”fulltext” linktext=”View online”>http://ebooks.adelaide.edu.au/t/turgenev/ivan/dog/</identifier>
identifier@type=”url”
@linktype=”subscription”
include=subscribinglibs A link to access this work through a particular organisation’s subscription. 

 

@nuc – the NUC symbol for the organisation that has the subscription.

@library – in future will be the API access point for more information about the organisation that has the subscription. e.g. “/library/ABS”

http://trove.nla.gov.au/goto?i=subs&w=151678302&d=VLINK%2Fnuc%3DABS%2Fit...
identifier@type=”url”
@linktype=”thumbnail”
Brief record If available, a link to a thumbnail-sized image representing this item. 

 

Note that book  cover art is not available. It can be sourced separately through services such as Nielsen BookData or Amazon.

http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=282557
holding include=holdings A container element for information about a copy of this work held by a particular organisation (library, archive, etc).  
holding@nuc include=holdings The NUC symbol of an organisation with a copy of this work. 

 

The NUC symbol (ID) can be used to retrieve more information about the organisation.

“NWU”
holding@name include=holdings The name of an organisation which controls a copy of this work. Provided instead of a NUC symbol for organisations which do not have one assigned. “Internet Archive”
holding@library include=holdings In future, this will be the API access point to look up more information about this organisation. “/library/NWU”
holding/url@type=”deepLink”,”catalogue”,”homepage” include=holdings “deepLink” – a link to view this item in the holding institution’s catalogue/website. 

 

“catalogue” – a link to the holding institution’s  catalogue home page.

“homepage” – a link to the organisation’s homepage

The best available link is shown.

http://catalogue.slwa.wa.gov.au/search~S2/i?SEARCH=2268040259
holding/callNumber include=holdings The institution’s call number for their copy of the work. 

 

More than one callNumber may be present.

@localIdentifier is also provided if available. From Libraries Australia MARC records, this is extracted from 850$b

“<.B16766362>”
version include=workversions A container element for a version/edition that is part of this work. Versions usually contain one record but can sometimes contain several.  
version@id include=workversions A string of internal Trove ids for any records that make up this version.  
version/record include=workversions Container element for a Dublin Core record. These records are contributed to Trove from various sources and have often been converted by Trove or the original contributor to Dublin Core from other formats. Only selected child elements are described below.  
version/record/identifier@type=”control number” @source=”OCoLC” include=workversions The OCLC number for this record. “660539373″
version/record/identifier@type=”control number” @source=”AuCNLKIN” include=workversions The Libraries Australia ID for this record. “000046285585″
version/record/metadataSource include=workversions The name of the organisation or aggregating service who contributed this record to Trove. “Libraries Australia” 

 

 

version/record/metadataSource@type=”nuc” include=workversions The NUC symbol of the organisation who contributed this this record to Trove. 

 

The NUC symbol (ID) can be used to retrieve more information about the organisation.

“QCCL”
version/type include=workversions The format of this version. There may be more than one type element. “Book/Illustrated” 

 

See the list of possible format values below.

version/issued include=workversions The date this version was issued/published/created. 

 

YYYY
OR
YYYY-MM
OR
YYYY-MM-DD

“1980-01-31″
version/holdingsCount include=workversions The number of institutions (libraries, archives, etc) who have or control a copy of this work. “1″
version/tagCount@level=”version” include=workversions The number of public tags on this version (not including tags placed at the work level.) “1″
version/commentCount@level=”version” include=workversions The number of public comments on this version (not including comments placed at the work level.) “1″
version/tag include=workversions,tags See documentation for tag above.  
version/comment include=workversions,comments See documentation for comment above.  
version/identifier@type=”url” include=workversions,links A URL associated with this version
 

 

@linktype indicates the type of URL. Possible values are listed below.

(@linktype=”subscription” is not included here.)

 
version/identifier@type=”url” @linktype=”subscription” include=workversions,subscribingLibs Link to access this version via a particular organisation’s subscription. 

 

See documentation for identifier above.

 
version/holding include=workversions,holdings See documentation for holding above.  
       

List of possible formats

  • Archived website
  • Art work
  • Article
    • Article/Abstract
    • Article/Book chapter
    • Article/Conference paper
    • Article/Journal or magazine article
    • Article/Other article
    • Article/Report
    • Article/Review
    • Article/Working paper
  • Audio book
  • Book
    • Book/Braille
    • Book/Illustrated
    • Book/Large print
  • Conference Proceedings
  • Data set
  • Map
    • Map/Aerial photograph
    • Map/Atlas
    • Map/Braille
    • Map/Electronic
    • Map/Globe or object
    • Map/Large print
    • Map/Map series
    • Map/Microform
    • Map/Single map
  • Object
  • Periodical
    • Periodical/Journal, magazine, other
    • Periodical/Newspaper
  • Photograph
  • Poster, chart, other
  • Published
  • Sheet music
  • Sound
    • Sound/Interview, lecture, talk
    • Sound/Other sound
    • Sound/Recorded music
  • Thesis
  • Unpublished
  • Video
    • Video/Captioned

List of possible linktype values

Trove tries to interpret how accessible a link is and whether it leads to the actual item, or something else instead (like a finding aid, a blurb or a related website).  The resulting categories are provided as a guide only, and are not correct in all cases.

Linktype value Trove display label (on brief results screen) Does this URL lead to an online, digital copy of this item? Access conditions?
fulltext “View  online” Yes No
restricted “View online (access conditions)” Yes Yes – payment or membership may be required before the item can be accessed
subscription “View online (access conditions)” Yes Yes – payment or membership may be required before the item can be accessed
unknown “Possibly online” Maybe – Trove is unsure about this link -
notonline - No, it leads to a related item (such as a finding aid) -
thumbnail - No, it leads to a thumbnail representing this item No

API List record structure

Field Where or how to access this field Description Example value, or list of possible values
list Brief record Container for all other elements describing the list.  
list@id Brief record The Trove list id “1234″
list@url Brief record A link to view this list through the Trove API. (Stick it on the end of the api base URL and add your key) “/list/1234″
troveUrl Brief record A link to view this list in the Trove web interface. http://trove.nla.gov.au/list?id=1234
title Brief record The name of the list. List names are not unique. Display them in conjunction with the list creator’s username. “Adelaide Festival of the Arts (1960 – )”
creator Brief record The username of the person who created the list. (Anonymous lists are not allowed.) “public:bobbyfamilytree”
“rholley” (NLA staff accounts do not include the ‘public’ prefix)
listItemCount Brief record The number of items in the list “11″
identifier @type=”url” @linktype=”thumbnail” Brief record A link to a thumbnail image for the list http://nla.gov.au/nla.pic-vn3260737-t
description Brief record (truncated to 120 characters)
Full record (full value)
The description of the list. May be quite long. May contain markup. <p><em>Furioso</em> premiered on 8 July 1993 at the Playhouse, Adelaide Festival Centre. It was choreographed by Meryl Tankard for Meryl Tankard Australian Dance Theatre. The original cast was Prue Lang, Mia Mason, Rachel Roberts, Tuula Roppola, Michelle Ryan, Vincent Crowley, Grayson Millwood, Shaun Parker, Gavin Webber and Steev Zane. It was danced to music by Arvo Part, Elliot Sharp and Henryk Gorecki, and had designs by Regis Lansac.</p>
date@created Full record When the list was created. (UTC timezone) “2009-12-31T13:00:00Z”
date@lastupdated Full record When the list was last changed. (UTC timezone) “2010-09-06T05:07:41Z”
tagCount Full record The number of tags on this list “1″
commentCount Full record The number of comments on this list “0″
tag include=tags A public tag added to the work. There may be more than one tag element. “dance”
tag@lastupdated include=tags When the tag was added. (UTC timezone) “2012-02-29T01:11:10Z”
comment include=comments A public comment on this list. There may be more than one comment element. “I have found this list very valuable as a teaching resource”
comment@by include=comments The username of the person who added this comment. “public:bobbyfamilytree”
“rholley” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
comment@lastupdated include=comments When this comment was created or last edited. “2012-02-29T01:11:19Z”
listItem include=listItems An item that belongs to the list. This may be a work, a digitised newspaper article, a person/organisation, or a link to an external website. 

 

There may be more than one listItem element.

A list item will contain one of the following elements: work, article, externalWebsite, people. It may also contain a note.

 
listItem/note include=listItems A note the creator of the list wrote about this item, such as why they decided to include it, or extra description of the item. “Henry Thomas Byrnes Death Notice”
listItem/work include=listItems brief record for a work that belongs to this list.  
listItem/article include=listItems brief record for a digitised newspaper article that belongs to this list.  
listItem/externalWebsite include=listItems Information about a link to page outside of Trove that has been included in this list.  
listItem/externalWebsite/title include=listItems The name of the webpage (as entered by the creator of the list). “Google”
listItem/externalWebsite/identifier@type=url include=listItems The URL of the webpage. http://google.com.au
listItem/people include=listItems A very brief record for a person or organisation that belongs to this list.  
listItem/people@id include=listItems The Trove id for the person or organisation. “725090″
listItem/people/troveUrl include=listItems A link to view the person or organisation on the Trove website. http://trove-test.nla.gov.au/people/725090

API Newspaper article record structure

Field Where or how to access this field Description Example value, or list of possible values
article Brief record Container element for a newspaper article.  
article@id Brief record Trove newspaper article id. “18341291″
heading Brief record The article heading “Agriculture around Kelvin Grove and Kedron Brook. [BY OUR AGRICULTURAL REPORTER.]“
category Brief record The type of article. Displayed on the Trove web interface as “Category”
  • Article
  • Advertising
  • Detailed lists, results, guides
  • Family Notices
  • Literature
title Brief record The name of the newspaper or periodical this article is found in. “The Queenslander (Brisbane, Qld. : 1866-1939)”
title@id Brief record The Trove id of the newspaper or periodical this article is found in. Can be used to look up more details. e.g. http://api.trove.nla.gov.au/newspaper/title/42?key=<insert key here> “42″
edition Brief record If this article appeared in a special newspaper/periodical edition, the name of that edition is included here. In the Trove web interface, this is shown on the page view.
e.g. http://trove.nla.gov.au/ndp/del/page/4298413
“2, SPECIAL EDITION TO THE QUEANBEYAN AGE”
date Brief record When the issue this article belongs to was published. YYYY-MM-DD 1876-05-27
page Brief record Determine the sequence of delivery of the pages in an issue. “1″
pageSequence Brief record In addition to the page sequence number, indicates if the article is part of a supplement/section (displayed in the Trove web interface) “1 S”
pageLabel Full Record Sometimes used to indicate what is printed on the page, or perhaps the page number within a section/supplement. Not displayed in the Trove web interface. Sometimes numeric and sometimes not. 

 

e.g. http://api.trove.nla.gov.au/newspaper/45649893?reclevel=full&key=<insert key here>

“Front cover”
status Brief record Included if the article is not currently available. Not included for normal articles. 

 

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.

  • “coming soon” (for articles not yet through the QA process)
  • “withdrawn” (for articles that have been removed for copyright reasons)
relevance Brief record, following a search How relevant the article is to the search
  • very relevant
  • likely to be relevant
  • may have relevance
  • limited relevance
  • vaguely relevant
relevance@score Brief record, following a search A numeric representation of how relevant this article is to the search. This number can be compared to other search results in this zone, but not to results from other zones. “0.009942865″
snippet Brief record, following a search A small amount of article text containing one or more of the search terms. The matching term/s are enclosed in a <B> element “… blue-green plumage holding the <B>tangled</B> loops. A very useful dress it composed of a plaided material …”
troveUrl Brief record A link to view this article in the Trove web interface. If this record was retrieved in response to a search, the search terms will be included in the URL which allows them to be highlighted when viewing in the article. 

 

This is not available for articles with a status of “coming soon”.

The persistent id for this article can be found in the identifier element. (It does not support search term highlighting).

http://trove.nla.gov.au/ndp/del/article/18342701″ 

 

OR

http://trove.nla.gov.au/ndp/del/article/18342701?searchTerm=tangled

trovePageUrl Brief record A link to view the first page of this article, in the Trove web interface. This is not available for articles with a status of “coming soon”. http://trove.nla.gov.au/ndp/del/page/2243685
supplement Full record The newspaper/periodical section this article appeared in. In the Trove web interface, this is shown on the page view. A supplement is part of an issue. “Something to do”
section Full record The newspaper/periodical section this article appeared in. In the Trove web interface, this is shown on the page view. A section is part of an issue. 

 

e.g. http://trove.nla.gov.au/ndp/del/page/4824108

“1, Special Home Feature”
illustrated Full record Flags whether the article is illustrated or not “Y”
wordCount Full record The number of words in the full text of the article “1514″
correctionCount Full record The number of corrections made to the article. Each correction may involve many lines. “1″
listCount Full record The number of  public Trove user created lists this article has been added to. “0″
tagCount Full record The number of public tags added to this article by Trove users. “3″
commentCount Full record The number of public comments added to this article by Trove users. “1″
tag include=tags A public tag added to the article. There may be more than one tag element. “fashion”
tag@lastupdated include=tags When the tag was added. (UTC timezone) “2012-02-20T23:57:57Z”
comment include=comments A public comment added to the article. There may be more than one comment element. “Robert Fuy should probably read Robert Fuz”
comment@lastupdated include=comments When the comment was most recently added/edited. (UTC timezone) “2012-02-20T23:57:57Z”
comment@by include=comments The username of the person who added the comment “public:annmanley”
“rholley” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
list include=lists The name of a public, user created list this article belongs to. There may be more than one list element. “Beacher-Craggs Family”
list@url include=lists A partial URL to retrieve more information about this list using the Trove API. “/list/21922″
list@by include=lists The username of the person who created the list “public:bobbyfamilytree”
“dance” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
list@lastupdated include=lists When the list was most recently added/edited. (UTC timeszone) “2012-02-29T01:02:15Z”
lastCorrection Full record Further information about the most recent correction to this article. The correction itself is not included.  
lastCorrection@by Full record The username of the person who made the most recent correction to this article, or “anonymous” “public:maurielyn”
“rholley” (NLA staff accounts do not include the ‘public’ prefix)
“anonymous” (no user account identified)
lastCorrection@lastupdated Full record When the most recent correction was made to this article (UTC timezone) “2011-12-06T18:05:17Z”
identifier Full record The article identifier. This URL leads to the article view on the Trove web interface. http://nla.gov.au/nla.news-article18341291
pdf Full record A link leading to the pdf for the page this article appears on. There may be more than one pdf element if the article appears over multiple pages.
PDFs are not available for some articles, such as the Australian Women’s Weekly, and articles with a status of “coming soon”.
http://trove.nla.gov.au/ndp/imageservice/nla.news-page2243325/print
articleText include=articletext The full text of the article, including all corrections. Article paragraphs are enclosed in a <p> element.  Lines are enclosed by <span>. 

 

Article text is not available for some articles, such as those from the Australian Women’s Weekly, and articles with a status of “coming soon”. For these articles, there will be no articleText element present.

“<p><span>  SHIPPING  INTELLIGENCE.</span></p> <p><span>  Lying  in  Owen’s  Anchorage.-II.M.S.  Pelorus,</span><span>  and  Champion»</span></p>”

The record structure of newspaper titles is documented here. “The Sydney Morning Herald” is an example of a newspaper title.

API Newspaper title record structure

 

Field Where or how to access this field Description Example value, or list of possible values
newspaper   Container element for a newspaper title.  
newspaper@id   ID of the newspaper title. 11
title   Name of the newspaper (or magazine) The Canberra Times (ACT : 1926-1954)
state   The state the newspaper was primarily published in.
  • National
  • ACT
  • New South Wales
  • Northern Territory
  • Queensland
  • South Australia
  • Tasmania
  • Victoria
  • Western Australia
issn   International Standard Serial Number 01576925
troveURL   A link to view this newspaper title in Trove http://trove.nla.gov.au/ndp/del/title/11
startDate   The publication date of the easliest issue of this newspaper available in Trove.

 

YYYY-MM-DD

1926-09-03
endDate   The publication date of the  most recently issue of this newspaper available in Trove.

 

YYYY-MM-DD

1954-12-31
year &include=years A list of the  publication years for this newspaper that are included in Trove  
year@date &include=years YYYY

 

A year this newspaper title was published.

1926
year@issuecount &include=years The number of issues  published in this year. 18
year/issue &include=years&range=YYMMDD-YYMMDD Information about a particular issue of this newspaper  
year/issue@id &include=years&range=YYMMDD-YYMMDD Issue id 3863
year/issue@date &include=years&range=YYMMDD-YYMMDD YY-MM-DD

 

Date this issue was published.

1926-09-03
year/issue@url &include=years&range=YYMMDD-YYMMDD URL to view this issue in Trove http://trove.nla.gov.au/ndp/del/issue/3863

The record structure of newspaper articles is documented here.

API Appendices

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   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
Details lists, results, guides
Family notices
Literature
Newspaper article category newspaper
illustrated   Is a newspaper article illustrated? newspaper
illtype   Type of illustration for newspaper article. Only available if illustrated facet is applied newspaper
word   Newspaper article word count newspaper
all     all

 

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)