Trove API Console

Basic search

Search all categories

https://api.trove.nla.gov.au/v3/result?q=wragge&category=all&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	all	possible values are 'all', 'newspaper', 'magazine', 'image', 'research', 'book', 'diary', 'music', 'people', 'list'
encoding	format of results	json	possible values are 'xml' (default) or 'json'

Search in multiple categories

https://api.trove.nla.gov.au/v3/result?q=wragge&category=book,newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	book,newspaper	separate multiple categorys with commas
encoding	format of results	json	possible values are 'xml' (default) or 'json'

Search in a single category

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json	possible values are 'xml' (default) or 'json'

Change the results format

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query	wragge
category	category(ies) to search in	newspaper
encoding	format of results	json	possible values are 'xml' (default) or 'json'

Change the number of results

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&n=100

parameter	parameter note	value	value note
q	the search query	wragge
category	category(ies) to search in	newspaper
encoding	format of results	json	possible values are 'xml' (default) or 'json'
n	number of results	100	possible values are 0 to 100 (default is 20)

Change the sort order

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&sortby=dateasc

parameter	parameter note	value	value note
q	the search query	wragge
category	category(ies) to search in	newspaper
encoding	format of results	json	possible values are 'xml' (default) or 'json'
sortby	order of results	dateasc	possible values are 'relevance' (default), 'dateasc', 'datedesc'

Get the full metadata for each record

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&reclevel=full

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
reclevel	request additional article metadata	full

Adding reclevel=full adds a number of additional fields to the article metadata, the actual fields added depends on the category. In newspapers and gazettes it adds illustrated, wordCount, correctionCount, tagCount, commentCount, listCount, trovePageUrl, and pdf (which is a link to a PDF of the whole page on which the article is published). In works it adds tagCount, commentCount, and listCount.

Include extra information in each record

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&include=tags&include=comments

parameter	parameter note	value	value note
q	the search query	wragge
category	category(ies) to search in	newspaper
encoding	format of results	json	possible values are 'xml' (default) or 'json'
include	include extra information	tags	possible values include 'tags', 'comments', and 'lists'; repeat parameter for multiple values
include	include extra information	comments	possible values include 'tags', 'comments', and 'lists'; repeat parameter for multiple values

The accepted values for the include parameter differ across categorys, but some values, like 'tags' and 'comments', are consistent. Other examples are included below.

Harvesting a complete result set

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&bulkHarvest=true&s=*

parameter	parameter note	value	value note
q	the search query	wragge
category	category(ies) to search in	newspaper	you can only harvest from one category at a time, so this must be set to a single category such as 'newspaper'
encoding	format of results	json	possible values are 'xml' (default) or 'json'
bulkHarvest	setting this to 'true' ensures that results will stay in the same order when you request subsequent pages; without it results might be duplicated or missing	true
s	supply a resumption token to get the next page of results	*	use '*' for the first request, then replace with the value of nextStart for subsequent results

Three parameters are important when harvesting a complete result set: category must be set to a single category, bulkHarvest set to 'true', and s must be updated after each request with the value of nextStart. Note that the nextStart value will only appear if there is another page of results to download, so you can use it in your loop as a check to see if you've finished.

Searching newspapers or gazettes

Limit results by article category

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-category=Article

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-category	category to include	Article	see Trove help documentation, or use the category facet for full list of possible values

This parameter can be used multiple times, however, this will behave like an AND query and only those articles in all of the specified categories will be returned. So adding &l-category=Article&l-category=Advertising will return zero results, as no articles are in both the 'Article' and 'Advertising' categories.

Limit results by place of publication

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-state=Victoria

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-state	place in which articles were published	Victoria	possible values are 'ACT', 'International', 'National', 'New South Wales', 'Northern Territory', 'Queensland', 'South Australia', 'Tasmania', 'Victoria'

This parameter can be used multiple times. Unlike the category facet, this will behave like an OR query, returning articles published in any of the specified places. So adding &l-state=Victoria&l-state=ACT will return articles published in either Victoria or the ACT.

Limit results by decade

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-decade=192

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-decade	limit to articles from this decade	192	192 includes the years 1920 to 1929

Limit results by year

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-decade=192&l-year=1924

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-decade	limit to articles from this decade	192
l-year	limit to articles from this year (l-decade must also be set)	1924	limit the results to articles from 1924, the l-decade parameter must be set to 192

Limit results by month

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-decade=192&l-year=1924&l-month=3

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-decade	limit to articles from this decade	192
l-year	limit to articles from this year (l-decade must also be set)	1924	limit the results to articles from 1924
l-month	limit to articles from this month (l-decade and l-year must also be set)	3	limit the results to articles from March 1924, possible values are numbers from 1 to 12

