Discovery for developers: about the application programming interface (API)

To access our API help page please click here.

If you would like access to our API, please contact us and include the IP address from which you will be sending requests to our API.

Discovery holds more than 32 million descriptions of records held by The National Archives and more than 2,500 archives and institutions across the United Kingdom, as well as a smaller number of archives around the world.

The information in Discovery is made up of record descriptions provided by or derived 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 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 on the functionality in this release.

Terms of use

Statement of intent

Our Discovery application programming interface (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

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.

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.

Report any concern you have over copyright to us.

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:

  1. Department – a government department, agency or body that creates the records
  2. Division – administrative section of a department, when appropriate
  3. Series – the main grouping of records with a common function or subject
  4. Sub-series – smaller groupings of records with a common function or subject
  5. Sub sub-series – smaller groupings of records with a common function or subject
  6. Piece – not a single piece of paper: a piece can be a box, volume or file
  7. 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).