Explore our application programming interface (API) help page
Discover how to use The National Archives' API.
Terms and conditions for our application programming interface (API)
The National Archives' API allows developers to query our online catalogue's search engine and database. This page explores how to use this and our terms of use for the API.
Discovery, The National Archives' online catalogue holds more than 37 million descriptions of records held by The National Archives. It also hosts the records descriptions of more than 2,500 archives and institutions across the United Kingdom and around the world.
The information in Discovery is made up of record descriptions from the catalogues of the different archives. Although some of The National Archives’ records have been digitised and can be read online, Discovery can’t search the words within them – only their description and title.
Our application programming interface (API) allows developers to query the search engine and database within the Discovery service application programmatically, and returns results in XML or Json for further processing. The service is offered as a beta with some functionality still to be developed. In the meantime we welcome feedback (via email) on the functionality in this release.
Get access to our API
If you would like access to our API, please contact us via email and include the IP address from which you will be sending requests to our API.
Terms of use
Statement of intent
Our Discovery API is designed to maximise access to the information held in our Discovery service catalogue.
You are welcome to use the information and the images for personal use, educational purposes or commercial use under the Open Government Licence.
Best practice
Do not make an unreasonable number of API calls or use the API in a way which significantly compromises the experience of its other users. As a guideline, you should make no more than 3,000 API calls per day at a rate of no more frequently than one request per second. We may choose to limit the number of API calls more formally in the future.
Please tell us about your use of the API by emailing us a link to your websites and describing how you are using the API service. Also, please provide feedback about your experience of using the API so that we can work to improve the service.
Important information
Please report any concern you have over copyright to us via email.
Terms and conditions
If you make a request to this service you are deemed to have accepted the terms and conditions listed here:
- You may not use The National Archives’ logo on your website without our specific written permission.
- Our Discovery service is still under development. Please do not cache or store any content returned by the API.
- You will not use The National Archives’ content or API service for any illegal or defamatory purpose of any nature. You will not use the API service to juxtapose our content with any illegal or defamatory material of any nature.
- You understand and agree that The National Archives will not provide any technical support services in connection with any use of the API. We do not guarantee availability of the API service.
The National Archives reserves the right to extend or alter these terms and conditions at any time.
Understanding the Discovery service catalogue
Note that the following information relates to the content, metadata and structure of The National Archives’ catalogue dataset; other catalogues and datasets within Discovery may be different.
A little understanding of the structure of the Discovery service catalogue will help with the API methods below. Our catalogue dataset is organised hierarchically to reflect the origin and structure of the records. There are seven levels in the catalogue, ranging from ‘department’ at the top of the tree to pieces and, occasionally items at the bottom:
- Department – a government department, agency or body that creates the records
- Division – administrative section of a department, when appropriate
- Series – the main grouping of records with a common function or subject
- Sub-series – smaller groupings of records with a common function or subject
- Sub sub-series – smaller groupings of records with a common function or subject
- Piece – not a single piece of paper: a piece can be a box, volume or file
- Item – part of a piece: can be a bundle, a single document, a letter, and so on
Every level of description in the hierarchy is described within a catalogue entry according to the international standard ISAD (G). The dataset follows its rules for multi-level catalogues (specificity, relevancy, hierarchy position and non-repetition of information at different levels).