Find articles on a specific page of a newspaper

https://api.trove.nla.gov.au/v3/result?q=firstpageseq:1&category=newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	firstpageseq:1	use the firstpageseq index in the query to specify a page number, firstpageseq:1 will find articles on page 1
category	category(ies) to search in (required)	newspaper
encoding	format of results	json

Find newspaper articles within a specific date range

https://api.trove.nla.gov.au/v3/result?q=date:[1942-10-31T00:00:00Z TO 1942-11-30T00:00:00Z]&category=newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	date:[1942-10-31T00:00:00Z TO 1942-11-30T00:00:00Z]	use the date index to specify a date range; the first date in the range is not included in the query, so this example searches for articles from November 1942
category	category(ies) to search in (required)	newspaper
encoding	format of results	json

Find newspaper articles from a particular day

https://api.trove.nla.gov.au/v3/result?q=date:[1942-11-01T00:00:00Z TO 1942-11-02T00:00:00Z]&category=newspaper&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	wragge date:[1942-11-01T00:00:00Z TO 1942-11-02T00:00:00Z]	use the date index to specify a date range; the first date in the range is not included in the query, so this example searches for articles from 2 November 1942
category	category(ies) to search in (required)	newspaper
encoding	format of results	json

Limit to articles with illustrations

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-illustrated=true

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-illustrated	limit to articles with illustrations	true	accepted values are 'true' or 'false'

Limit to articles with photographs

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-illustrated=true&l-illustrationType=Photo

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-illustrated	limit to articles with illustrations	true	accepted values are 'true' or 'false'
l-illustrationType	limit to articles with this type of illustration	Photo	the l-illustrated facet must be set to 'true'; common values include 'Photo', 'Cartoon', 'Map', and 'Illustration', set facet to 'illustrationType' to see all possible values

This parameter can be used multiple times, however, this will behave like an AND query and only those articles with all of the specified illustration types will be returned.

Filter articles by number of words

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&l-wordCount=<100 Words

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
l-wordCount	filter by number of words in the article	<100 Words	accepted values are '<100 Words', '100 - 1000 Words', or '1000+ Words'

Limit to articles with tags (or comments)

https://api.trove.nla.gov.au/v3/result?q=wragge has:tags&category=newspaper&encoding=json&include=tags

parameter	parameter note	value	value note
q	the search query (optional)	wragge has:tags	add has:tags to limit to articles with tags; has:comments will similarly limit to articles with comments
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
include		tags	you need to specifically include tags to see the tag values; change to 'comments' to include any comments

Get the OCRd text for each article

https://api.trove.nla.gov.au/v3/result?q=wragge&category=newspaper&encoding=json&include=articletext

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
include	add additional information to the record	articletext	this adds the full OCRd text to the record, other possible values are 'tags', 'comments'

The OCRd text is return as HTML, so depending on you use you might need to strip the tags out.

Get the number of articles in each category

https://api.trove.nla.gov.au/v3/result?q=%00&category=newspaper&encoding=json&facet=category&n=0

parameter	parameter note	value	value note
q	the search query (optional)	%00	'%00' is an empty search, so will return everything
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
n		0	we don't need results, just the facets, so we can set n to 0
facet	include facet data	category	break down results by category; see the Trove API documentation for a full list of facets

Get the number of articles per year in a decade

https://api.trove.nla.gov.au/v3/result?q=%00&category=newspaper&encoding=json&l-decade=192&facet=year&n=0

parameter	parameter note	value	value note
q	the search query (optional)	%00	'%00' is an empty search, so will return everything
category	category(ies) to search in (required)	newspaper
encoding	format of results	json
n	number of results	0	we don't need results, just the facets, so we can set n to 0
l-decade	set the decade	192	needs to be set to find the totals by year
facet	include facet data	year	break down results by year in the given decade; see the Trove API documentation for a full list of facets

For more examples using the year facet see Visualise Trove newspaper searches over time in the GLAM Workbench.

Searching other categories

Limit to works with a particular format

https://api.trove.nla.gov.au/v3/result?q=weather&category=book&encoding=json&l-format=Thesis

parameter	parameter note	value	value note
q	the search query (optional)	weather
category	category(ies) to search in (required)	book
encoding	format of results	json
l-format	format or type of work	Thesis	see the Trove help documentation for a list of formats

This parameter can be used multiple times, however, this will behave like an AND query and only those articles in all of the specified formats will be returned.

Exclude works with a particular format

