Trove API v3
Info
This is a temporary section of the the GLAM Workbench created to bring together information and examples relating to version 3 of the Trove API. It will probably disappear once the new version is officially released and I reorganise the Trove sections of the GLAM Workbench accordingly.
Release 2 of the Trove API Version 3 beta is now available for testing. See the introductory notes for more details.
Timeline¶
- March 2023: Trove API v3 beta (release 1)
- May 2023: Trove API v3 beta (release 2)
- June 2023: Trove API v3 beta (release 3)
- Mid 2023: Trove API v3 officially released
- Early 2024: Trove API v2 decommissioned
Trove API Console¶
The Trove API Console has been updated to add examples from v3 of the API. It provides many sample queries that you can run and modify without the need for an API key.
Summary of breaking changes¶
Info
This is a work in progress as I work my way through the API changes. Additions are very welcome.
This summary only includes breaking changes – the things you'll need to change in your code before v2 of the API is switched off in early 2024. For a full list of changes see the introduction to the v3 API, and the v3 technical guide.
The release notes don't mention the changes to the JSON responses. In general, the changes flatten the JSON responses by removing top-level wrappers that served no function. This means the way you access data within responses has changed. For example, assuming that you've saved the JSON response as a variable called data
, to access the title of a newspaper article retrieved via the /newspaper/[article id]
endpoint in version 2 you would use:
data["article"]["heading"]
While in version 3 you'd use:
data["heading"]
There are similar changes across all endpoints.
All endpoints¶
- API keys will now automatically expire 12 months after activation! (There will be an option to renew.)
- change
v2
tov3
in the endpoint url! callback
parameter for JSONP removed, use CORS instead- default encoding now JSON not XML (I've been told this is a bug and release 3 will make XML the default again)
/result
endpoint¶
zone
parameter has been replaced withcategory
, possible values are: all, newspaper, magazine, image, research, book, diary, music, people, list; note that in most cases there is no one-to-one correspondence between zones and categories as the boundaries of what's included have changed, for example, the 'newspaper' category includes the contents of both the 'newspaper' and 'gazette' zones- the handling of 'blank' searches has changed –
in version 2 you could use a " " space as a value forrelease 2 of the v3 beta made theq
allowing you to search for everything, this doesn't work in v3beta, however, using the unicode null value,%00
, does seem to workq
(query) parameter optional. This means blank searches are supported without any need for workarounds. - JSON response format changes:
- top-level
response
key removed zone
key changed tocategory
- the meaning of the
name
parameter inside eachcategory
value has change – the old name value can be accessed via thecode
key, whilename
now returns the category's display name.
- top-level
/work/[work id]
endpoint¶
- JSON response format changes:
- top-level
work
key removed
- top-level
/newspaper/[article id]
endpoint¶
- JSON response format changes:
- top-level
article
key removed
- top-level
/newspaper/titles
endpoint¶
- JSON response format changes:
- top-level
response
andrecords
keys removed
- top-level
/newspaper/titles/[title id]
endpoint¶
- JSON response format changes:
- top-level
newspaper
key removed
- top-level
/list/[list id]
endpoint¶
- JSON response format changes:
- top-level
list
key removed – note too that in v2list
returned an array (even though there was only one value), in v3 there is just a single value, not an array; so instead of usingdata["list"][0]["title"]
to get the title of a list, you'll need to usedata["title"]
.
- top-level
contributor
endpoint¶
There are major changes here that aren't mentioned in the release notes. Previously a call to this endpoint without additional parameters just returned a long list of contributors. Now, you need to supply a q
parameter to filter the results.
Release 2 of the v3 API beta made theq
parameter added and required – to do a blank search and get all contributors (ie the v2 behaviour), include theq
parameter with no value, eg:contributor?q=&encoding=json&reclevel=full
q
parameter optional.- JSON response format changes:
- top-level
response
key removed
- top-level
contributor/[NUC]
endpoint¶
- JSON response format changes:
- top-level
contributor
key removed
- top-level
magazine/titles/
endpoint¶
This endpoint was introduced in release 2 of the Trove API v3 beta, however, it's currently returning no results. I've been told this will be fixed in release 3.