https://api.trove.nla.gov.au/v3/result?q=weather NOT format:Book &category=image&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	weather NOT format:Book	by adding NOT format:Book to the query we should filter out books
category	category(ies) to search in (required)	image
encoding	format of results	json

You can use the format index in both the query and as a facet, that means you can say that you don't want works with particular formats. This is handy for filtering out noise.

Limit to works created within a particular date range

https://api.trove.nla.gov.au/v3/result?q=weather date:[* TO 1900]&category=book&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	weather date:[* TO 1900]	using the date index you can specify a range of years; use '*' to indicate the earliest or latest possible dates, this example will return all works published in 1900 or before
category	category(ies) to search in (required)	book
encoding	format of results	json

Limit to works with a thumbnail image

https://api.trove.nla.gov.au/v3/result?q=weather imageInd:thumbnail &category=image&encoding=json

parameter	parameter note	value	value note
q	the search query (optional)	weather imageInd:thumbnail	set imageInd to 'thumbnail' to limit results to works that include a thumbnail link
category	category(ies) to search in (required)	image
encoding	format of results	json

The actual thumbnail link is included in the identifier field with a linktype of 'thumbnail'. To ensure you get all the possible values for identifier you can also add &include=links to your query.

Include metadata from all versions of a work

https://api.trove.nla.gov.au/v3/result?q=wragge&category=image&encoding=json&include=workversions

parameter	parameter note	value	value note
q	the search query (optional)	wragge
category	category(ies) to search in (required)	image
encoding	format of results	json
include	format of results	workversions	include the metadata for each individual version of this work

The way that versions are grouped as works in Trove can be quite confusing. The work level metadata is generally quite consistent, but it can leave out useful metadata that's attached to an individual version. The version metadata is richer, but is also less consistent, so you have to be prepared for some trial and error if you want to extract information from it.

Find works with full text

https://api.trove.nla.gov.au/v3/result?q=weather fullTextInd:y&category=magazine&encoding=json&include=workversions

parameter	parameter note	value	value note
q	the search query (optional)	weather fullTextInd:y	set fullTextInd to 'y' to return only articles with full text
category	category(ies) to search in (required)	magazine
encoding	format of results	json
include		workversions	the full text is buried down in the version-level metadata, so you need to add this parameter if you want to actually get to it

The fullTextInd index seems quite misleading as it includes articles from commercial databases where only a truncated sample of the full text is actually available, and electronic legal deposit works where access to the text is restricted. It would seem better to combine this indicator with a search for "nla.obj" or nuc:ANL:DL to try and limit to resources digitised by the NLA and partners.

Limit to articles from a specific digitised journal (using facets)

https://api.trove.nla.gov.au/v3/result?q=weather&category=magazine&encoding=json&l-title=The bulletin

parameter	parameter note	value	value note
q	the search query (optional)	weather
category	category(ies) to search in (required)	magazine
encoding	format of results	json
l-title	limit to this journal title	The bulletin

There's no controlled list of journal titles to use with this facet, so you probably need to get the values from the web interface.

Limit to articles from a specific digitised journal (using identifiers)

https://api.trove.nla.gov.au/v3/result?q=weather "https://nla.gov.au/nla.obj-68375465"&category=magazine&encoding=json&l-format=Article

parameter	parameter note	value	value note
q	the search query (optional)	weather "https://nla.gov.au/nla.obj-68375465"
category	category(ies) to search in (required)	magazine
encoding	format of results	json
l-format	limit to this format	Article	limit the results to articles so we don't get the records for the periodicals themselves

An alternative to using the title facet is to include the identifier of the parent journal in the q parameter. This is how the Trove Digitised Journals app works.

Find out of copyright or openly licensed photographs

https://api.trove.nla.gov.au/v3/result?q=rights:Free&category=image&encoding=json&include=workversions

parameter	parameter note	value	value note
q	the search query (optional)	rights:Free	see the Trove help documentation for a full list of possible values for rights
category	category(ies) to search in (required)	image
encoding	format of results	json
l-format	format of work	Photo
include		workversions	the rights statements are attached to versions, so to see them you need to ask for the full versions data

This facet only works with records where the copyright status is specified in the record. Some out-of-copyright photographs might be missing from results because their status has not been identified. A search for photos created before 1955 using date[* TO 1954] might find additional out-of-copyright images.

Get facets

Facets break the result set into sections and can provide a useful overview. Note that there are limits on the number of facets returned, so they might not include the whole result set.

Facet results by decade

https://api.trove.nla.gov.au/v3/result?category=all&facet=decade&n=0&encoding=json

parameter	parameter note	value	value note
category	category(ies) to search in (required)	all
encoding	format of results	json
facet	facet to return	decade
n	number of results	0	We just want facets, not the list of results.

Facet results by contributor

https://api.trove.nla.gov.au/v3/result?category=all&facet=partnerNuc&n=0&encoding=json

parameter	parameter note	value	value note
category	category(ies) to search in (required)	all
encoding	format of results	json
facet	facet to return	partnerNuc
n	number of results	0	We just want facets, not the list of results.

Contributors are identified by NUC identifiers.

Get individual records

Article or work identifiers are supplied as part of the url rather than as a query parameter. For example, https://api.trove.nla.gov.au/v3/newspaper/41697877 returns the details of the article with the identifier 41697877.

Get a newspaper or gazette article

https://api.trove.nla.gov.au/v3/newspaper/41697877?encoding=json&reclevel=full&include=articletext,tags,comments

parameter	parameter note	value	value note
encoding	format of results	json
reclevel	amount of detail in record	full
include	include extra information	articletext,tags,comments	include the OCRd text, as well as any tags or comments, in the record

Get a work record

https://api.trove.nla.gov.au/v3/work/1144040?encoding=json&reclevel=full&include=workversions,tags,comments

parameter	parameter note	value	value note
encoding	format of results	json
reclevel	amount of detail in record	full
include	include extra information	workversions,tags,comments	include metadata from all grouped versions, as well as any tags or comments

Get a list

https://api.trove.nla.gov.au/v3/list/43805?encoding=json&reclevel=full&include=listitems

parameter	parameter note	value	value note
encoding	format of results	json
reclevel	amount of detail in record	full
include	include extra information	listitems	include details of all items in the list

You only get the brief record version for each of the list items, so to get extra information, such as OCRd text for a newspaper article, you'll have to request each article individually. Also, the list items are not paginated, so if you have a long list this will return a lot of data.

Get newspaper and gazette titles

There's a bug in the API so that a request for newspaper titles also returns the gazette titles. See the GLAM Workbench for a workaround.

Get a list of all newspaper titles

https://api.trove.nla.gov.au/v3/newspaper/titles?encoding=json

parameter	parameter note	value	value note
encoding	format of results	json

Get a list of all gazette titles

https://api.trove.nla.gov.au/v3/gazette/titles?encoding=json

parameter	parameter note	value	value note
encoding	format of results	json

Get a list of newspapers from a particular state

https://api.trove.nla.gov.au/v3/newspaper/titles?encoding=json&state=vic

parameter	parameter note	value	value note
encoding	format of results	json
state	limit to this state	vic	possible values are 'nsw', 'act', 'qld', 'tas', 'sa', 'nt', 'wa', 'vic', 'national'

Get the number of issues per year for a particular newspaper

https://api.trove.nla.gov.au/v3/newspaper/title/35?encoding=json&include=years

parameter	parameter note	value	value note
encoding	format of results	json
include		years	list the years available on Trove, with the number of issues per year

The newspaper identifier is included in the url as indicated. This example will return details of the Sydney Morning Herald which has an identifier of '35'.

Get details of newspaper issues within a date range

https://api.trove.nla.gov.au/v3/newspaper/title/35?encoding=json&include=years&range=18420101-18421231

parameter	parameter note	value	value note
encoding	format of results	json
include		years	this needs to be included to retrieve the full issue information
range	date range of issues to return	18420101-18421231	dates are in YYYYMMDD format; this example will return details of all issues of the Sydney Morning Herald published in 1842

The issue details include a publication date and a url which redirects to the first page of the issue.

Get magazine and newsletter titles

Although this endpoint is included in the technical documention, as of 23 May 2023 it was returning no results. Hopefully it'll start working soon!

Get a list of all magazine and newsletter titles

https://api.trove.nla.gov.au/v3/magazine/titles?encoding=json

parameter	parameter note	value	value note
encoding	format of results	json

Get Trove contributors

Organisations can be nested under other organisations (as children), this makes the data structure a bit complex.

Get a list of organisations contributing data to Trove

https://api.trove.nla.gov.au/v3/contributor?q=&encoding=json

parameter	parameter note	value	value note
q	search query (optional)		leave blank for everything
encoding	format of results	json

Get full details of an organisation contributing to Trove

https://api.trove.nla.gov.au/v3/contributor/ANL?encoding=json&reclevel=full

parameter	parameter note	value	value note
encoding	format of results	json
reclevel	amount of detail to return	full

The organisation's identifier is included in the url as indicated. This example retrieves details for the National Library of Australia, whose identifier is 'ANL'.